NVIDIA Cosmos 教學手冊

這份手冊把 nvidia/cosmos 從「Physical AI 入口 hub」拆成可讀、可實作、可資安審查的內部知識文件。 對應 gh-save metadata 報告：inbox/2026-06-02-github-nvidia-cosmos.md 對應姊妹文件（NVIDIA 生態系）：inbox/2026-06-02-tutorial-Nemotron.md

目錄

1. 專案定位
2. 安裝指南
3. 核心架構解析（含 mermaid 圖）
4. Helper Scripts 與 Cookbook Notebook 詳細用法
5. 應用場景（機器人 / 自駕 / 合成資料 / 影音生成）
6. 資安掃描報告
7. FAQ
8. 進階技巧
9. 整合進 NVIDIA AI 工作流（Nemotron / Nemotron-Labs-Diffusion / alpamayo）
10. 重點摘要 Checklist
11. 進一步閱讀

1. 專案定位

1.1 這是什麼

NVIDIA Cosmos 是 NVIDIA 為 Physical AI（實體 AI） 推出的 World Foundation Model（WFM；世界基礎模型） 開放平台。

「Physical AI」與「Digital AI」最大差別：

• Digital AI（如純 LLM）只在 token 空間活動，不需要對「物理世界怎麼動」有正確理解
• Physical AI（機器人、自駕車、無人機、家用機器手臂）必須預測物理世界的演化——拿起一個杯子會不會打翻？輪胎在濕地會不會打滑？人物在路口會不會走出來？

World Foundation Model 就是回答這類問題的基礎模型：給定當前場景（影像 / 影片 / 動作），預測「下一秒會發生什麼」（next frame / next observation / next action）。

Cosmos 3（2026-05-31 釋出）把這件事推到 omnimodal：單一 MoT 模型同時理解與生成「文字 / 影像 / 影片 / 音訊 / 動作」五種 modality，並暴露兩個 runtime surface：

也就是「拿同一個底層模型，既當 VLM 用（看影片回答問題），又當 world simulator 用（生成假影片）」。

1.2 Cosmos 模型家族總覽

Cosmos 3 之前還有 v0.1（tokenizer，2024-11）與 v1.0（diffusion + AR WFM，2025-01）。Cosmos 3 是第一次把所有路徑統一到 MoT。

1.3 在 NVIDIA Physical AI / AI 生態系中的位置

Cosmos 不是孤立專案；它是 NVIDIA AI 棧的**「世界模型層」**，與其他三個 NVIDIA 大旗艦專案各司其職：

「Nemotron 與 Cosmos 同時是 NVIDIA 兩大旗艦基礎模型家族」這件事是理解 NVIDIA 2026 開源策略的關鍵：Nemotron 負責語言與推理、Cosmos 負責物理世界與動作，兩者透過 NeMo 全家桶（Curator / RL / Bridge / DataDesigner / NIM）共享資料、訓練與部署管線。

1.4 統計資料快照（2026-06-02）

與 Nemotron（1,200 stars / 264 forks）相比，Cosmos 的 8,410 stars 顯示 Physical AI 主題對外熱度更高；但 Cosmos repo 結構簡潔（只有 cookbooks/），主邏輯都在 cosmos-framework 與 HuggingFace 權重，所以 codebase 規模反而較小。

2. 安裝指南

Cosmos 安裝的關鍵字是「選 backend」——你的 use case 決定要走哪一條安裝路徑，不需要全部都裝。

2.1 環境需求（通用）

• 作業系統：Linux（Cosmos 沒測 Windows / macOS GPU 路徑）
• GPU：NVIDIA Ampere / Hopper / Blackwell（A100 / H100 / H200 / RTX PRO 6000 Blackwell / RTX 5090）
• CUDA driver：CUDA 13（建議）或 12.8——driver 與 PyTorch CUDA major version 必須一致
• Python：3.13（NVIDIA 官方範例都用 3.13）
• 包管理：uv（強制 — Cosmos Framework 在 pyproject.toml 內 enforce uv >= 0.11.3）
• HuggingFace token：模型 gated，必須先 uvx hf@latest auth login 或 export HF_TOKEN=<token>
• 磁碟：venv + uv cache + 模型 cache 可能吃掉數十 GiB

2.2 五種 Backend 怎麼選

Cosmos 3 cookbooks 支援 5 個 backend，依「研究 vs production」與「reasoner vs generator」分流：

2.3 CUDA / vLLM 版本配對（要小心）

這是 Cosmos 安裝最容易出錯的點。driver CUDA、torch backend tag、vLLM 版本必須三件一組對齊：

--torch-backend=auto 在這個情境不可靠（vLLM 沒有發 cu129/cu131 wheel），務必明確 pin。

2.4 安裝流程圖

flowchart TD
    A[要做什麼?] --> B{用途}
    B -->|生成 video / image / action| C[Generator surface]
    B -->|理解 video / 推理 / 任務規劃| D[Reasoner surface]
    B -->|訓練 / 後訓練 / 客製| E[研究路徑]

    C --> C1{研究還是 production?}
    C1 -->|研究 Python-first| C2[Diffusers backend
uv pip install diffusers]
    C1 -->|production API| C3[vLLM-Omni backend
docker pull vllm-omni:cosmos3]

    D --> D1{研究還是 production?}
    D1 -->|研究 Python-first| D2[Transformers backend
coming soon]
    D1 -->|production API| D3[vLLM backend
uv pip install vllm==0.21.0]

    E --> E1[Cosmos Framework backend
git clone cosmos-framework
uv sync --group=cu130-train]

    C2 --> F[HF auth login
uvx hf auth login]
    C3 --> F
    D2 --> F
    D3 --> F
    E1 --> F

    F --> G[執行 cookbook notebook
或 cosmos_framework.scripts.inference]

2.5 Diffusers 最小可跑範例（Generator）

 1uv venv --python 3.13 --seed --managed-python
 2source .venv/bin/activate
 3uv pip install --torch-backend=auto \
 4  "diffusers @ git+https://github.com/huggingface/diffusers.git" \
 5  accelerate \
 6  av \
 7  cosmos_guardrail \
 8  huggingface_hub \
 9  imageio \
10  imageio-ffmpeg \
11  torch \
12  torchvision \
13  transformers

 1import torch
 2from diffusers import Cosmos3OmniPipeline
 3from diffusers.utils import export_to_video
 4
 5pipe = Cosmos3OmniPipeline.from_pretrained(
 6    "nvidia/Cosmos3-Nano",
 7    torch_dtype=torch.bfloat16,
 8    device_map="cuda",
 9)
10
11result = pipe(
12    prompt="A mobile robot navigates a warehouse aisle and stops at a shelf.",
13    num_frames=189,
14    height=720,
15    width=1280,
16    fps=24.0,
17)
18
19export_to_video(result.video, "cosmos3_t2v.mp4", fps=24, macro_block_size=1)

第一次跑會下載 Cosmos3-Nano 權重，diffusion 是 compute-heavy，單張 7.9 秒影片在 H100 上仍需數十秒，這是正常的不是 hang。

2.6 vLLM-Omni Docker 最小可跑範例（Generator API）

 1docker pull vllm/vllm-omni:cosmos3
 2docker run --runtime nvidia --gpus all \
 3  -v ~/.cache/huggingface:/root/.cache/huggingface \
 4  -v "$(pwd):/workspace" \
 5  -p 8000:8000 \
 6  --ipc=host \
 7  vllm/vllm-omni:cosmos3 \
 8  vllm serve nvidia/Cosmos3-Nano \
 9    --omni \
10    --model-class-name Cosmos3OmniDiffusersPipeline \
11    --allowed-local-media-path / \
12    --port 8000

對外用 OpenAI-compatible API：

 1curl -sS -X POST http://localhost:8000/v1/videos/sync \
 2  --form-string "prompt=A small warehouse robot moves a blue box across a clean floor." \
 3  --form-string "negative_prompt=blurry, distorted, low quality" \
 4  --form-string "size=1280x720" \
 5  --form-string "num_frames=81" \
 6  --form-string "fps=24" \
 7  --form-string "num_inference_steps=35" \
 8  --form-string "guidance_scale=4.0" \
 9  --form-string "seed=42" \
10  -o cosmos3_t2v_output.mp4

務必用 --form-string（不要用 -F）：curl -F 把 ; 當 content-type 分隔，prompt 含分號會被截掉。這是 README 明確警告的踩雷點。

2.7 vLLM Reasoner 最小可跑範例

 1uv venv --python 3.13 --seed --managed-python
 2source .venv/bin/activate
 3uv pip install --torch-backend=cu130 "vllm==0.21.0" \
 4  "vllm-cosmos3 @ git+https://github.com/NVIDIA/cosmos-framework.git#subdirectory=packages/vllm-cosmos3"
 5
 6vllm serve nvidia/Cosmos3-Nano \
 7    --hf-overrides '{"architectures": ["Cosmos3ReasonerForConditionalGeneration"]}' \
 8    --async-scheduling \
 9    --allowed-local-media-path / \
10    --port 8000

Reasoner API 是標準 chat-completions：

 1import openai
 2client = openai.OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")
 3response = client.chat.completions.create(
 4    model=client.models.list().data[0].id,
 5    messages=[{"role": "user", "content": [
 6        {"type": "image_url", "image_url": {"url": "https://.../robot.jpg"}},
 7        {"type": "text", "text": "Caption the image in detail."},
 8    ]}],
 9    max_tokens=4096,
10    seed=0,
11)
12print(response.choices[0].message.content)

2.8 Cosmos Framework 完整安裝（研究 / 訓練路徑）

1mkdir -p packages
2git clone https://github.com/NVIDIA/cosmos-framework.git packages/cosmos3
3cd packages/cosmos3
4
5# lerobot 用 git-LFS，跳過 smudge 避免 LFS blob 失敗
6export GIT_LFS_SKIP_SMUDGE=1
7uv sync --all-extras --group=cu130-train     # CUDA 13
8# uv sync --all-extras --group=cu128-train   # CUDA 12.x

這會產生 packages/cosmos3/.venv。後續 cookbook notebook 都靠這個 venv 跑 torchrun -m cosmos_framework.scripts.inference。

2.9 常見安裝問題

3. 核心架構解析

3.1 Repo 結構

nvidia/cosmos repo 本身極簡潔——這是入口 hub，不是主框架：

 1cosmos/
 2├── README.md                       (537 行；模型家族 + 5 個 backend + quickstart + troubleshooting)
 3├── inference_benchmarks.md         (576 行；latency / throughput 量測結果)
 4├── RELEASE.md                      (release cadence 表)
 5├── LICENSE                         (OpenMDW-1.1)
 6├── cosmos-logo-thumbnail.png
 7└── cookbooks/
 8    └── cosmos3/
 9        ├── README.md               (5 個 backend 共用環境設定)
10        ├── cosmos3-model-architecture.png
11        ├── reasoner/
12        │   ├── README.md
13        │   ├── run_with_cosmos_framework.ipynb
14        │   ├── run_with_vllm.ipynb
15        │   └── assets/             (sample images + videos)
16        ├── generator/
17        │   ├── audiovisual/
18        │   │   ├── README.md
19        │   │   ├── run_with_diffusers.ipynb
20        │   │   ├── run_with_cosmos_framework.ipynb
21        │   │   ├── run_with_vllm_omni.ipynb
22        │   │   └── assets/         (prompts + sample images)
23        │   └── action/
24        │       ├── README.md
25        │       ├── run_fd_with_cosmos_framework.ipynb
26        │       ├── run_fd_with_vllm.ipynb
27        │       ├── run_id_with_cosmos_framework.ipynb
28        │       ├── run_id_with_vllm.ipynb
29        │       └── assets/         (action trajectories + sample videos)

真正的「框架」（trainer / inference engine / 模型實作）都在 NVIDIA/cosmos-framework repo；本 repo 只是 cookbooks + docs。

3.2 Cosmos 3 模型架構

flowchart LR
    subgraph IN[輸入 modality]
        T[Text tokens]
        V[Vision tokens
image / video]
        A[Audio tokens]
        ACT[Action tokens
9D / 10D / 20D / 29D]
    end

    subgraph CORE[統一 MoT Transformer]
        EMB[Multimodal embedding
3D mRoPE 位置編碼]
        ATTN{Attention mode
選擇}
        EMB --> ATTN
        ATTN -->|Reasoner| CAUSAL[Causal self-attention
next-token prediction]
        ATTN -->|Generator| FULL[Full attention
diffusion denoising]
    end

    subgraph OUT[輸出]
        TEXT[文字輸出
caption / answer / plan]
        IMG[圖像輸出
JPG]
        VID[影片輸出
MP4]
        SND[音訊輸出
AAC 48kHz stereo]
        ACTOUT[動作輸出
JSON trajectory]
    end

    T --> EMB
    V --> EMB
    A --> EMB
    ACT --> EMB

    CAUSAL --> TEXT
    FULL --> IMG
    FULL --> VID
    FULL --> SND
    FULL --> ACTOUT

關鍵設計：

1. Mixture-of-Transformers (MoT)：同一個 transformer backbone 同時支援兩種 attention mode
2. Unified 3D mRoPE：用三維 multi-dimensional rotary position embedding，同時編碼 spatial（H/W）與 temporal（T）兩個維度，讓模型對影片時序與空間結構都有正確 prior
3. Reasoner Mode（autoregressive）：causal self-attention，next-token prediction，做語意理解 / 規劃
4. Generator Mode（diffusion）：full attention，noise → clean 多步去噪，做生成
5. Action modality：把機器人 / 自駕車的動作軌跡也 token 化，與 video 同等地位——這是 Cosmos 3 對 v1.0 最大的躍進

3.3 Cosmos 在 NVIDIA Physical AI Stack 的位置

flowchart TB
    subgraph SIM[模擬與資料層]
        ISIM[Isaac Sim
3D 機器人模擬器]
        ILAB[Isaac Lab
RL training framework]
        CCUR[cosmos-curator
資料策展]
    end

    subgraph WFM[世界基礎模型層 — 本 Repo]
        COSMOS[Cosmos 3
Reasoner + Generator]
    end

    subgraph BRAIN[Agentic LLM 層]
        NEMO[Nemotron
Nano/Super/Ultra]
    end

    subgraph TRAIN[訓練 / 評估管線]
        NRL[NeMo-RL]
        MB[Megatron-Bridge]
        CEVAL[cosmos-evaluator]
    end

    subgraph DEPLOY[部署層]
        NIM[NIM serving]
        VLLM[vLLM / vLLM-Omni]
    end

    subgraph DOWN[下游應用]
        ROBOT[機器人 policy
DROID / UMI / humanoid]
        AV[自駕車
alpamayo]
        VFX[影音生成
game / film]
    end

    ISIM -->|sim trajectories| CCUR
    CCUR -->|curated data| COSMOS
    COSMOS -->|sim-to-real synthetic data| TRAIN
    COSMOS -->|world reasoning| BRAIN
    BRAIN -->|task plan| COSMOS
    TRAIN --> NEMO
    TRAIN --> COSMOS
    CEVAL -->|metrics| COSMOS
    COSMOS --> VLLM
    NEMO --> NIM
    VLLM --> ROBOT
    VLLM --> AV
    VLLM --> VFX
    NIM --> ROBOT
    NIM --> AV

讀法：左到右是「資料 → 模型 → 訓練 → 部署 → 應用」管線。Cosmos 卡在中間「世界基礎模型」位置：

• 上游吃 cosmos-curator 整理過的多模態資料（影片 + 動作軌跡）
• 下游餵下游應用（機器人 policy / 自駕 / VFX）
• 與 Nemotron 雙向交互：Nemotron 給 task plan，Cosmos 看世界並執行；Cosmos 生成的合成資料又回去訓練 Nemotron policy

3.4 兩個 Surface 的具體能力

Reasoner（理解）

Generator（生成）

3.5 動作（Action）模態如何運作

Cosmos 3 把「動作」當第五種 modality，token 化方式如下：

統一介面設計：

• 3D translation + 6D continuous rotation（避免 quaternion 在訓練的不穩定）
• Grasp 用 1D open-close 或 15D 人手 representation

3.6 支援的生成設定

4. Helper Scripts 與 Cookbook Notebook 詳細用法

4.1 Cookbook 結構速查表

4.2 cosmos_framework.scripts.inference 統一入口

不論 reasoner 還是 generator，Cosmos Framework 都是同一個 entrypoint：

1torchrun --nproc-per-node=<N> \
2  -m cosmos_framework.scripts.inference \
3  --parallelism-preset=<latency|throughput> \
4  -i <input-spec>.json \
5  -o <output-dir> \
6  --checkpoint-path <Cosmos3-Nano|Cosmos3-Super|...> \
7  --seed=<int>

Input spec 格式（JSON）：

Reasoner spec：

1{
2  "model_mode": "reasoner",
3  "name": "robot_image",
4  "prompt": "Describe what is happening in this image in one sentence.",
5  "vision_path": "https://.../robot_153.jpg",
6  "enable_sound": false
7}

enable_sound: false 在 reasoner 是必填——避免一個 strict argument-validation 失敗（README 明確記載的踩雷點）。

Forward dynamics spec：

1{
2  "model_mode": "generator",
3  "name": "umi_fd",
4  "vision_path": "assets/videos/umi.mp4",
5  "action_path": "assets/actions/umi.json",
6  "embodiment": "umi",
7  "num_frames": 16
8}

4.3 vLLM-Omni 動作端點

Policy / ID 必須走 async（因為要等 action 推完）；FD 可以走 sync（只回 video）。

extra_params 範例（forward dynamics）：

1{
2  "action_mode": "forward_dynamics",
3  "domain_name": "bridge_orig_lerobot",
4  "raw_action_dim": 10,
5  "action_chunk_size": 16,
6  "action_path": "/workspace/assets/actions/umi.json"
7}

action_path 是容器內路徑——掛載時要確保 --allowed-local-media-path 涵蓋這個目錄，否則被擋。

4.4 共用請求欄位

4.5 Reasoner Sampling 參數

啟用 reasoning 時要附 prompt 模板：

1Answer the question using the following format:
2
3<think>
4Your reasoning.
5</think>
6
7Write your final answer immediately after the </think> tag.

4.6 Generator Sampling 預設

4.7 Tensor / CFG / Ulysses Parallel

Cosmos3-Super 64B 需要拆 GPU：

組合時 GPU 數 = tensor_parallel × cfg_parallel × ulysses_degree。

5. 應用場景

5.1 機器人 Policy 訓練（最旗艦的 use case）

問題：訓練機器人 policy 需要大量「state + action」trajectory，real-world 資料蒐集慢、成本高。

Cosmos 解法：

1. 用 Cosmos3-Nano-Policy-DROID 對真實機器人影片做 inverse dynamics → 取得估計動作
2. 用 forward dynamics + 隨機 action 生大量 sim-to-real synthetic trajectories
3. 把 synthetic + real 一起餵 NeMo-RL / 自家 RL trainer

範例（vLLM-Omni FD）：

1files = {"input_reference": open("start.jpg", "rb")}
2data = {"prompt": "DROID arm picks up the red block",
3        "extra_params": '{"action_mode":"forward_dynamics","domain_name":"droid_lerobot","raw_action_dim":10,"action_chunk_size":16,"action_path":"/workspace/action.json"}'}
4r = requests.post("http://localhost:8000/v1/videos/sync", files=files, data=data)
5open("predicted_future.mp4","wb").write(r.content)

5.2 自駕車模擬（與 alpamayo 對接）

問題：自駕車 E2E driving model（如 NVlabs/alpamayo）需要大量罕見場景訓練資料（雨夜、行人鑽出、車輛切入）。

Cosmos 解法：

1. Generator T2V：給 prompt「雨夜城市路口，行人從停放車輛後方走出」生 sim 影片
2. Generator FD/AV：給起始幀 + 自駕車 9D ego pose trajectory → 預測未來路徑下的相機畫面
3. Reasoner physical plausibility：產生完後自動審查「這個場景物理合理嗎？」
4. 通過審查的合成影片 → alpamayo 訓練集

5.3 影音內容生成（game / film / 商業 VFX）

問題：手動製作高品質影片 / 同步音訊昂貴。

Cosmos 解法：

• T2V with sound：一個 prompt 同時得到視覺 + 音訊（AAC 48 kHz stereo），且兩者是時間對齊的（這是 Cosmos 3 vs. Sora / Veo 的差異點之一）
• I2V：給一張概念圖 + prompt 描述動作，產出動態影片
• V2V：給原始影片 + prompt「改成 cyberpunk 風格」做風格轉換

5.4 Physical AI Agent（與 Nemotron 對接）

問題：一個 robot agent 需要「規劃 task → 看世界 → 執行 → 回報」迴圈，純 LLM 看不到物理世界。

Cosmos 解法：

1. Nemotron：接 user request「把桌上的紅色積木搬到籃子裡」→ 規劃子任務
2. Cosmos Reasoner：看當前 camera feed → 回報目前場景理解（積木在哪、籃子在哪）
3. Nemotron：根據場景描述產生下一步動作 prompt
4. Cosmos Generator (policy mode)：給場景 + prompt → 產生 10D action trajectory
5. 真實機器人執行 → 回到步驟 2

這就是「Cosmos = 物理眼 + 物理手；Nemotron = 邏輯腦」的完整管線。

5.5 World Model 評估 / 物理一致性檢查

問題：生成出來的世界畫面看起來像，但物理錯了（球穿過桌子、人懸浮）。

Cosmos 解法：

• Reasoner Physical Plausibility Analysis：輸入影片，回傳 label（合理 / 不合理）
• 配合 NVIDIA/cosmos-evaluator：對大量生成樣本做批次評估，產生品質分布報告

5.6 範例 input 結構（cookbook 內附）

cookbooks/cosmos3/generator/audiovisual/assets/prompts/text2video/robot_kitchen.json：

1{
2  "prompt": "A robotic arm is preparing a meal in a modern kitchen..."
3}

cookbooks/cosmos3/generator/action/assets/actions/umi.json：UMI 手臂 16 frame trajectory，每一格是 10D pose delta + grasp。

6. 資安掃描報告

資安採紅黃綠燈格式（🔴 高 / 🟡 中 / 🟢 低）。針對「把 Cosmos 部署成內部 inference service」與「把 Cosmos 拿來生內部訓練資料」兩種 use case 評估。

6.1 🔴 高風險項目

6.1.1 --allowed-local-media-path / 預設給根目錄 read 權限

cookbooks/cosmos3/README.md、README.md、reasoner README、action README 一律示範：

1vllm serve ... --allowed-local-media-path / --port 8000

問題：這個參數讓 server 可以讀 host 任何 file://（透過 request body 內的本地路徑）。如果 vLLM-Omni endpoint 對外開放（甚至只在內網但跨團隊），有人可以餵 file:///etc/passwd、file:///root/.ssh/id_rsa、file:///proc/self/environ 當「input image」，server 會把內容當圖讀，雖然多半解析失敗，但錯誤訊息可能洩漏路徑或檔案存在性；更嚴重的是某些 codec 失敗後會回傳檔案開頭幾 byte 作 debug。

修補建議：

• 正式部署絕對不用 /，改成 --allowed-local-media-path /workspace/inputs（明確 whitelist）
• 容器掛載也只掛該子目錄，不要掛 $HOME / /
• 配合 reverse proxy 做 input sanitization，拒絕含 file:// 的 request body

6.1.2 trust_remote_code: true 在 deploy config

README.md 的 no_guardrails.yaml 範例：

1trust_remote_code: true

問題：vLLM / Transformers 載入 HuggingFace 模型時，若該 repo 含 custom Python（modeling code、tokenizer code），trust_remote_code: true 等於執行 HF 上的任意 Python。Cosmos 官方 repo 可信，但若管線設計允許下游切換模型路徑（透過 env / config），攻擊者可以指到惡意 HF mirror。

修補建議：

• 鎖死 model path 為 nvidia/Cosmos3-Nano / nvidia/Cosmos3-Super（不要讓 user 透過 query param 換 model）
• HF cache 用 read-only 掛載
• 內部 mirror 把 Cosmos 權重 fork 到自家 registry，斷外網拉

6.2 🟡 中風險項目

6.2.1 Guardrails 可以一行關閉

1model_config:
2  guardrails: false
3  offload_guardrail_models: false

或 per-request：

1extra_params={"guardrails":false}

問題：Cosmos 3 內建 prompt screening + face blur guardrails；關掉後可以生未模糊人臉的影片，或產出可能違反 NSFW / 真實人物 policy 的內容。對外服務必須堅守 guardrails 開啟。

修補建議：

• 內部部署用「server-wide off + per-request 不准 override」（README 提到「per-request overrides then cannot turn them back on」這條路徑）
• 對外服務絕對不開
• 日誌記錄每次 guardrails 觸發次數，定期 audit

6.2.2 HF_TOKEN / HF auth login 寫到 env / cookbook

cookbook 範例：

1export HF_TOKEN=<your_token>

問題：token 進 shell history、進 container env、進 ipynb cell；如果 notebook 不小心 commit 到 repo 就全公開。

修補建議：

• 用 uvx hf auth login（會寫到 ~/.cache/huggingface/token，正確 chmod 600）
• 不要在 ipynb cell 寫 export HF_TOKEN=
• HF cache 掛載要避免 cross-tenant 共用

6.2.3 Docker image 拉自外網 vllm/vllm-omni:cosmos3

問題：production 環境若 image registry 被 compromise，部署到 GPU host 形同被入侵。

修補建議：

• pin image digest（不是 tag）
• 推到自家 internal registry，斷外網拉
• 定期 trivy / grype 掃 image vulnerabilities

6.3 🟢 低風險 / 已合理處理

6.4 總體評估

🟡 中度風險，可控

• 預設 cookbook 設定（--allowed-local-media-path / + guardrails 可關 + trust_remote_code）是「研究友善 / production unsafe」
• 不能直接照 README 抄到 production，必須做 hardening：whitelist media path、鎖 model path、guardrails 鎖 on、image digest pin、HF cache 隔離
• 對「內部研究 GPU 機」使用 OK；對「對外 API service / 跨團隊共用 endpoint」必須做 reverse proxy + WAF + auth

7. FAQ

Q1：Cosmos 跟 Sora / Veo / Runway 比，差在哪？

A：定位完全不同。Sora / Veo 主打消費級影片生成，Cosmos 主打 Physical AI——它特別擅長機器人 / 自駕場景，且支援 action 條件（給 9D / 10D / 29D 動作 trajectory 預測畫面），這是消費級模型沒有的。對影視 VFX 來說 Cosmos 不是最美觀的，但對「我要生 100 萬筆 DROID 機器手臂 trajectory 訓 policy」這種需求，Cosmos 是目前最直接的 production-grade open 方案。

Q2：Cosmos 3 與 Cosmos 1.0 / 2 差別？

A：

• Cosmos 1.0（2025-01）：兩個獨立模型——diffusion WFM + autoregressive WFM，分開部署
• Cosmos 3（2026-06）：MoT 架構統一在同一個 transformer backbone，同時支援 reasoner + generator + action modality；3D mRoPE 統一空間時序編碼

Cosmos 2 雖然有研究 paper，但未發 release tag。

Q3：我沒有 H100，能跑嗎？

A：

• Cosmos3-Nano（16B）：1× 24-40 GB GPU（RTX 4090 / A6000 / A100-40G）可跑 inference，但長影片仍可能 OOM
• Cosmos3-Super（64B）：至少 4× GPU + tensor parallel + 可能要 --enable-layerwise-offload
• 想 fine-tune 或 post-train：規模放大到 8-64 GPU，視 task 而定

Q4：vLLM 還是 Diffusers，怎麼選？

A：

• 研究 / 自定義 / 改 sampling：Diffusers（Python-first，code 直接看到 forward）
• production 服務 / OpenAI 相容 API：vLLM（reasoner）/ vLLM-Omni（generator）
• 訓練 / 後訓練：Cosmos Framework（torchrun -m cosmos_framework.scripts.inference）

Q5：Cosmos 與 Nemotron 一起用，最合理的工作流？

A：「Nemotron 規劃 + Cosmos 執行/驗證」：

1. Nemotron 接 user request，產 task plan
2. Cosmos Reasoner 看 camera feed，回報目前場景
3. Nemotron 規劃下一步動作 prompt
4. Cosmos Generator (policy mode) 產 10D action trajectory
5. 真實機器人執行 → 回到 2

訓練流程則反過來：用 Cosmos 生大量 synthetic robot trajectory，餵 NeMo-RL，去訓 Nemotron + 機器人 policy head。

Q6：Cosmos 跟 NVlabs/alpamayo 是什麼關係？

A：兩者是「世界模型 vs E2E driving model」的互補關係。alpamayo（NVlabs 自駕車研究專案）是把感知 → 規劃 → 控制全部包成單一模型；Cosmos 是「物理世界的 simulator + reasoner」，可以生成 alpamayo 的訓練資料（罕見場景合成）與驗證 alpamayo 的輸出物理合理性。

Q7：Cosmos 跟 NVlabs/Nemotron-Labs-Diffusion 是什麼關係？

A：兩者都是 NVIDIA 系的 diffusion 模型，但階段不同：

• Nemotron-Labs-Diffusion：NVlabs 研究階段，探索新 diffusion 架構 / 訓練方法
• Cosmos：production-grade，已經套 omnimodal MoT，模型權重對外發

可以視為「NVlabs 研究 → 成熟後進 NVIDIA-NeMo / Cosmos 主線」的演化關係。

Q8：sound 怎麼跟 video 同步生？

A：Cosmos 3 的 audiovisual generator 同時把 video token 與 audio token 餵進 MoT，full attention 同時對齊兩個 modality。對外用：

• vLLM-Omni /v1/videos/sync 加 generate_sound=true
• Diffusers 用 enable_sound=True 且模型 checkpoint 含 sound module
• 輸出是 AAC 48 kHz stereo，muxed 進 MP4

Q9：為什麼 cookbook 都用 uv？

A：Cosmos Framework pyproject.toml enforce uv >= 0.11.3，原因：

• [tool.uv.audit] section 需要 uv 才認得
• --torch-backend=cu130 是 uv 特有的 syntax（pip 不認）
• Cosmos 依賴複雜（diffusers / vllm / cosmos-framework / vllm-cosmos3 等多個 git+source），uv resolver 比 pip 快很多

Q10：guardrails 對研究有妨礙嗎？

A：對 robotics / autonomous vehicle 場景影響不大；對「需要生具名人物 / 含敏感場景」的研究會被擋。允許 per-request 關閉但對外服務必須開。

Q11：模型 license 商業可用嗎？

A：OpenMDW-1.1 是 NVIDIA 自家許可，covers source + weights。商業使用前必須讀完整 LICENSE 並讓法務確認——它與 MIT/Apache-2.0 不完全相同。

Q12：v1.0 的 model 還能用嗎？

A：可以但官方主推 Cosmos 3。v1.0 的 tokenizer / WFM 仍在 HF（標 deprecated 提示），舊 pipeline 不要急著換但新專案直接上 3。

8. 進階技巧

8.1 Disable Guardrails（內部研究 only）

server-wide 關閉（per-request override 也不能開回來）：

 1# no_guardrails.yaml
 2async_chunk: false
 3stages:
 4  - stage_id: 0
 5    max_num_seqs: 1
 6    enforce_eager: true
 7    trust_remote_code: true
 8    model_class_name: Cosmos3OmniDiffusersPipeline
 9    model_config:
10      guardrails: false
11      offload_guardrail_models: false

1vllm serve nvidia/Cosmos3-Nano --omni \
2  --model-class-name Cosmos3OmniDiffusersPipeline \
3  --deploy-config no_guardrails.yaml \
4  --port 8000

8.2 Cosmos3-Super 在有限 VRAM 上跑（layerwise offload）

1docker run --runtime nvidia --gpus '"device=0,1,2,3"' \
2  vllm/vllm-omni:cosmos3 \
3  vllm serve nvidia/Cosmos3-Super \
4    --omni \
5    --model-class-name Cosmos3OmniDiffusersPipeline \
6    --tensor-parallel-size 4 \
7    --enable-layerwise-offload \
8    --allowed-local-media-path /workspace \
9    --port 8000

--enable-layerwise-offload 把 transformer block 在 CPU / GPU 之間 swap，犧牲 latency 換 VRAM。對 single-stream inference OK，concurrent 多 request 場景反而拖慢。

8.3 CFG Parallel + Ulysses

1vllm serve nvidia/Cosmos3-Super --omni \
2  --tensor-parallel-size 4 \
3  --cfg-parallel-size 2 \
4  --ulysses-degree 2 \
5  ...

需要 4 × 2 × 2 = 16 張 GPU。CFG parallel 把 positive / negative branch 同時跑，省一半 diffusion latency。

8.4 Reasoner 啟用 think tag

把這段 append 到 user prompt：

1Answer the question using the following format:
2
3<think>
4Your reasoning.
5</think>
6
7Write your final answer immediately after the </think> tag.

sampling 改 temperature=0.6, top_p=0.95, presence_penalty=0.0。

8.5 FlashInfer JIT 找不到 ninja

1source .venv/bin/activate     # 確保 .venv/bin 在 PATH
2vllm serve ...

不要用 .venv/bin/vllm 直接跑（會找不到 ninja）。

8.6 vLLM-Omni 對自定 embodiment 做 forward dynamics

擴充 embodiment：複製 assets/actions/umi.json 結構，改 dim / fps / rotation 編碼。Server 端 domain_name 要對應到 cosmos-framework 註冊的 embodiment（目前支援：bridge_orig_lerobot, av, camera_pose, droid_lerobot, umi）。自定 embodiment 要從 cosmos-framework 改 code。

8.7 cosmos-evaluator 批次評估

1git clone https://github.com/NVIDIA/cosmos-evaluator.git
2# 啟動 reasoner server（physical_plausibility）
3# 批次跑 evaluator 把 100k 個 generation 過一遍，產 metrics 報告

8.8 內部 mirror 模型權重

1# 在內部 GPU host
2huggingface-cli download nvidia/Cosmos3-Nano --local-dir /shared/models/cosmos3-nano
3# 之後 serve 時用 local path
4vllm serve /shared/models/cosmos3-nano --omni ...

這同時解決 (a) HF rate limit (b) 外網中斷 (c) 多機共享 cache 三個痛點。

9. 整合進 NVIDIA AI 工作流

9.1 與 Nemotron 雙劍合璧

詳見 §5.4 的 5 步 agentic loop。Nemotron tutorial（inbox/2026-06-02-tutorial-Nemotron.md §3）有提到 21 個 RLVR reward env、SWE-RL、GenRM-RLHF；其中embodied env（機器人 / 自駕）非常適合用 Cosmos 作為 simulator + critic：

• simulator：每一步 RL rollout 不在真機跑（太貴），改用 Cosmos forward dynamics 模擬未來畫面
• critic：用 Cosmos reasoner physical_plausibility 當 reward signal 一部分（生出來的軌跡如果物理不合理就 penalize）

實作骨架（pseudo-code）：

 1# Nemotron 給 task plan
 2plan = nemotron.chat(f"Plan tasks for: {user_request}")
 3
 4# 每一步
 5for step in plan.steps:
 6    # Cosmos reasoner 看當前 camera
 7    scene = cosmos_reasoner.caption(current_camera_feed)
 8
 9    # Nemotron 根據 scene 產 action prompt
10    action_prompt = nemotron.chat(f"Given scene: {scene}\nNext step: {step.description}\nProduce action.")
11
12    # Cosmos generator policy mode 把 prompt 轉成 10D trajectory
13    trajectory = cosmos_generator.policy(image=current_image,
14                                          prompt=action_prompt,
15                                          embodiment="droid_lerobot")
16
17    # 真實機器人執行
18    robot.execute(trajectory)

9.2 與 cosmos-curator + cosmos-evaluator

flowchart LR
    RAW[raw videos
YouTube / 內部蒐集] --> CUR[cosmos-curator
filter / annotate / dedup]
    CUR --> TRAIN[Cosmos Framework
post-training]
    TRAIN --> COSMOS[新 Cosmos checkpoint]
    COSMOS --> GEN[batch generation
100k synthetic samples]
    GEN --> EVAL[cosmos-evaluator
physical_plausibility / quality]
    EVAL --> METRICS[metrics report]
    EVAL -->|拒絕的 sample| GEN
    EVAL -->|通過的 sample| DOWNSTREAM[下游訓練
RL / SFT / policy distillation]

9.3 與 NeMo-RL / Megatron-Bridge / DataDesigner

從 Nemotron tutorial §2.4 知道 Nemotron 是 NeMo 全家桶用戶。Cosmos 預期會走相同路線：

• NeMo-Curator ↔ cosmos-curator：兩者並存；cosmos-curator 偏視覺 / 影片，NeMo-Curator 偏文字
• NeMo-RL：未來 Cosmos post-training（embodied RLVR）的 trainer
• Megatron-Bridge：大規模分散式訓練底層
• DataDesigner：產合成資料；Cosmos 是「視覺合成資料」面，DataDesigner 是「結構化合成資料」面，兩者互補

9.4 與 NVlabs/alpamayo（自駕 E2E）

整合骨架：

1. Cosmos generator AV mode 生罕見場景影片 + 9D ego trajectory
2. cosmos-evaluator physical_plausibility 過濾
3. 通過的合成資料丟給 alpamayo 訓練
4. alpamayo deploy 後，用 Cosmos reasoner 做 online safety check（看 alpamayo 預測的下一步動作會不會撞到物體）

9.5 與 NVlabs/Nemotron-Labs-Diffusion

研究階段對比：

• 如果 Nemotron-Labs-Diffusion 探索出新 diffusion sampler / scheduler，可以做 ablation 移植到 Cosmos generator
• 反過來：Cosmos 3 的 MoT 統一架構也是 NVlabs 研究先驗（Mixture-of-Transformers 起源於 NVlabs 早期論文）

9.6 部署模式對照（內部資料 pipeline）

10. 重點摘要 Checklist

• 知道 Cosmos 是「Physical AI 的 world foundation model」，與 Sora / Veo 定位不同
• 知道 Cosmos 3 = MoT 統一 reasoner + generator + 5 種 modality（含 action）
• 知道五種 backend：Cosmos Framework / Diffusers / Transformers (TBD) / vLLM (reasoner) / vLLM-Omni (generator)
• 安裝時 driver CUDA / torch backend / vLLM 版本必須三件一組對齊
• HuggingFace 模型 gated，要先 uvx hf auth login
• cookbook 預設 --allowed-local-media-path / 是研究設定，production 必須 whitelist 子目錄
• cookbook 預設 trust_remote_code: true，production 必須鎖死 model path
• Guardrails 對外服務必須開
• --form-string 不是 -F（prompt 含分號會被 curl -F 吃掉）
• enable_sound: false 在 reasoner spec 是必填
• Cosmos 與 Nemotron 的關係：Cosmos = 物理眼 + 物理手，Nemotron = 邏輯腦
• 與 alpamayo 的關係：Cosmos 生 AV 訓練資料，alpamayo 用
• 與 Nemotron-Labs-Diffusion 的關係：研究 → production 兩端
• Cosmos3-Super 需要多 GPU + tensor parallel + 可能 layerwise offload
• License OpenMDW-1.1 商業使用前要法務確認

11. 進一步閱讀

11.1 官方資源

• GitHub 本 repo：https://github.com/nvidia/cosmos
• Cosmos Framework（訓練 / 推理主框架）：https://github.com/NVIDIA/cosmos-framework
• Cosmos Curator（資料策展）：https://github.com/NVIDIA/cosmos-curator
• Cosmos Evaluator（評估）：https://github.com/NVIDIA/cosmos-evaluator
• 官網：https://www.nvidia.com/en-us/ai/cosmos/
• Cosmos Lab 首頁：https://research.nvidia.com/labs/cosmos-lab/cosmos3/
• Cosmos 3 Technical Report：https://research.nvidia.com/labs/cosmos-lab/cosmos3/technical-report.pdf
• HuggingFace collection：https://huggingface.co/collections/nvidia/cosmos3
• vLLM-Omni Cosmos 3 PR：https://github.com/vllm-project/vllm-omni/pull/3454
• OpenMDW-1.1 License：https://openmdw.ai/license/1-1/

11.2 相關 NVIDIA 專案（內部教材已涵蓋）

• inbox/2026-06-02-tutorial-Nemotron.md — Nemotron LLM 家族（Nano/Super/Ultra/Nano Omni）
• inbox/2026-05-29-... — NVlabs/Nemotron-Labs-Diffusion（研究階段 diffusion，姊妹文件處理中）
• inbox/2026-05-29-... — NVlabs/alpamayo（E2E 自駕，姊妹文件處理中）

11.3 相關技術背景

• Diffusers 文件 — Cosmos 3 pipeline：https://huggingface.co/docs/diffusers/main/en/api/pipelines/cosmos3
• vLLM-Omni Videos API：https://docs.vllm.ai/projects/vllm-omni/en/latest/serving/videos_api/
• vLLM-Omni Image Generation API：https://docs.vllm.ai/projects/vllm-omni/en/latest/serving/image_generation_api/
• vLLM-Omni Cosmos 3 online-serving 範例：https://github.com/vllm-project/vllm-omni/tree/main/examples/online_serving/cosmos3
• DROID benchmark（機器人）：https://arxiv.org/abs/2403.12945
• inference_benchmarks.md（Cosmos repo 內，每張 GPU × workflow latency 量測）

11.4 Physical AI / World Model 相關研究

• 「World Model」概念起源：Ha & Schmidhuber 2018 (RNN world model)
• Genie / Genie 2（Google DeepMind）：互動式 world model 競爭者
• 1X NEO / Figure 02 / Tesla Optimus：humanoid robot 場景下 Cosmos action policy 的潛在客戶

11.5 內部 retro / 學習筆記

• gh-tutorial-qd workflow：.claude/skills/gh-tutorial-qd/SKILL.md
• quarkdown：.claude/skills/quarkdown/SKILL.md
• ai-gh-save：.claude/skills/ai-gh-save/SKILL.md

文件結束

這份 Cosmos 教學手冊以 NVIDIA Physical AI 生態系視角寫成，與 2026-06-02-tutorial-Nemotron.md 互為姊妹文件。 兩者結合：Nemotron 是邏輯腦、Cosmos 是物理眼+手、cosmos-curator/evaluator 是資料策展與評估、NeMo-RL/Megatron-Bridge/DataDesigner 是訓練管線。理解這個分工，就理解了 NVIDIA 2026 開源 AI 的整盤棋。