---
title: Embodied 官方运行准备
description: 克隆 WorldFoundry 后，如何配置 checkpoint、Docker simulator 资产和结果路径，并完成具身 benchmark 测评。
---

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

两类测评 surface：

- **原生闭环 simulator** (`ai2thor`, `behavior1k`, `calvin`, `kinetix`, `libero`, `libero-mem`, `libero-plus`, `libero-pro`, `maniskill2`, `maniskill`, `mikasa`, `molmospaces`, `rlbench`, `robocasa`, `robocerebra`, `robomme`, `robotwin`, `simpler-env`, `vlabench`) — official result import、in-tree simulator API、Docker-backed rollout hooks
- **仅结果导入** (`bridgedata-v2`, `metaworld`) — 归一化官方格式的结果文件

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

---

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

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

```bash
worldfoundry-eval zoo benchmarks --json
```

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

---

## 第一步：指定你的根目录

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

```bash
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 脚本（只生成模板和占位目录，不会替你下载大文件）：

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

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

- `embodied_official_env.sh` — 可 `source` 的 env 模板；**你已 export 的变量优先**（`${VAR:-default}`）
- `local_assets_manifest.yaml` — 本地 asset 清单；可复制到 git 外并通过 `WORLDFOUNDRY_LOCAL_ASSET_MANIFEST` 指向
- `check_repo_assets.sh` — 检查已配置的 source/runtime 根目录，并报告缺失路径
- `download_public_assets.sh` — 公开 HF 资源下载命令
- `validate_official_results.sh` — rollout 完成后的批量导入命令

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

```bash
# 若 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_*}` 占位符后：

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

---

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

- **验证框架接线** — `worldfoundry-eval zoo benchmarks --json`。需要 GPU / 资产：否
- **Official result import** — `worldfoundry-eval zoo benchmark-run --benchmark-id robotwin --mode official-validation --official-results-path <official_results.json> --output-dir tmp/benchmark_zoo/official_validation/robotwin --json`。需要 GPU / 资产：否
- **检查还缺哪些 env / 路径** — `worldfoundry-eval zoo benchmark-show --benchmark-id robotwin --json`。需要 GPU / 资产：否（会列出缺失项）
- **导入已有 official 结果** — 见下文“导入官方结果”。需要 GPU / 资产：只需结果文件
- **完整 simulator rollout** — 在上游 repo 内按官方文档跑。需要 GPU / 资产：是

---

## 环境策略

优先使用统一 CUDA 环境：

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

- **LIBERO、CALVIN、RoboCasa、MiKASA、RoboCerebra、RoboMME** — 推荐环境：`worldfoundry-unified-cu128`。何时独立环境：robosuite/MuJoCo pin 冲突时
- **LIBERO-Plus** — 推荐环境：`libero-plus` profile。何时独立环境：与 base LIBERO 包可能不共存
- **BEHAVIOR-1K** — 推荐环境：OmniGibson/Isaac Sim 独立环境。何时独立环境：需接受上游 terms + 大型资产
- **Kinetix** — 推荐环境：JAX 独立环境
- **RLBench** — 推荐环境：CoppeliaSim/PyRep 独立环境
- **RoboTwin、VLABench、ManiSkill2、SimplerEnv** — 推荐环境：导入用统一环境；rollout 用外部 simulator runtime。何时独立环境：SAPIEN/Curobo 等
- **AI2-THOR** — 推荐环境：外部 simulator runtime。何时独立环境：Unity 二进制 + CloudRendering/X11
- **Octo/OpenPI 系 policy** — 推荐环境：按 model profile

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

---

## Benchmark 环境变量参考

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

<KvCatalog heading="Benchmark" vars rows={[
    { name: <><code>ai2thor</code></>, description: <>{"eval config 中的 "}<code>scene</code>{" / "}<code>benchmark_kwargs</code></>, reads: [{ label: "Policy checkpoint", value: "policy checkpoint 或 external policy server" }, { label: "Official results", value: <><code>WORLDFOUNDRY_AI2THOR_RESULTS_PATH</code></> }] },
    { name: <><code>libero</code></>, description: <><code>WORLDFOUNDRY_LIBERO_SUITE</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_LIBERO_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_LIBERO_RESULTS_PATH</code></> }] },
    { name: <><code>robotwin</code></>, description: <><code>WORLDFOUNDRY_ROBOTWIN_TASK_CONFIG</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_ROBOTWIN_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_ROBOTWIN_RESULTS_PATH</code></> }] },
    { name: <><code>robomme</code></>, description: <><code>WORLDFOUNDRY_ROBOMME_SUITE</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_ROBOMME_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_ROBOMME_RESULTS_PATH</code></> }] },
    { name: <><code>calvin</code></>, description: <><code>WORLDFOUNDRY_CALVIN_SPLIT</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_CALVIN_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_CALVIN_RESULTS_PATH</code></> }] },
    { name: <><code>robocasa</code></>, description: <><code>WORLDFOUNDRY_ROBOCASA_SUITE</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_ROBOCASA_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_ROBOCASA_RESULTS_PATH</code></> }] },
    { name: <><code>maniskill2</code></>, description: <><code>WORLDFOUNDRY_MANISKILL2_SUITE</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_MANISKILL2_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_MANISKILL2_RESULTS_PATH</code></> }] },
    { name: <><code>rlbench</code></>, description: <><code>WORLDFOUNDRY_RLBENCH_TASK_SPLIT</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_RLBENCH_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_RLBENCH_RESULTS_PATH</code></> }] },
    { name: <><code>behavior1k</code></>, description: <><code>WORLDFOUNDRY_BEHAVIOR1K_TASK_SPLIT</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_BEHAVIOR1K_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_BEHAVIOR1K_RESULTS_PATH</code></> }] },
    { name: <><code>simpler-env</code></>, description: <><code>WORLDFOUNDRY_SIMPLERENV_SUITE</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_SIMPLERENV_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_SIMPLERENV_RESULTS_PATH</code></> }] },
    { name: <><code>vlabench</code></>, description: <><code>WORLDFOUNDRY_VLABENCH_TASK_SPLIT</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_VLABENCH_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_VLABENCH_RESULTS_PATH</code></> }] },
    { name: <><code>bridgedata-v2</code></>, description: <><code>WORLDFOUNDRY_BRIDGEDATA_V2_SPLIT</code></>, reads: [{ label: "Policy checkpoint", value: <><code>WORLDFOUNDRY_BRIDGEDATA_V2_POLICY_CHECKPOINT</code></> }, { label: "Official results", value: <><code>WORLDFOUNDRY_BRIDGEDATA_V2_RESULTS_PATH</code></> }] }
  ]} />

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

---

## 验证与导入

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

```bash
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 数据集。
验证运行不能作为排行榜证据。

---

## 发版维护说明

Maintainer 的 release gate 与 `official_benchmark_verified` 标注流程见 [验证证据](/zh/docs/reference/validation)。