--- title: 本地资产 description: 从哪里查来源、下载到哪里、用什么命令准备 checkpoint/dataset/repo。 --- ## 0. 前置条件 当命令提示缺 checkpoint、dataset、metric 权重、生成输出或官方结果文件时，优先看这一页。WorldFoundry 把这些大型或带 license 的文件放在 git 外；仓库内保存代码和 manifest，本机或共享存储保存 manifest 引用的资产。 典型路径：用 `worldfoundry-eval zoo ... --json` 查看模型或 benchmark ID；评测时再生成单个 benchmark 的 asset plan；只补齐本次运行需要的路径。使用框架不需要提前准备所有 benchmark 资产。统一 conda 环境见 [环境配置](/zh/docs/reference/environments)。 安装 Hugging Face Hub 包。`hf` / `huggingface-cli` 是可选入口；下载脚本会优先用 CLI，缺少时回退到 `huggingface_hub.snapshot_download`： ```bash python -m pip install "huggingface_hub[cli]" ``` Gated 模型/数据集需先在上游接受 license，再导出 token： ```bash export HF_TOKEN="hf_..." # 或 huggingface-cli login ``` 访问 huggingface.co 较慢时，可用 [HF-Mirror](https://hf-mirror.com) 的 `hfd`（依赖 `aria2c`）： ```bash wget https://hf-mirror.com/hfd/hfd.sh chmod a+x hfd.sh export WORLDFOUNDRY_HF_ENDPOINT=https://hf-mirror.com export HF_ENDPOINT="${WORLDFOUNDRY_HF_ENDPOINT}" ./hfd.sh Skywork/Matrix-Game-2.0 \ --local-dir "${WORLDFOUNDRY_HFD_ROOT:-${HOME}/.cache/worldfoundry/models/checkpoints/hfd}/Skywork--Matrix-Game-2.0" ./hfd.sh BestWishYsh/ChronoMagic-Pro --dataset \ --local-dir "${WORLDFOUNDRY_HFD_DATASET_ROOT:-${WORLDFOUNDRY_DATA_DIR:-${HOME}/.cache/worldfoundry/data}/datasets}/BestWishYsh__ChronoMagic-Pro" ``` Studio 默认不选择任何第三方镜像；如需让 Studio 子进程使用镜像，请显式设置 `WORLDFOUNDRY_HF_ENDPOINT`。直接运行 Hugging Face 工具时仍使用上例的 `HF_ENDPOINT`。Gated repo 需先在 Hugging Face 官网申请许可，再用 `--hf_token "${HF_TOKEN}"`。 镜像始终需要显式启用。Studio 派发的子进程会继承 shell 中已有的 `HF_ENDPOINT`，默认不会重定向到第三方镜像。若只想覆盖 WorldFoundry 管理的子进程，导出 `WORLDFOUNDRY_HF_ENDPOINT`；它优先于继承的 `HF_ENDPOINT`。 ## 1. 初始化目录与环境变量 这些目录是 runtime state，不是源码。放在容量足够的本地盘或共享文件系统上。 ```bash export WORLDFOUNDRY_HOME="${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}" export WORLDFOUNDRY_CACHE_DIR="${WORLDFOUNDRY_CACHE_DIR:-${WORLDFOUNDRY_HOME}/cache}" export WORLDFOUNDRY_DATA_DIR="${WORLDFOUNDRY_DATA_DIR:-${WORLDFOUNDRY_CACHE_DIR}/data}" export WORLDFOUNDRY_MODEL_DIR="${WORLDFOUNDRY_MODEL_DIR:-${WORLDFOUNDRY_CACHE_DIR}/models}" export WORLDFOUNDRY_CKPT_DIR="${WORLDFOUNDRY_CKPT_DIR:-${WORLDFOUNDRY_MODEL_DIR}/checkpoints}" export WORLDFOUNDRY_HFD_ROOT="${WORLDFOUNDRY_HFD_ROOT:-${WORLDFOUNDRY_CKPT_DIR}/hfd}" export WORLDFOUNDRY_HFD_DATASET_ROOT="${WORLDFOUNDRY_HFD_DATASET_ROOT:-${WORLDFOUNDRY_DATA_DIR}/datasets}" export WORLDFOUNDRY_ARTIFACT_DIR="${WORLDFOUNDRY_ARTIFACT_DIR:-${WORLDFOUNDRY_HOME}/artifacts}" export HF_HOME="${HF_HOME:-${WORLDFOUNDRY_HOME}/huggingface}" export HF_HUB_CACHE="${HF_HUB_CACHE:-${HF_HOME}/hub}" mkdir -p \ "${WORLDFOUNDRY_HFD_ROOT}" \ "${WORLDFOUNDRY_HFD_DATASET_ROOT}" \ "${WORLDFOUNDRY_CACHE_DIR}/repos" \ "${WORLDFOUNDRY_ARTIFACT_DIR}/runs" ``` 共享机器可用 bootstrap 或 Workspace 参数指定根目录： ```bash 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 source tmp/worldfoundry_unified_env.sh ``` ```text parent/ WorldFoundry/ ckpt/ data/ ``` 未导出 `WORLDFOUNDRY_CKPT_DIR` / `WORLDFOUNDRY_DATA_DIR` 时，`scripts/workspace/run_workspace.sh` 会在同级 `ckpt/`、`data/` 存在时自动使用。CI 中建议显式传参： ```bash bash scripts/workspace/run_workspace.sh \ --ckpt-dir /path/to/ckpt \ --data-dir /path/to/data ``` ### 路径命名约定 - **HF 模型 `org/name`** — 本地目录 `org--name`。示例：`Skywork/Matrix-Game-2.0` → `Skywork--Matrix-Game-2.0`。 - **HF 数据集 `org/name`** — 本地目录 `org__name`。示例：`lerobot/libero` → `lerobot__libero`。 - **GitHub `owner/repo`** — 常见为 `owner--repo`。示例：`Lifelong-Robot-Learning/LIBERO` → `Lifelong-Robot-Learning--LIBERO`。 **以 catalog 或 `local_assets.example.yaml` 里的 `path` 为准。** 部分具身 benchmark 仍引用 legacy 路径如 `cache/vla_va_wam/hf_datasets/org--name`，可按同样结构放置，或在 manifest 里改路径。 ## 2. 去哪里查“要下载什么” 资产需求写在 manifest 里，docs / TUI / CLI / runner 才能描述同一件事。优先看 CLI summary；需要核对准确来源时再打开 YAML。 ### 走读示例：`matrix-game-2`（模型 checkpoint） `worldfoundry/data/models/catalog/world_models/matrix-game-2.yaml` ```yaml id: matrix-game-2 name: Matrix-Game 2.0 checkpoints: - Skywork/Matrix-Game-2.0 checkpoint: repos: - id: Skywork/Matrix-Game-2.0 sha: f1729d99a80e0f07993a77d7dad4a3190e23c2c8 gated: false license: mit status: confirmed_public_hf runtime_profile: runtime-profile:matrix-game-2-universal-ref-image-seed42-15f official_sources: huggingface: - repo_id: Skywork/Matrix-Game-2.0 type: model status: confirmed ``` `checkpoints` / `checkpoint.repos[].id` 是要下载的仓库；`sha` 钉 revision；`runtime_profile` 指向期望本地路径与 env。同一信息也在 CLI JSON 里： ```bash worldfoundry-eval zoo model-show --model-id matrix-game-2 --json ``` 落盘后大致是： ```text ${WORLDFOUNDRY_HFD_ROOT}/hub/models--Skywork--Matrix-Game-2.0/ # 或： ${WORLDFOUNDRY_CKPT_DIR}/Skywork--Matrix-Game-2.0/ ``` ### 走读示例：`libero`（benchmark 资产） `worldfoundry/data/benchmarks/catalog/embodied/libero.yaml` ```yaml id: libero name: LIBERO official_sources: github: url: https://github.com/Lifelong-Robot-Learning/LIBERO huggingface_datasets: - repo_id: yifengzhu-hf/LIBERO-datasets revision: f13aa24a3da8c43c7225569f28c562979fa0e35a - repo_id: lerobot/libero revision: 1595a93b43aa055e55c127a4f0b4a99bb8035447 dataset_refs: - repo_id: yifengzhu-hf/LIBERO-datasets path: cache/vla_va_wam/hf_datasets/yifengzhu-hf--LIBERO-datasets - repo_id: lerobot/libero path: cache/vla_va_wam/hf_datasets/lerobot--libero runner: runtime: root_env: WORLDFOUNDRY_LIBERO_ROOT results_path_env: WORLDFOUNDRY_LIBERO_RESULTS_PATH required_assets: - LIBERO dataset root or LeRobot conversion - suite-specific policy checkpoint - official rollout logs/result dump ``` `dataset_refs[].repo_id` 是 HF 下载源；`path` 是数据根下的期望相对路径；`required_assets` / `*_env` 列出其余要准备的东西。把 catalog + task + profile 合成清单： ```bash worldfoundry-eval zoo benchmark-show --benchmark-id libero --json python scripts/setup/prepare_benchmark_assets.py \ --benchmark-id libero \ --json ``` 重点看 planner 字段：`assets.data`、`assets.checkpoints`、`env.api_or_secret`、`download_hints.hf`、`commands.official_runtime`、`commands.official_result_import`。 ## 3. 模型 checkpoint（推理） ### 感知与 3D 可视化 checkpoint 以下仓内 runtime 通过统一 base-model asset registry 解析 checkpoint；源码不依赖某台机器的绝对路径。

能力

UniDepth V2 与 UniK3D 权重采用 CC-BY-NC-4.0；下载或再分发前需要核对上游的非商业使用条款。 先查看准确 URL、解析后路径、大小校验和 export 命令，不执行下载： ```bash worldfoundry-eval models assets \ --capability sam2 \ --capability mobile_sam \ --capability repvit_sam \ --capability midas_v21_small_256 \ --capability unidepth_v2_vitl14 \ --capability unik3d_vitl \ --json ``` 补齐缺失文件时添加 `--execute-downloads`。SAM2、UniDepth V2 与 UniK3D 的 Hugging Face 下载会遵循 `HF_ENDPOINT`；MobileSAM、RepViT-SAM 与 MiDaS 使用各自官方 GitHub repo/release URL： ```bash export HF_ENDPOINT=https://hf-mirror.com worldfoundry-eval models assets \ --capability sam2 \ --capability mobile_sam \ --capability repvit_sam \ --capability midas_v21_small_256 \ --capability unidepth_v2_vitl14 \ --capability unik3d_vitl \ --execute-downloads ``` 先 plan，确认存储与 license 后再 execute： ```bash worldfoundry-eval zoo model-download \ --model-id matrix-game-2 \ --cache-dir "${WORLDFOUNDRY_HFD_ROOT}" \ --check-local \ --json worldfoundry-eval zoo model-download \ --model-id matrix-game-2 \ --cache-dir "${WORLDFOUNDRY_HFD_ROOT}" \ --execute \ --disable-xet \ --check-local \ --json ``` 备选： ```bash bash scripts/inference/prepare_model_infer.sh matrix-game-2 --download hf download Skywork/Matrix-Game-2.0 \ --revision f1729d99a80e0f07993a77d7dad4a3190e23c2c8 \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/Skywork--Matrix-Game-2.0" ``` ### 走读示例：Echo-Memory Echo recipes 共用 Wan2.1 T2V 1.3B backbone，但分别要求 `Echo-Team/Echo-Memory` 下的不同文件。截至 2026-07-20，官方 HF `main` 只保留 `context_k1/epoch-0.safetensors`。其他 Echo model ID 仍以精确预期 文件名保留在 catalog 中，但上游状态是 `unreleased_by_upstream` 或 `retracted_misaligned_by_upstream`；不能用 K=1 权重代替它们。 将当前公开 recipe 与钉定的 backbone 放入 runtime layout，再创建正常 HFD alias，全程不复制 tensor： ```bash export HF_ENDPOINT=https://hf-mirror.com hf download Echo-Team/Echo-Memory \ context_k1/epoch-0.safetensors \ --revision 7645f33efbfd02c58dc471570d0c7bd6a50eec83 \ --local-dir "${WORLDFOUNDRY_CKPT_DIR}/Echo-Memory" hf download Wan-AI/Wan2.1-T2V-1.3B \ --revision 37ec512624d61f7aa208f7ea8140a131f93afc9a \ --local-dir "${WORLDFOUNDRY_CKPT_DIR}/Wan2.1-T2V-1.3B" bash scripts/setup/link_hf_checkpoints.sh \ --repo Echo-Team/Echo-Memory=Echo-Memory \ --repo Wan-AI/Wan2.1-T2V-1.3B=Wan2.1-T2V-1.3B ``` 标准 checker 现在同时检查 recipe-specific filename 与仓库，因此只有 K=1 的 cache 不会把 K=20 或 SSM 模型误报为 ready： ```bash worldfoundry-eval zoo model-download \ --model-id echo-memory-context-k1 \ --check-local \ --json ``` 研究者若有未公开 checkpoint，可放到对应 runtime profile 声明的精确 `checkpoint_path`，再建立相同 HFD alias。在严格 checkpoint 加载与 CUDA artifact validation 通过前，catalog entry 应继续保持 blocked。 ### 走读示例：Matrix-Game 3.5 第一、第三人称模型 ID 共用 Wan2.2、UMT5 与 DA3 资产，但分别绑定 `RiemannDynamics/Matrix-Game-3.5-Base` 中的不同文件。一次下载两个人称权重， 两个不可变 recipe 就都能通过标准 HFD alias 解析。使用 HF-Mirror 时先设置 `HF_ENDPOINT=https://hf-mirror.com`。DA3 checkpoint 有独立的 CC-BY-NC-4.0 license，而 Matrix-Game 与 Wan checkpoint 是 Apache-2.0； 使用时需要分别遵守各依赖的上游条款。 ```bash hf download RiemannDynamics/Matrix-Game-3.5-Base \ --revision 40c172355efa32d4e2a44076569e310807788f8a \ --include first-person.safetensors \ --include third-person.safetensors \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/RiemannDynamics--Matrix-Game-3.5-Base" hf download Wan-AI/Wan2.2-TI2V-5B \ --revision 921dbaf3f1674a56f47e83fb80a34bac8a8f203e \ --include 'diffusion_pytorch_model*.safetensors' \ --include models_t5_umt5-xxl-enc-bf16.pth \ --include Wan2.2_VAE.pth \ --include 'google/umt5-xxl/*' \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/Wan-AI--Wan2.2-TI2V-5B" hf download depth-anything/DA3NESTED-GIANT-LARGE-1.1 \ --revision b2359bdf726fb44ef62acca04d629dcf158053e7 \ --include config.json \ --include model.safetensors \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/depth-anything--DA3NESTED-GIANT-LARGE-1.1" ``` 不加载模型张量即可检查两个 recipe 的本地资产： ```bash worldfoundry-eval zoo model-download \ --model-id matrix-game-3.5-first-person \ --check-local \ --json worldfoundry-eval zoo model-download \ --model-id matrix-game-3.5-third-person \ --check-local \ --json ``` ### 走读示例：Cosmos 1 与 Cosmos 2 GEN3C 显式依赖四组资产：7B transformer、Tokenize1 codec、T5-11B 与 MoGe depth model。Cosmos Predict2 使用所选 Video2World transformer、 `tokenizer/tokenizer.pth` 和同一个 T5-11B encoder。Predict2 repo 受 gated 限制，使用镜像前仍需先完成鉴权。 ```bash export HF_ENDPOINT=https://hf-mirror.com hf download nvidia/GEN3C-Cosmos-7B \ --revision 9bcfdb4f3924f41376daeadf6200826c12a3bf8e \ --include model.pt \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--GEN3C-Cosmos-7B" hf download nvidia/Cosmos-Predict2-2B-Video2World \ --revision f50c09f5d8ab133a90cac3f4886a6471e9ba3f18 \ --include model-720p-16fps.pt \ --include tokenizer/tokenizer.pth \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Predict2-2B-Video2World" hf download google-t5/t5-11b \ --revision 90f37703b3334dfe9d2b009bfcbfbf1ac9d28ea3 \ --include pytorch_model.bin --include config.json \ --include spiece.model --include tokenizer.json \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/google-t5--t5-11b" ``` GEN3C 还需按 runtime profile 下载 `nvidia/Cosmos-Tokenize1-CV8x8x8-720p` 与 `Ruicheng/moge-vitl`。Predict2 14B 切换为 `nvidia/Cosmos-Predict2-14B-Video2World` revision `03b03a377fede782647afac998f674d9f358e319`。 ### 走读示例：Cosmos 2.5 Cosmos Predict 与 Transfer 共用 Predict 2B 的 `tokenizer.pth` Wan codec 和 Reason1 language model，只需要下载所选 transformer 与这两组共享资产。 Transfer 当前固定官方 `general/edge` 精确 revision；目录存在但缺少该文件 不能算 ready。需要镜像时先设置 `HF_ENDPOINT=https://hf-mirror.com`。 ```bash hf download nvidia/Cosmos-Predict2.5-2B \ --revision f176dc95b4a70f53ce01c4b302851595e7322b00 \ --include tokenizer.pth \ --include 'base/post-trained/81edfebe-bd6a-4039-8c1d-737df1a790bf_ema_bf16.pt' \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Predict2.5-2B" hf download nvidia/Cosmos-Reason1-7B \ --revision 375e24000b24baed78f4618d3dd779e47cd96323 \ --include 'model*.safetensors' \ --include model.safetensors.index.json \ --include tokenizer.json \ --include tokenizer_config.json \ --include chat_template.json \ --include config.json \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Reason1-7B" hf download nvidia/Cosmos-Transfer2.5-2B \ --revision bd963eabcfc2d61dc4ea365cacf41d45ac480aa5 \ --include 'general/edge/ecd0ba00-d598-4f94-aa09-e8627899c431_ema_bf16.pt' \ --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Transfer2.5-2B" ``` Predict 14B 应改为下载 `nvidia/Cosmos-Predict2.5-14B` revision `71ebf3e8af30ecfe440bf0481115975fcc052b46` 下的 `base/post-trained/e21d2a49-4747-44c8-ba44-9f6f9243715f_ema_bf16.pt`， Reason1 与 VAE 资产保持不变。 其他模型按各自 catalog 里的 `repo_id` / `revision` 同样下载。共享机器上若已有 snapshot，设置 `WORLDFOUNDRY_MODEL_DIR` 并用软链镜像 HF cache 名，不要复制权重： ```bash bash scripts/setup/link_hf_checkpoints.sh \ --ckpt-dir "${WORLDFOUNDRY_CKPT_DIR}" \ --hfd-root "${WORLDFOUNDRY_HFD_ROOT}" \ --hf-hub-cache "${HF_HUB_CACHE}" \ --repo Skywork/Matrix-Game-2.0=Matrix-Game-2.0 \ --default-world ``` 优先走原生 HF 加载（`from_pretrained`、`snapshot_download`、`HF_HOME` / `HF_HUB_CACHE`）。`${WORLDFOUNDRY_CKPT_DIR}` 软链只给需要固定目录布局的上游 runtime。VBench 系 metric 权重见对应 [Benchmark Hub](/zh/docs/evaluation/benchmark-hub) / [指标](/zh/docs/evaluation/metrics) 页，或 planner JSON 的 `assets.checkpoints`。 ## 4. Benchmark 数据集 WorldFoundry **不会** bulk-download 所有 benchmark 数据集。先生成 plan，再跑 `download_hints.hf`（或 `source_provenance` 里的官方 URL）： ```bash python scripts/setup/prepare_benchmark_assets.py \ --benchmark-id \ --json python scripts/setup/prepare_benchmark_assets.py \ --benchmark-id \ --write-env "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/.env" \ --create-dirs source "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/.env" ``` 手动下载示例： ```bash hf download Howieeeee/WorldScore \ --repo-type dataset \ --local-dir "${WORLDFOUNDRY_DATA_DIR}/datasets/Howieeeee__WorldScore" ``` Gated 数据集先接受上游 license 并设置 `HF_TOKEN`。各 benchmark 的布局与运行要求见 [Benchmark Hub](/zh/docs/evaluation/benchmark-hub)。 ## 5. `local_assets` manifest 把示例拷到 git 外，并用环境变量指向它： ```bash cp worldfoundry/data/benchmarks/local_assets.example.yaml \ "${WORLDFOUNDRY_HOME}/local_assets.yaml" export WORLDFOUNDRY_LOCAL_ASSET_MANIFEST="${WORLDFOUNDRY_HOME}/local_assets.yaml" ``` - **`repo`** — 已有 source/runtime root。典型命令：设置 `WORLDFOUNDRY__ROOT=`。 - **`dataset`** — HF dataset snapshot。典型命令：`hf download --repo-type dataset --local-dir `。 - **`checkpoint`** — 模型权重。典型命令：`hf download --local-dir `。 - **`simulator_asset`** — 仿真器文件。典型命令：按各 benchmark 文档手动安装。 - **`result_dump`** — 上游官方结果。典型命令：跑完上游 evaluator 后拷贝。 具身仿真器 root 与 helper 脚本见 [Embodied official runtime](/zh/docs/evaluation/embodied-official-runtime)。