cosmos

基于Mixture-of-Transformers的统一世界模型平台，支持语言、图像、视频、音频和动作序列的联合处理与生成。NVIDIA官方出品，提供Reasoner（理解推理）和Generator（生成仿真）两种模式，专为机器人、自动驾驶等Physical AI场景设计，附带微调、评估、数据蒸馏等完整生态工具。模型有16B/64B两档，支持多种集成方式（Diffusers/vLLM/NIM），是目前开源世界中兼顾理解与生成的少有方案。

README

Cosmos

NVIDIA Cosmos

网站 | 框架

介绍

NVIDIA Cosmos 是一个开放的世界模型、数据集和工具平台，使开发者能够为机器人、自动驾驶车辆、智能基础设施等构建物理 AI（Physical AI）。

Cosmos 3

Cosmos 3 是我们最新的模型家族 [报告] [网站]。它是一套全模态世界模型（omnimodal world models），设计在统一的 Mixture-of-Transformers 架构中联合处理和生成语言、图像、视频、音频和动作序列。通过支持高度灵活的输入-输出配置，它无缝统一了物理 AI 的关键模态——有效地将视觉语言模型、视频生成器、世界模拟器和世界动作模型整合到一个框架中。

Cosmos 3 提供两种运行时表面：

表面	输入	输出	用例
推理器 (Reasoner)	文本、视觉	文本	世界理解、基础、物理推理、任务规划、动作预测、具身代理推理、自主系统决策
生成器 (Generator)	文本、视觉、声音、动作	视觉、声音、动作	世界生成、世界模拟、未来预测、合成数据生成、策略学习、机器人训练

核心能力

世界理解： 分析视频和图像，生成描述、时序事件、下一步动作、空间基础、物理合理性和因果结果。
世界生成： 从文本、图像、视频或动作输入生成图像、视频、同步声音以及动作条件化的推演。
动作建模： 为机器人、相机运动、第一人称运动和自动驾驶场景预测策略动作、逆动力学和正动力学。
研究与生产路径： 使用 Diffusers 和 Transformers 进行 Python 优先的开发，然后使用 vLLM-Omni 和 vLLM 提供 OpenAI 兼容的服务。
后训练配方： 使用 Cosmos Framework 训练配方和针对特定任务的评估来适配视觉、动作和推理工作流 [即将推出]。

模型架构

Cosmos 3 模型架构

Cosmos 3 是一个全模态世界模型，构建在统一的 Mixture-of-Transformers (MoT) 架构上，该架构结合了一个用于推理的自回归 (AR) transformer 和一个用于多模态生成的扩散 transformer (DM)。在推理模式 (Reasoner Mode) 下，语言和视觉理解 token 通过因果自注意力进行处理，实现下一个 token 预测，适用于感知、规划和世界推理等任务。在生成模式 (Generator Mode) 下，带噪声的图像、视频、音频和动作 token 通过全注意力进行去噪，使模型能够联合生成一致的多模态输出。两种模式共享相同的 transformer 架构、多模态注意力层以及统一的 3D 多维旋转位置嵌入 (mRoPE) 表示，该表示编码了跨模态的空间和时间结构，从而能够对图像、视频、音频流和动作轨迹进行一致的推理。

模型家族

模型	参数量	核心能力
Cosmos3-Nano	16B	紧凑的全模态世界模型，用于多模态理解、世界模拟、未来预测、动作推理和物理 AI。
Cosmos3-Super	64B	前沿规模的全模态世界模型，用于高级多模态理解、世界模拟、未来预测、动作推理和物理 AI。
Cosmos3-Super-Text2Image	64B	高保真文本到图像生成。
Cosmos3-Super-Image2Video	64B	时序一致的图像到视频生成。
Cosmos3-Nano-Policy-DROID	16B	用于 DROID 操作和控制的视觉语言机器人策略。

支持的生成设置

设置	支持的值
分辨率等级	256p, 480p, 720p, 默认=480p
宽高比	16:9, 4:3, 1:1, 3:4, 9:16, 默认=16:9
帧率	10, 16, 24, 30 FPS, 默认=24
帧数	5 到 300 帧, 默认=189
精度	BF16 经过测试
操作系统	Linux
GPU 架构	NVIDIA Ampere, Hopper, Blackwell

输入与输出

规格	值
输入类型	文本、文本+图像、文本+视频、文本+图像+动作
输入格式	文本字符串、JPG/PNG/JPEG/WEBP 图像、MP4 视频、JSON 动作数组
视觉条件	720p 使用 1280x720，480p 使用 832x480，256p 使用 320x192。视频条件使用 5 帧对应分辨率。
动作条件	支持的动作维度取决于具体形态，包括相机运动 (9D)、自动驾驶 (9D)、第一人称运动 (57D)、单臂机器人 (10D, DROID/UR/Fractal/Bridge/UMI)、双臂机器人 (20D, 双 DROID 臂)、人形机器人 (29D, AgiBot)。
输出类型	图像、视频、声音、动作状态、文本
输出格式	JPG 图像、MP4 视频、合入 MP4 的 AAC 音频流、JSON 动作值、文本字符串
提示长度	世界生成提示建议少于 300 词
声音输出	与视频一起生成时，48 kHz 立体声 AAC

用例

生成器

生成器示例产生由文本、视觉和动作输入条件化的非文本输出。

工作流	输入	输出	演示内容
文本到图像	文本	视觉	根据文本提示生成机器人实验室场景
文本到视频	文本	视觉	根据密集场景描述生成工业视频
文本到视频（带声音）	文本	视觉、声音	同步的视觉和音频生成
图像到视频	文本、图像	视觉	从起始图像和提示生成机器人操作动画
图像到视频（带声音）	文本、图像	视觉、声音	图像条件化运动与同步音频
视频到视频	文本、视频	视觉	根据提示对机器人操作视频进行变换
视频到视频（带声音）	文本、视频、声音	视觉、声音	根据提示对机器人操作视频进行变换
正动力学	文本、视觉、动作	视觉	从动作和视觉上下文进行未来状态推演
动作策略	文本、视觉	动作、视觉	从上下文生成动作轨迹和推演视频

生成器提示上采样（prompt upsampling）将简短的场景描述扩展为密集的结构化提示。当前示例使用以下采样默认值：

参数	值
`max_tokens`	`20000`
`temperature`	`0.7`
`top_p`	`0.8`
`top_k`	`20`
`repetition_penalty`	`1.0`
`presence_penalty`	`1.5`
`seed`	`3407`

推理器

推理器示例从文本和视觉输入产生文本输出。它遵循 Qwen3-VL 兼容的消息约定来处理图像和视频输入。

工作流	输入	输出	演示内容
描述	视频	文本	详细的视频描述
时间定位	视频、查询	文本或 JSON	事件检测、时间戳查询和区间问答
具身推理	视频、问题	文本	机器人和辅助任务场景下的下一步动作预测
常识推理	视频、问题	文本	基于可见上下文的物理常识判断
2D基础	图像、提示	JSON 框	根据图像提示进行边界框定位
描述任意对象	图像、标记的目标	JSON 或文本	对标记目标的属性描述
动作链式思维	图像或视频、提示	文本或 JSON	轨迹预测和驾驶场景的链式思维
物理合理性分析	视频、提示	标签	物理合理性分类
场景理解	视频、问题	文本	场景理解和下一步可能动作预测

推理器示例使用以下采样设置：

参数	无推理	有推理
`top_p`	`0.8`	`0.95`
`top_k`	`20`	`20`
`repetition_penalty`	`1.0`	`1.0`
`presence_penalty`	`1.5`	`0.0`
`temperature`	`0.7`	`0.6`

文本+视觉请求使用以下基本消息结构：

[
  {
    "role": "system",
    "content": [{"type": "text", "text": "你是一个有用的助手。"}]
  },
  {
    "role": "user",
    "content": [
      {"type": "video_url", "video_url": "https://example.com/video.mp4"},
      {"type": "text", "text": "列出值得注意的事件及其大约时间戳。"}
    ]
  }
]

要明确要求推理，请在用户提示后附加以下格式指令：

请使用以下格式回答问题：

<think>
你的推理过程。
</think>

在 </think> 标签后立即写出你的最终答案。

快速开始

在运行示例之前，创建一个 Hugging Face 访问令牌，然后在本地进行身份验证：

uvx hf@latest auth login

如果要使用共享缓存或更大磁盘，请设置 HF_HOME。

Diffusers 生成器

展开 Diffusers 生成器的设置、示例和模式

使用 HuggingFace Diffusers 进行 Cosmos 3 生成器的研究、训练和模型开发。此路径加载完整的 Cosmos 3 检查点，包括推理器路径、扩散生成路径和媒体 tokenizer。

uv venv --python 3.13 --seed --managed-python
source .venv/bin/activate
uv pip install --torch-backend=auto \
  "diffusers @ git+https://github.com/huggingface/diffusers.git" \
  accelerate \
  av \
  cosmos_guardrail \
  huggingface_hub \
  imageio \
  imageio-ffmpeg \
  torch \
  torchvision \
  transformers

--torch-backend=auto 让 uv 检测您的 NVIDIA 驱动并安装匹配 CUDA 版本的 torch/torchvision。如果没有此选项，uv 会拉取最新的 CUDA wheel（目前是 cu130），这在 CUDA 13 之前的驱动上会失败，并显示 The NVIDIA driver on your system is too old 且 torch.cuda.is_available() 返回 False。如果您愿意，也可以固定一个显式的后端，例如使用 --torch-backend=cu128 用于 CUDA 12.8 驱动。

text-to-video 运行需要一些时间：首次运行会下载 Cosmos3-Nano，并且扩散过程计算量大，在产生输出之前会执行所有推理步骤。较长的步骤时间属于正常现象，不是卡死。

import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano",
    torch_dtype=torch.bfloat16,
    device_map="cuda",
)
pipe.scheduler = UniPCMultistepScheduler.from_config(pipe.scheduler.config, flow_shift=10.0)

result = pipe(
    prompt="一个移动机器人在仓库过道中导航，并在一个货架前停下。",
    negative_prompt="",
    image=None,
    num_frames=189,
    height=720,
    width=1280,
    fps=24,
    num_inference_steps=35,
    guidance_scale=6.0,
    enable_sound=False,
    add_resolution_template=False,
    add_duration_template=False,
    generator=torch.Generator(device="cuda").manual_seed(1234),
)

export_to_video(result.video, "cosmos3_t2v.mp4", fps=24, macro_block_size=1)

Diffusers 模式：

模式	用途
`text-to-image`	单帧图像生成，使用 `num_frames=1`；返回 PIL 图像
`text-to-video`	视频生成；189 帧在 24 FPS 下约为 7.9 秒
`image-to-video`	基于输入图像条件化的视频生成
`text-to-video-with-sound`	对于包含声音模块的检查点，生成带有声音的视频

有关每种模式的可运行示例，请参阅 Cosmos 3 Diffusers 文档。

vLLM-Omni 生成器

展开 vLLM-Omni 生成器的设置、端点和请求参考

使用 vLLM-Omni 进行生成器的生产推理，背后是 OpenAI 兼容的 API。此集成加载完整的 Cosmos 3 检查点，包括基于 Qwen3-VL 的推理器路径和扩散生成路径。对于仅返回文本的理解任务，请改用 vLLM 推理器，它只加载推理器。

兼容性状态： Cosmos 3 生成器支持已合入 vllm-project/vllm-omni main 分支：文本到图像、文本到视频、图像到视频 (#3454) 以及带声音的视频 (#4073) 已合并；动作（策略/正动力学）正在审核中 (#4102)，视频到视频正在规划中。vllm/vllm-omni:cosmos3 Docker 镜像仍然是最简单的全合一构建。有关当前设置和按模态的使用方法，请参阅维护的配方：Cosmos3-Nano 和 Cosmos3-Super。

从 Docker 镜像启动服务器（所有模态）。挂载包含您希望服务器读取的本地媒体或动作文件的任何目录。

docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v "$(pwd):/workspace" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-omni:cosmos3 \
  vllm serve nvidia/Cosmos3-Nano \
  --omni \
  --model-class-name Cosmos3OmniDiffusersPipeline \
  --allowed-local-media-path / \
  --port 8000 \
  --init-timeout 1800

Cosmos3 检查点可能超过默认的服务器初始化超时时间；在本节中的每个 vllm serve 命令上使用 --init-timeout 1800。

当 API 就绪时，vLLM-Omni 会打印 Application startup complete.

对于 nvidia/Cosmos3-Super（更大的 64B 模型），跨 GPU 拆分权重并可选择卸载层以减少峰值内存：--tensor-parallel-size 跨多个 GPU 拆分模型权重，--enable-layerwise-offload 在 CPU 和 GPU 之间卸载 transformer 块，这会带来延迟权衡并消耗额外的 CPU RAM。例如，在四个 GPU 上，在 vllm serve 命令中添加 --tensor-parallel-size 4 --enable-layerwise-offload --init-timeout 1800。

其他并行选项：

选项	用途
`--cfg-parallel-size 2`	在两个 GPU 上并行运行正负 CFG 分支。使用请求级别的 `guidance_scale` 设置 CFG 强度；不要使用 `true_cfg_scale`。
`--ulysses-degree 2`	启用 Ulysses 序列并行，跨 GPU 拆分序列维度。

组合并行选项时，请确保服务器拥有足够数量的 GPU，以满足已启用度的乘积（tensor_parallel_size × cfg_parallel_size × ulysses_degree）。

要安装来自 main 分支的 vLLM-Omni，而不是使用 Docker 镜像（文本到图像、文本到视频、图像到视频和带声音的视频已合并；请参阅 Cosmos3-Nano 和 Cosmos3-Super 配方了解按模态的使用方法），创建一个 venv 并安装，选择与您的驱动匹配的 CUDA 构建：

uv venv --python 3.13 --seed --managed-python
source .venv/bin/activate
# CUDA 13 驱动:
uv pip install --torch-backend=cu130 \
  "vllm-omni @ git+https://github.com/vllm-project/vllm-omni.git@main"
# CUDA 12.8 驱动:
# uv pip install --torch-backend=cu128 \
#   "vllm-omni @ git+https://github.com/vllm-project/vllm-omni.git@main"

然后直接运行 vllm serve nvidia/Cosmos3-Nano --omni --model-class-name Cosmos3OmniDiffusersPipeline --allowed-local-media-path / --port 8000 --init-timeout 1800，无需 docker run ... vllm/vllm-omni:cosmos3 包装。

视觉端点：

模式	端点	备注
文本到图像	`POST /v1/images/generations`	返回 base64 编码的 PNG
文本到视频	`POST /v1/videos/sync`	阻塞并直接返回 MP4 字节
图像到视频	`POST /v1/videos/sync`	使用 `input_reference` 上传条件图像
视频到视频	`POST /v1/videos/sync`	上传源视频，选择哪些帧保留为干净条件
带声音的视频	`POST /v1/videos/sync`	添加 `generate_sound=true` 以生成配乐

动作模式将 Cosmos 3 用作世界模型：它们以某个形态（domain_name）为条件，并交换视频和动作序列。策略和逆动力学返回预测的动作块，因此通过异步 POST /v1/videos 作业发送它们，并从完成的结果中读取动作数据；正动力学只返回视频，可以使用同步 POST /v1/videos/sync。

模式	`action_mode`	输入	输出
策略	`policy`	图像 + 指令	视频 + 预测动作块
逆动力学	`inverse_dynamics`	视频 + 指令	视频 + 预测动作块
正动力学	`forward_dynamics`	图像 + 动作块	视频

通过 extra_params 传递形态设置：action_mode、domain_name（例如 bridge_orig_lerobot、av 或 camera_pose）、raw_action_dim 和 action_chunk_size。正动力学还需要一个 action_path，指向服务器可以读取的动作文件，因此启动服务器时使用 --allowed-local-media-path 覆盖该文件（对于 Docker，挂载文件并传递容器可见的路径）。有关机器人、自动驾驶和相机姿态变体的完整列表，请参阅 Cosmos 3 vLLM-Omni 配方。

视频请求示例：

curl -sS -X POST http://localhost:8000/v1/videos/sync \
  --form-string "prompt=一个小型仓库机器人正在干净的地板上移动一个蓝色箱子。" \
  --form-string "negative_prompt=模糊、变形、低质量" \
  --form-string "size=1280x720" \
  --form-string "num_frames=189" \
  --form-string "fps=24" \
  --form-string "num_inference_steps=35" \
  --form-string "guidance_scale=6.0" \
  --form-string "flow_shift=10.0" \
  --form-string "seed=0" \
  --form-string 'extra_params={"use_resolution_template":false,"use_duration_template":false,"guardrails":true}' \
  -o cosmos3_t2v_output.mp4

对于文本字段（prompt、negative_prompt、extra_params），使用 --form-string 而不是 -F：使用 -F 时，curl 会将 ; 视为内容类型分隔符，并静默截断任何包含 ; 的值。

常见请求字段（图像端点遵循 Image Generation API，视频端点遵循 Videos API）：

字段	用途
`prompt`	正向文本提示
`negative_prompt`	要避免的概念或伪影
`size`	输出分辨率，格式为 `<宽>x<高>`
`num_frames`、`fps`	视频长度和帧率（仅视频端点）
`num_inference_steps`	扩散去噪步数
`guidance_scale`	无分类器引导尺度（请为 Cosmos 3 CFG 使用此字段；不要使用 `true_cfg_scale`）
`flow_shift`	调度器的 flow-shift 值
`seed`	可复现种子
`max_sequence_length`	保留用于条件化的最大提示 token 数量（Cosmos 3 默认 `512`）；较长的提示会被截断并发出警告，较短的会填充
`input_reference`	为图像到视频、视频到视频和动作请求上传的图像或视频
`extra_params`	JSON 编码的 Cosmos 3 特定选项：动作设置（`action_mode`、`domain_name`、`raw_action_dim`、`action_chunk_size`、`action_path`）、视频到视频条件化（`condition_frame_indexes_vision`、`condition_video_keep`）、提示模板开关（`use_resolution_template`、`use_duration_template`）以及每个请求的 `guardrails` 开关
`extra_args`	JSON 对象，用于 Cosmos 3 图像端点的特定选项，例如 `use_resolution_template`

禁用护栏：Cosmos 3 内置了安全护栏，用于检查提示并在生成的输出中模糊人脸。可以通过在 extra_params 中添加 guardrails: false 在每个请求中禁用它：

curl -sS -X POST http://localhost:8000/v1/videos/sync \
  --form-string "prompt=一个小型仓库机器人正在干净的地板上移动一个蓝色箱子。" \
  --form-string 'extra_params={"guardrails":false,"use_resolution_template":false,"use_duration_template":false}' \
  -o cosmos3_t2v.mp4

要在服务器范围内禁用护栏，使其永远不会加载护栏模型（这样按请求的覆盖也无法重新启用它们），请传递一个部署配置——未来版本将用专用的 --cosmos3-no-guardrails 标志替换此配置：

# no_guardrails.yaml
async_chunk: false
stages:
  - stage_id: 0
    max_num_seqs: 1
    enforce_eager: true
    trust_remote_code: true
    model_class_name: Cosmos3OmniDiffusersPipeline
    model_config:
      guardrails: false
      offload_guardrail_models: false

vllm serve nvidia/Cosmos3-Nano --omni \
  --model-class-name Cosmos3OmniDiffusersPipeline \
  --deploy-config no_guardrails.yaml \
  --port 8000 \
  --init-timeout 1800

参考：

Transformers 推理器

即将推出！

vLLM 推理器

使用 vLLM 进行推理器的生产推理，背后是 OpenAI 兼容的聊天补全 API。

uv venv --python 3.13 --seed --managed-python
source .venv/bin/activate
uv pip install --torch-backend=cu130 "vllm==0.21.0" \
  "vllm-cosmos3 @ git+https://github.com/NVIDIA/cosmos-framework.git#subdirectory=packages/vllm-cosmos3"

vLLM 版本和 torch 后端是配对的：对于 CUDA 13 驱动使用 --torch-backend=cu130 "vllm==0.21.0"，对于 CUDA 12.8 使用 --torch-backend=cu128 "vllm==0.19.1"。vLLM 不会为每个 CUDA 次要版本发布 wheel，因此 --torch-backend=auto 在这里不可靠——请选择与您的驱动匹配的配对。

vllm serve nvidia/Cosmos3-Nano \
  --hf-overrides '{"architectures": ["Cosmos3ReasonerForConditionalGeneration"]}' \
  --async-scheduling \
  --allowed-local-media-path / \
  --port 8000

有关 notebook 启动命令（Cosmos3-Super 在四个 GPU 上、媒体路径默认值以及完整标志集），请参阅 cookbooks/cosmos3/README.md — 启动服务器。

如果您的 vLLM 构建报告 DeepGEMM 不可用，请在启动服务器前禁用它：

export VLLM_USE_DEEP_GEMM=0

配置说明：

选项	用途
`--tensor-parallel-size`	用于张量并行推理的 GPU 数量
`--mm-encoder-tp-mode data`	多模态工作负载中视觉编码器的数据并行
`--media-io-kwargs '{"video": {"num_frames": -1}}'`	允许处理器在下游帧采样之前考虑所有可用帧
`--allowed-local-media-path`	当请求传递本地 `file://` 媒体路径时需要

NIM 推理器

展开 NIM 推理器的设置、容器启动和请求参考

使用 Cosmos 3 Reasoner NIM 以获得最快路径，部署生产级、OpenAI 兼容的推理器端点。NIM 提供了预构建、优化的容器，因此您可以跳过上述 vLLM 依赖和 CUDA 配对设置；它从文本、图像和视频输入生成文本输出。

您可以在浏览器中交互式地试用 cosmos3-nano-reasoner 构建页面上的沙盒——该沙盒正是由同一个 NIM 驱动。有关完整的请求参考，请参阅 Cosmos Reason 3 NIM API 参考。

容器提供两种规模，通过 NIM_MODEL_SIZE 选择：

`NIM_MODEL_SIZE`	提供的模型名称
`nano` (默认)	`nvidia/cosmos3-nano-reasoner`
`super`	`nvidia/cosmos3-super-reasoner`

启动 NIM 容器（此处显示 Nano；要使用 Super，设置 -e NIM_MODEL_SIZE=super）。首先必须在环境中设置 NGC_API_KEY——从 NGC 生成一个，并将 Docker 登录到 nvcr.io 一次（docker login nvcr.io，用户名 $oauthtoken，密码 = 您的密钥）。

export CONTAINER_NAME="nvidia-cosmos3-reasoner"
export IMG_NAME="nvcr.io/nim/nvidia/cosmos3-reasoner:1.7.0"
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"

docker run -it --rm --name=$CONTAINER_NAME \
  --runtime=nvidia \
  --gpus all \
  --shm-size=32GB \
  -e NGC_API_KEY=$NGC_API_KEY \
  -e NIM_MODEL_SIZE=nano \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -u $(id -u) \
  -p 8000:8000 \
  $IMG_NAME

然后 OpenAI 兼容的 API 在 http://127.0.0.1:8000/v1 可用。使用 curl 查询：

curl -X POST 'http://127.0.0.1:8000/v1/chat/completions' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nvidia/cosmos3-nano-reasoner",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手。"},

开源项目NVIDIA2026-06-05原文

打开互动版