运行推理

运行模型 demo、检查生成产物并做发布验证 — 评分请见评测章节。

最后更新: 2026年7月11日

本页内容

快速路径环境可复现的单模型准备流程 CLI 推理 Workspace 推理输出契约下一步

WorldFoundry 推理覆盖环境安装、checkpoint 准备、模型启动和产物检查。Benchmark 评分与 scorecard 见评测。选模型 id、看 readiness 标签请先看模型。

快速路径

bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"

bash scripts/inference/test_nav_video_gen.sh matrix-game-2 \
  --output-dir tmp/matrix_game2_first_run

在 tmp/matrix_game2_first_run 下检查生成的视频和运行元数据。该产物只是推理证据，不是 benchmark 或 leaderboard 证据。Checkpoint 与 cache 布局见本地资产；Web workspace 见 Studio。

环境

创建并激活统一推理环境：

bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"

如果模型有专用 conda profile，用 profile resolver 安装或验证，不要猜环境名：

bash scripts/setup/model_env_install.sh --list
bash scripts/setup/model_env_install.sh --model <model-id>

Hugging Face checkpoints 默认应通过原生 from_pretrained 或 snapshot_download cache 行为加载。

WORLDFOUNDRY_CKPT_DIR 用于非 HF 权重，以及上游式 runtime 需要的兼容 alias。

如果机器上已经有共享 checkpoint 目录，优先用软链接接入支持的 cache layout，不要复制权重：

bash scripts/setup/link_hf_checkpoints.sh \
  --ckpt-dir /path/to/checkpoints \
  --hfd-root /path/to/checkpoints/hfd \
  --hf-hub-cache /path/to/huggingface/hub \
  --default-world

这个脚本会同时创建 HFD alias，例如 THUDM--CogVideoX-5b-I2V，以及原生 Hugging Face cache alias，例如 models--THUDM--CogVideoX-5b-I2V/snapshots/worldfoundry-local。新用户不需要执行这一步，可以直接让 Hugging Face 按默认策略下载到 HF_HOME。

单模型首次推理可以用面向发布的 helper 串起这些步骤：

bash scripts/inference/prepare_model_infer.sh <model-id> --verify-env-only
bash scripts/inference/prepare_model_infer.sh <model-id> --download

它会解析 conda profile，通过原生 HF cache 或文档声明的 HFD alias 检查/下载 Hugging Face checkpoint，运行 zoo model-download --check-local，并打印下一步推理命令。

可复现的单模型准备流程

本地发布验证和开源用户复现都使用同一组顺序：

bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"

bash scripts/setup/model_env_install.sh --list
bash scripts/setup/model_env_install.sh --model <model-id> --verify-only

bash scripts/inference/prepare_model_infer.sh <model-id> --download

model_env_install.sh --list 是环境路由的事实来源。大多数 model profile 会解析到 worldfoundry-unified-<tier>。只有 runtime/environments 记录了真实兼容性原因时，才应该使用专用环境，例如固定的 torch/CUDA ABI、 JAX/TensorFlow 隔离，或 simulator 依赖。

不要把私有 cache 路径写进公开文档。公开 checkpoint 路径应该是 Hugging Face repo id、原生 HF cache 位置，或文档明确声明的 WORLDFOUNDRY_CKPT_DIR alias。

CLI 推理

共享命令行推理入口是 Studio workspace job runner：

python -m worldfoundry.studio.workspace_job infer \
  --model-id <model-id> \
  --prompt "a cinematic scene, high quality" \
  --output-dir tmp/worldfoundry_infer/<model-id> \
  --device cuda

Image-to-video 或 video-to-video 模型需要传入对应输入路径：

python -m worldfoundry.studio.workspace_job infer \
  --model-id <model-id> \
  --input-path /path/to/input.png \
  --prompt "camera moves forward through the scene" \
  --frames 81 \
  --steps 30 \
  --seed 42 \
  --output-dir tmp/worldfoundry_infer/<model-id>

如果模型需要尚未做成一级 flag 的参数，用 --call-json 和 --load-json：

python -m worldfoundry.studio.workspace_job infer \
  --model-id <model-id> \
  --call-json '{"num_frames": 17, "height": 480, "width": 832}' \
  --load-json '{"torch_dtype": "bfloat16"}' \
  --output-dir tmp/worldfoundry_infer/<model-id>

兼容桥接脚本也存在：

bash scripts/inference/run_infer.sh \
  --model-id <model-id> \
  --prompt "a cinematic scene, high quality" \
  --output-dir tmp/worldfoundry_infer/<model-id>

Workspace 推理

多模型验证时，启动 workspace UI 并在浏览器中提交 job：

bash scripts/workspace/run_workspace.sh

打开：

http://127.0.0.1:7870/

Workspace 是检查 release readiness 的首选界面。

它适合检查模型专用输入表单、官方 demo 默认参数、生成文件、 gallery previews 和视觉回归；确认后再记录模型 readiness。

逐模型 viewer 路由和 Visualizers 页面说明见 Studio 指南。

Create Job 字段、runtime checks、默认值，以及可选的持久化默认配置，见 Studio 指南。

输出契约

每次推理应产生一个 manifest-like JSON record 和一个或多个 artifact：

输出	期望用途
生成的视频/图像/3D/action artifact	需要人工视觉或结构检查的主要 demo 输出。
Job manifest 或 run record	记录 model id、variant、backend、参数、路径、耗时、状态和错误。
Logs	Runtime import、checkpoint、CUDA 和模型调用细节。
Studio 的 Gallery/Files 条目	发布验证时的人类 review surface。

不要把“生成了视频文件”本身当作成功。

还要检查输入契约、prompt/camera/action 控制、帧数、分辨率和 artifact 内容是否匹配官方 demo 或模型 profile。