cosmos

环境要求

• Python 环境，并安装 uv（Cosmos Framework 要求 uv >= 0.11.3）
• 可用的 NVIDIA CUDA 环境（安装使用 --torch-backend=cu128 等 CUDA 后端）
• Hugging Face 账号，并能创建访问令牌（access token）
• 已申请并获得 gated 仓库 nvidia/Cosmos-1.0-Guardrail 的访问权限（Generator 必需）
• 磁盘空间充足，或可挂载共享/大容量缓存盘用于存放模型（HF_HOME）

安装与启动步骤

1. 1确认 uv 版本

   Cosmos Framework 通过 pyproject.toml 强制要求 uv >= 0.11.3，版本过旧会解析配置失败或无法识别 cu130 等新参数。

   uv self update

   复制

2. 2创建 HF 令牌

   在 Hugging Face 网站创建 access token；这是运行示例前的前置条件，令牌需要能读取所用模型仓库。

3. 3本地认证 Hugging Face

   用官方 CLI 在本地完成登录，认证后后续示例才能拉取 NVIDIA Cosmos 模型权重。

   uvx hf@latest auth login

   复制

4. 4申请 Guardrail 权限

   Generator 路径依赖 gated 仓库 nvidia/Cosmos-1.0-Guardrail，需先在该页面申请访问并通过审核。

5. 5设置缓存目录

   如需共享缓存或磁盘空间不足，可设置 HF_HOME 把模型缓存指向更大容量的磁盘，否则可跳过。

   export HF_HOME=/your/path/hf-cache

   复制

6. 6准备 NIM 密钥

   只有 NIM 路径用 NGC API key 替代 Hugging Face 认证，其他 Generate/Reasoner 路径不需要这一步。

   export NGC_API_KEY=nvapi-xxxxxxxx

   复制

7. 7运行 Quickstart

   按 README Quickstart 选择一条路径（Diffusers、vLLM-Omni、NIM、SGLang 或 Transformers、vLLM、TensorRT-LLM）。

关键配置

如何确认成功

所选 Quickstart notebook 能无报错跑通，成功输出生成视频或推理结果，且 Guardrail 校验通过。

常见问题

注意事项

• README 节选未给出完整安装命令，其中的 uv pip install --torch-backend=cu128 在原文里被截断，请以官方 README 完整命令为准。
• Generator 相关路径必须先通过 nvidia/Cosmos-1.0-Guardrail 的 gated 仓库访问申请。
• 关闭 Guardrail 的开关因推理后端而异：Diffusers、TensorRT-LLM、vLLM-Omni、Cosmos Framework 各不相同。
• 节选只覆盖 Quickstart 的认证与权限部分，各后端具体运行命令需查看 README 对应小节。