Cosmos-Transfer2.5 是 NVIDIA 基于 Cosmos-Predict2.5 构建的世界模拟模型，能够以深度、边缘、分割、可见性等多种空间控制视频为条件生成高质量仿真视频。本文带你从零开始，用官方内置的Gradio Web 服务为它搭建一个支持多进程推理的可视化界面：上传素材、粘贴 JSON 请求、一键生成视频，全程无需手写推理脚本。

一、先看懂多进程架构：为什么是"多进程"

Cosmos-Transfer2.5 的 Gradio 服务（packages/cosmos-gradio/）采用了"前端界面进程 + N 个模型工作进程"的架构：

• GradioApp 主进程：负责渲染 Web 界面、校验 JSON 参数、把请求分发到工作进程，并收集输出视频与状态信息（gradio_app.py）；
• Model Worker 进程：每个 GPU 对应一个独立工作进程，各自完整加载一次模型，通过进程间通信（IPC）队列接收请求（model_server.py）；
• 超时自愈：工作进程卡死或超时会触发自动重启，服务不会整体挂掉。

📌 这种设计的好处是：界面始终保持响应，多张 GPU 可以并行服务多个推理请求。

二、环境准备与安装步骤

1. 系统要求

详细清单见官方 docs/setup.md。

2. 克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/co/cosmos-transfer2.5 cd cosmos-transfer2.5 # 安装 uv 后同步依赖（CUDA 12.8 环境用 cu128） uv python install uv sync --extra=cu128 source .venv/bin/activate

💡 Blackwell / DGX Spark / Jetson AGX 请改用uv sync --extra=cu130。

3. 准备模型检查点

1. 获取一个具有Read权限的 Hugging Face Access Token；
2. 安装并登录 HF CLI：uv tool install -U "huggingface_hub[cli]"，然后执行hf auth login；
3. 接受 NVIDIA Open Model License Agreement。

检查点会在首次推理时自动下载，可通过HF_HOME环境变量修改缓存位置。

三、一键启动 Gradio 服务

官方提供了一键脚本 scripts/run_gradio.sh，它会完成：安装依赖 → 激活虚拟环境 → HF 认证 → 自动创建输出目录 → 启动服务并写日志。

# 最简启动（默认 multicontrol 模型、2 个 GPU 工作进程） bash scripts/run_gradio.sh

脚本内部核心逻辑（摘自 run_gradio.sh）：

export GRADIO_APP=${GRADIO_APP:-cosmos_transfer2/gradio/gradio_bootstrapper.py} export MODEL_NAME=${MODEL_NAME:-"multicontrol"} export NUM_GPUS=${NUM_GPUS:-2} PYTHONPATH=. python3 "$GRADIO_APP" 2>&1 | tee -a "$LOG_FILE"

也可以不走脚本，手动指定入口：

export MODEL_NAME=multicontrol export NUM_GPUS=2 PYTHONPATH=. python3 cosmos_transfer2/gradio/gradio_bootstrapper.py

启动成功后，浏览器打开http://localhost:8080即可访问（服务默认绑定0.0.0.0:8080，支持上传最大 500MB 的文件）。

四、关键环境变量配置表

服务的全部部署配置由DeploymentEnv类从环境变量（或.env文件）读取，定义见 deployment_env.py：

支持的 MODEL_NAME 取值

模型名到工作进程的映射见 gradio_bootstrapper.py：

⚠️ 注意：multiview模式强制要求NUM_GPUS=8，否则启动时直接报错退出。

五、使用 Web 界面生成视频

打开http://localhost:8080后，界面包含四大功能区（见 gradio_ui.py）：

1. 文件上传区：上传本地图片/视频，系统返回服务器路径，直接填入 JSON 请求即可；
2. JSON 请求区：预填了当前模型的示例请求（sample_data.py），展开 "Request Format Help" 可查看完整参数 Schema；
3. 结果区：点击Generate Video后在线播放生成视频，并显示状态信息；
4. 日志查看器：实时滚动显示LOG_FILE中的推理日志，排错无需离开浏览器。

一个典型的控制转移请求长这样：

{ "name": "robot_edge", "prompt_path": "assets/robot_example/robot_prompt.txt", "video_path": "assets/robot_example/robot_input.mp4", "guidance": 3, "edge": { "control_path": "assets/robot_example/edge/robot_edge.mp4", "control_weight": 1.0 } }

💡 除了网页，服务还暴露了 API 端点generate和generate_default_request，方便脚本化批量调用。

六、常见问题排查

更多排查技巧见 docs/troubleshooting.md。

七、小结

通过本文，你已经掌握了 Cosmos-Transfer2.5 Gradio Web 服务的完整部署流程：

• ✅ 环境安装：uv sync --extra=cu128+ HF Token 登录；
• ✅ 一键启动：bash scripts/run_gradio.sh，默认 2 GPU 多进程推理；
• ✅ 按需配置：MODEL_NAME切换单控制/多控制/多视角模型，NUM_GPUS控制并行工作进程数；
• ✅ 使用体验：浏览器中上传素材 → 编辑 JSON → 在线预览视频与日志。

整个界面源码位于 cosmos_transfer2/gradio/，框架文档见 packages/cosmos-gradio/README.md，如需接入自己的模型，只需实现"模型类 + 工厂函数 + 参数校验"三件套即可复用这套多进程 Web 服务。