快速开始

本指南给出从 clone 到一次可 review 的 WorldFoundry run 的最短完整路径：

• 环境配置
• 资产准备
• TUI
• CLI
• 推理
• 评测

换了模型或 benchmark，大多数 run 的形状仍然一样：先让 Python 环境可 import，再发现稳定 ID，只准备必要的 checkpoint 与 benchmark 资产，生成并检查 artifact，最后才对 artifact 打分。

使用流程

前置条件

• 操作系统： 推荐 Linux，用于 GPU 推理和大多数 benchmark runner
• 安装路径： 轻量 CPU catalog/CLI/TUI 工作使用 python -m pip install -e ".[tui]"；CUDA conda runtime 使用 bash scripts/setup/bootstrap_worldfoundry.sh。这是文档用户的官方首次 clone 脚本；它已经会调用 scripts/setup/unified_install.sh 创建统一 GPU 环境，因此不要从 unified_install.sh 起步，除非你只是在刷新该环境。可选 extras 不会自动选择 CUDA PyTorch wheel index。
• Python： 3.10+；GPU 路径由 WorldFoundry 统一 conda 环境管理
• 可选： 支持 CUDA 的 GPU、用于 gated checkpoint 的 Hugging Face token

1. 环境配置

下面的命令描述 GPU runtime 路径。官方首次 clone 命令是 bash scripts/setup/bootstrap_worldfoundry.sh。它会创建默认 WorldFoundry runtime，并写出一份本地 shell 文件，里面包含 CLI、Studio 和评测 runner 会用到的路径。每次打开新 shell 后都应该先 source 这个文件。

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenEnvision/WorldFoundry.git
cd WorldFoundry

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

bash scripts/setup/bootstrap_worldfoundry.sh \
  --home /path/to/worldfoundry-home \
  --data-root /path/to/worldfoundry-data \
  --model-root /path/to/worldfoundry-models \
  --artifact-root /path/to/worldfoundry-artifacts

bash scripts/setup/bootstrap_worldfoundry.sh --verify-only
worldfoundry-eval --help

2. 资产准备

WorldFoundry 只把可执行代码放在仓库里。Checkpoint、dataset、metric 权重、reference 文件与生成输出都放在本地，默认优先走 Hugging Face。

bash scripts/inference/prepare_model_infer.sh <model-id> --verify-env-only
bash scripts/inference/prepare_model_infer.sh <model-id> --download
worldfoundry-eval zoo model-download --model-id <model-id> --check-local --json

python scripts/setup/prepare_benchmark_assets.py \
  --benchmark-id <benchmark-id> \
  --json

python scripts/setup/prepare_benchmark_assets.py \
  --benchmark-id <benchmark-id> \
  --write-env "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/<benchmark-id>.env" \
  --create-dirs

source "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/<benchmark-id>.env"

仅当 gated 资产的使用条款已经接受时，才设置 Hugging Face token：

export HF_TOKEN=<your-huggingface-token>

完整 cache 和路径规则见 本地资产。

3. TUI

不想记 model ID、benchmark ID 和命令参数时，用 TUI。它读取的就是 CLI 使用的同一套 manifest，会展示可选项，并且可以在真正启动昂贵任务前打印最终命令。

python -m pip install -e ".[tui]"
worldfoundry-eval tui

只生成命令、不进入交互界面：

worldfoundry-eval tui \
  --model-id <model-id> \
  --benchmark-id <benchmark-id> \
  --print-command

4. CLI

CLI 适合脚本、批量任务和可复现记录。不要靠猜 ID，先跑 discovery 命令：

worldfoundry-eval zoo models --json
worldfoundry-eval zoo benchmarks --json
worldfoundry-eval zoo model-download --model-id <model-id> --check-local --json

可复现、写进文档的第一次推理命令是 worldfoundry-eval run <id> --pipeline.task-profile …。<id> 和 task profile 从模型页复制；worldfoundry-eval run <id> --help 会列出该模型的 typed flag。

worldfoundry-eval run <model-id> \
  --pipeline.task-profile <task-profile> \
  --output-dir tmp/worldfoundry_infer/<model-id>

选哪条命令。 日常可复现运行、以及模型页上的命令，用 worldfoundry-eval run。只有 Workspace 视觉冒烟才用 python -m worldfoundry.studio.workspace_job infer。入口对照见 CLI 命令入口。

Workspace 视觉冒烟（与 Studio UI 提交的是同一条 job 路径）：

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

完整命令说明见 CLI。状态用词见 运行状态。

5. 推理

推理只产出 artifact，本身不是 benchmark evidence。

实际工作流建议是：先生成小批量，检查输出内容，确认目录结构，再扩展到目标 benchmark 要求的完整 prompt set。

需要反复查看生成结果时，启动 workspace：

bash scripts/workspace/run_workspace.sh

打开 http://127.0.0.1:7870/，评分前先检查输出：

find tmp/worldfoundry_infer/<model-id> -maxdepth 2 -type f | head

更多细节见 运行推理 和 Studio。

6. 评测

一个 benchmark run 需要三个具体输入。如果缺少任何一个，runner 应该产出 blocked scorecard，而不是静默给出看似能上 leaderboard 的分数。

• Benchmark assets — Prompt/task metadata、reference 文件、official result、judge credentials、simulator assets 或 metric checkpoints。
• Candidate artifacts — 模型产出的 videos、frames、rollouts、traces，或 official-shaped result dump。
• Runner mode — official-validation 导入已有 official-shaped 结果；official-run 从生成产物计算分数。

worldfoundry-eval zoo benchmark-run \
  --benchmark-id <benchmark-id> \
  --mode official-validation \
  --official-results-path /path/to/official/results-or-report \
  --generated-artifact-dir /path/to/generated/artifacts \
  --output-dir tmp/<benchmark-id>/official-validation \
  --json

worldfoundry-eval zoo benchmark-run \
  --benchmark-id <benchmark-id> \
  --mode official-run \
  --generated-artifact-dir /path/to/generated/artifacts \
  --output-dir tmp/<benchmark-id>/official-run \
  --json

worldfoundry-eval run \
  --benchmark <benchmark-id> \
  --model <model-id> \
  --mode official-run \
  --output-dir tmp/<benchmark-id>/<model-id> \
  --json

详细说明