快速开始

配置环境、准备资产、使用 TUI 或 CLI，然后运行推理与评测。

最后更新: 2026年7月22日

本页内容

使用流程前置条件 1. 环境配置 2. 资产准备 3. TUI 4. CLI 5. 推理 6. 评测详细说明

本指南覆盖从 clone 到一条可 review WorldFoundry run 的最短完整路径：

环境配置
资产准备
TUI
CLI 推理
产物检查
评测

大多数运行虽然模型和 benchmark 不同，但流程是一样的：先让 Python 环境可 import，再发现稳定 ID，只准备必要 checkpoint 与 benchmark 资产，生成并检查 artifact，最后才对 artifact 打分。

提示

浏览 catalog 和检查 readiness 不需要 GPU 或模型权重。如果你只是判断 WorldFoundry 是否覆盖目标系统，可以完成环境与 discovery 检查、阅读 blocker，然后在下载资产之前停止。

使用流程

创建 conda 环境，并 source WorldFoundry 的本地路径变量。

只准备本次运行需要的模型 checkpoint、benchmark 数据和 metric 资产。

想交互式选模型和 benchmark 就用 TUI；脚本化运行就用下面的 CLI 命令。

先跑推理生成产物。只有产物目录符合 benchmark layout 后，再启动评测。

前置条件

操作系统： 推荐 Linux，用于 GPU 推理和大多数 benchmark runner
Python： 通过 WorldFoundry 统一 conda 环境使用 3.10+
可选： 支持 CUDA 的 GPU、用于 gated checkpoint 的 Hugging Face token

说明

没有权重也可以浏览 catalog 和检查 readiness。只有在你选定具体模型 run 并开始下载资产后，才会进入昂贵路径。

1. 环境配置

Bootstrap 会创建默认 WorldFoundry runtime，并写出一份本地 shell 文件，里面包含 CLI、Studio 和评测 runner 会用到的路径。每次打开新 shell 后都应该先 source 这个文件。

默认安装共享路径运行前检查

在仓库根目录执行：

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}"

共享机器上，把 dataset、checkpoint 和输出放到 git 外：

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

下一步

按模型和 benchmark 拆分的环境映射见环境配置。当某个模型需要额外 conda profile，或者某个 benchmark evaluator 依赖统一环境之外的 metric package 时，到那一页查。

2. 资产准备

WorldFoundry 的可执行代码在仓内。Checkpoint、dataset、metric 权重、reference 文件和生成输出放在本地，默认优先走 Hugging Face。

重要

模型资产和 benchmark 资产是两类东西。模型 checkpoint 用来生成候选 artifact；benchmark 资产定义要生成什么、输出应该怎么命名、以及计算分数需要哪些文件或 metric 权重。

模型Benchmark

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

先让 WorldFoundry 打印 asset plan：

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

不想记模型 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

说明

TUI 不会绕过 checkpoint、dataset、license 或环境缺失。如果它为某个 benchmark 打印了命令，但对应资产还没准备好，请先跑 benchmark asset preparation。

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

命令行推理：

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

图生视频或其他条件生成模型：

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>

完整命令说明见 CLI。

5. 推理

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

重要

一个视频在 Studio 里看起来正确，但如果文件名、prompt 覆盖、split 或 metadata 不符合 benchmark runner 的要求，后续评测仍然可能失败。

实际工作流建议是：先生成小批量，检查输出内容，确认目录结构，再扩展到目标 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 的分数。

Input	含义
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` 从生成产物计算分数。

Official validationOfficial 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

如果生成产物已经准备好，并且仓内 runner 能计算指标：

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

如果 model-zoo 和 benchmark-zoo 支持一条命令完成生成加评分：

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

提示

先看 scorecard.json。公开 leaderboard 复现必须满足完整资产、完整生成产物和 benchmark-specific eligibility flags。

快速开始

环境配置

本地资产

TUI

CLI

Benchmark Hub