Embodied 官方运行准备

你会用到什么

WorldFoundry 在仓库内提供具身 benchmark 的 结果归一化、CLI 和 simulator 接口（worldfoundry.evaluation.tasks.embodied）。Checkpoint、simulator 资产、Docker image 和 rollout 结果不会打进 git——这些路径由你在本机通过环境变量或 CLI 参数指定。

两类测评 surface：

integration_status: integrated 只表示接口已接入，不等于 leaderboard 已验证。未跑完官方 protocol 前，scorecard 保持 official_benchmark_verified=false。

快速开始（无需下载资产）

克隆仓库后，先确认测评框架本身可用：

worldfoundry-eval zoo benchmarks --json

这会确认 libero / robomme / robotwin 等条目可被 CLI 发现。不需要 GPU，也不需要 checkpoint。

第一步：指定你的根目录

所有路径都通过 WORLDFOUNDRY_* 环境变量 或 CLI 参数 解析。请把下面的占位符换成你机器上的实际目录：

export WORLDFOUNDRY_DATA_DIR="$HOME/worldfoundry-data"
export WORLDFOUNDRY_HFD_DATASET_ROOT="$HOME/worldfoundry-data"   # HF 数据集镜像根目录，可与 DATA_DIR 相同
export WORLDFOUNDRY_CKPT_DIR="$HOME/worldfoundry-checkpoints"
export WORLDFOUNDRY_MODEL_DIR="$HOME/worldfoundry-models"
export WORLDFOUNDRY_CACHE_DIR="$HOME/worldfoundry-cache"
export WORLDFOUNDRY_ARTIFACT_DIR="$HOME/worldfoundry-artifacts"
export WORLDFOUNDRY_MODEL_SOURCE_DIR="$HOME/worldfoundry-upstream-repos"  # 上游 benchmark / policy 代码 clone 根目录

目录 layout 没有唯一标准。 常见两种都可以：

• HF 平铺：在 WORLDFOUNDRY_HFD_DATASET_ROOT 下放 lerobot__libero、TianxingChen__RoboTwin2.0 等
• 自定义子树：在 WORLDFOUNDRY_DATA_DIR/datasets/... 下组织

只要对应的 WORLDFOUNDRY_*_ROOT / WORLDFOUNDRY_*_CHECKPOINT 指向真实文件即可。

第二步：生成 scaffold，再填你的路径

运行 scaffold 脚本（只生成模板和占位目录，不会替你下载大文件）：

PYTHONPATH=. ${WORLDFOUNDRY_UNIFIED_PYTHON} scripts/setup/prepare_embodied_official_assets.py \
  --create-dirs \
  --json

生成文件（默认在 tmp/benchmark_zoo/embodied_official_assets/，可用 --output-root 改）：

加载并覆盖为你自己的路径：

# 若 scaffold 在默认位置
source tmp/benchmark_zoo/embodied_official_assets/embodied_official_env.sh
bash tmp/benchmark_zoo/embodied_official_assets/check_repo_assets.sh

# 示例：把 LIBERO 指到你 clone 的位置
export WORLDFOUNDRY_LIBERO_ROOT="$WORLDFOUNDRY_MODEL_SOURCE_DIR/LIBERO"
export WORLDFOUNDRY_LIBERO_POLICY_CHECKPOINT="$WORLDFOUNDRY_CKPT_DIR/your-policy-for-libero"
export WORLDFOUNDRY_LIBERO_RESULTS_PATH="$WORLDFOUNDRY_ARTIFACT_DIR/runs/libero/official_results.json"

也可复制 worldfoundry/data/benchmarks/local_assets.example.yaml 到任意位置，编辑其中的 ${WORLDFOUNDRY_*} 占位符后：

export WORLDFOUNDRY_LOCAL_ASSET_MANIFEST=/path/to/your/local_assets_manifest.yaml

第三步：按目标选择验证深度

环境策略

优先使用统一 CUDA 环境：

bash scripts/setup/bootstrap_worldfoundry.sh --cuda cu128
source tmp/worldfoundry_unified_env.sh

查看 model 环境映射：bash scripts/setup/model_env_install.sh --list

Benchmark 环境变量参考

每个 benchmark 用独立 env 指向 你的 checkout、checkpoint 和结果文件：

上游代码根目录通常用 WORLDFOUNDRY_<BENCHMARK>_ROOT（例如 WORLDFOUNDRY_LIBERO_ROOT）。完整列表见 prepare_embodied_official_assets.py 生成的 embodied_official_env.sh。

验证与导入

导入官方结果（已有 rollout 输出时）：

worldfoundry-eval zoo benchmark-run \
  --benchmark-id libero \
  --mode official-validation \
  --official-results-path "$WORLDFOUNDRY_LIBERO_RESULTS_PATH" \
  --output-dir "$WORLDFOUNDRY_ARTIFACT_DIR/validation/libero" \
  --json

--official-results-path 和 --benchmark-data-root 也可直接在命令行指定，无需事先 export env。

检查输出中的 scorecard.json、raw_results.jsonl、evaluation/summary.json。official_benchmark_verified=false 在仅做 import 时是预期行为。

完整 Rollout

使用 Docker-backed official evaluator 或 VLA evaluation harness 运行指定 policy checkpoint，生成 result 文件，再用上一节的 official-validation 导入。

Rollout 前建议记录：benchmark id、上游 commit、simulator 版本、dataset split、checkpoint 路径、action/observation 约定、结果文件路径。

接入真实 policy 时，把 eval config 里的 model_id 换成已配置的 VLA policy，或通过 server.url 指向 external policy server；policy 返回 {"token": "forward"} 或等价离散 action 即可。

内置验证 fixture

零资产 validation 用的 minimal 结果在：

worldfoundry/data/test_cases/evaluation/embodied_fixtures/

覆盖 libero、robomme、robotwin，与真实 rollout 后的导入路径相同，但不构成 leaderboard 证据。

发版维护说明

Maintainer 的 release gate 与 official_benchmark_verified 标注流程见 验证证据。