# 运行推理 (/zh/docs/guides/inference)



WorldFoundry 推理覆盖环境安装、checkpoint 准备、模型启动和产物检查。Benchmark 评分与 scorecard 见 [评测](/zh/docs/evaluation)。选模型 id、看 readiness 标签请先看 [模型](/zh/docs/guides/supported-models)。

## 快速路径 [#快速路径]

```bash
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 布局见 [本地资产](/zh/docs/guides/local-assets)；Web workspace 见 [Studio](/zh/docs/guides/studio)。

## 环境 [#环境]

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

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

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

```bash
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
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
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
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 推理 [#cli-推理]

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

```bash
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 模型需要传入对应输入路径：

```bash
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`：

```bash
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
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-推理]

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

```bash
bash scripts/workspace/run_workspace.sh
```

打开：

```text
http://127.0.0.1:7870/
```

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

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

逐模型 viewer 路由和 Visualizers 页面说明见
[Studio 指南](/zh/docs/guides/studio#workspace-可视化器)。

Create Job 字段、runtime checks、默认值，以及可选的持久化默认配置，见
[Studio 指南](/zh/docs/guides/studio#create-job-配置)。

## 输出契约 [#输出契约]

每次推理应产生一个 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。

## 下一步 [#下一步]

产物确认无误后，进入独立文档章节继续：

<Cards>
  <Card title="评测" description="运行 benchmark、对输出评分并阅读 scorecard。" href="/docs/evaluation" />

  <Card title="Studio" description="多模型 workspace，用于视觉 QA 与 Gallery 审查。" href="/docs/guides/studio" />
</Cards>