运行环境

介绍

运行环境指一个模型或基准预期的依赖和启动上下文：Python 包、CUDA/Torch 桶、可选系统工具、checkpoint 布局、设备假设和命令形状。

仓库元数据里仍然使用 runtime_profile 这个字段，因为它指向 worldfoundry/data/models/runtime/profiles/<model-id>.yaml 中的一条具体环境记录。在面向读者的文档里，这个概念统一称为运行环境。

WorldFoundry 统一使用 conda 路径。文档里的标准流程为主框架创建一个命名 conda 环境；只有上游 simulator 或 official runtime 需要隔离时，才创建单独 conda 环境。

1. 模型推理默认从 bash scripts/setup/bootstrap_worldfoundry.sh 开始。
2. 用 bash scripts/setup/model_env_install.sh --list 查看所有 model-to-env 映射；需要某个模型的精确环境时使用 --model <model-id>。
3. 当解析出的 profile 是 worldfoundry-unified-<tier> 时，继续使用统一环境。
4. 只有 runtime/environments/<category>/<model-id>.yaml 记录 ABI 或 simulator 约束时，才切换到专用环境。
5. 只有 official metrics、reference metrics 或 physics stacks 使用 benchmark-specific scripts。

Clone 后可运行的 setup 脚本

下面这些脚本都从仓库根目录运行。它们是开源发布面的一部分，不是本地临时 笔记。

• scripts/setup/bootstrap_worldfoundry.sh — clone 后第一条命令。创建/验证统一环境，写出 tmp/worldfoundry_unified_env.sh，可选安装模型专用环境，可选准备模型资产，并打印 Workspace 启动命令。
• scripts/setup/unified_install.sh — 只安装主 GPU runtime。创建 worldfoundry-unified-<cuda-tier>，安装 requirements/worldfoundry-unified.txt、PyTorch CUDA wheels、可选 flash-attn，并做 import/CUDA 检查。
• scripts/setup/model_env_install.sh — 逐模型解析环境。读取 worldfoundry/data/models/runtime/environments/**；能合并进统一环境的 profile 会回到统一环境，只有硬 ABI 冲突才创建专用环境。
• scripts/inference/prepare_model_infer.sh — 逐模型准备 checkpoint/Hugging Face 资产。默认是 plan/check-local；确认 license、gated access 和存储后才加 --download。
• scripts/workspace/run_workspace.sh — 从已激活 runtime 启动浏览器 Workspace。显式设置 PYTHONPATH=.、WORLDFOUNDRY_WORKSPACE_MAX_JOBS 和 WORLDFOUNDRY_CKPT_DIR。

推荐 fresh-clone 路径：

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

环境 prefix 是机器本地产物。如果已有 checkout 报缺少 python3.x、原生 模块或 libssl/libcrypto，应重建环境，或先运行公开验证入口：

bash scripts/setup/bootstrap_worldfoundry.sh --verify-only

下载 checkpoint 前，先审查某个模型的环境和资产计划：

bash scripts/setup/bootstrap_worldfoundry.sh \
  --with-model matrix-game-2 \
  --prepare-model matrix-game-2

确认准备好存储和权限后，再下载公开资产：

export HF_TOKEN=<your-token-if-needed>
bash scripts/setup/bootstrap_worldfoundry.sh \
  --with-model matrix-game-2 \
  --prepare-model matrix-game-2 \
  --download-model-assets

--download-model-assets 会转发到对应模型的准备脚本。它不会绕过 Hugging Face gated 模型限制；用户仍需先在 HF 接受条款，并自行提供 HF_TOKEN 或 HUGGING_FACE_HUB_TOKEN。

多模型机器先安装一次统一环境，再显式验证例外环境：

bash scripts/setup/bootstrap_worldfoundry.sh \
  --with-model lingbot-world \
  --with-model octo \
  --prepare-model lingbot-world \
  --prepare-model octo

setup 后启动 Workspace：

source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"
PYTHONPATH=. WORLDFOUNDRY_WORKSPACE_MAX_JOBS=8 \
python -m worldfoundry.studio.workspace_app --host 127.0.0.1 --port 7870

如果 datasets 或 checkpoints 要放到共享存储，显式传入路径：

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

Runtime 变量

bootstrap_worldfoundry.sh 和 unified_install.sh 会写出同一套可 source 的 env 文件。这个文件应保留在本机；里面是路径，不应包含密钥。

公开 checkpoint 优先使用 Hugging Face 原生加载策略：from_pretrained、 snapshot_download 和标准 HF cache 变量。WORLDFOUNDRY_CKPT_DIR 用于上游 runtime 需要固定目录布局的情况，或用软链保持官方路径而不重复复制大文件。

模型专用环境例外

所有模型默认都先从 worldfoundry-unified-<cuda-tier> 开始。只有下表这些 profile 存在真实 ABI 或框架族冲突时，才单独创建 conda 环境。

安装某个例外环境：

bash scripts/setup/model_env_install.sh --model <model-id>

准备某个模型时，优先使用 scripts/inference/prepare_model_infer.sh；它会先解析并 安装对应环境，再检查或下载资产。只有只想安装环境、不碰 checkpoint 时，才直接用 scripts/setup/model_env_install.sh。

EvalCrafter 是当前唯一明确的 benchmark metric 专用环境例外，不是生成模型例外； 见下一节。

统一环境但需要额外 runtime 条件

下表模型仍然使用 worldfoundry-unified-<cuda-tier>，但文档里必须写清楚额外的本地 资产、编译 wheel 或外部服务。这些都不是 clone 外部 repo 的理由；代码路径仍然在仓内。

Benchmark Metric 专用环境

大多数 benchmark contract 检查和 official-result normalizer 可以在统一环境中运行。 如果完整官方指标套件会污染模型推理环境，则使用单独 conda profile。安装仍然走 同一个公开入口：

bash scripts/setup/model_env_install.sh --model evalcrafter

EvalCrafter 是当前明确的 benchmark 例外。已有 final_result.txt 的归一化可以在 worldfoundry-unified-<tier> 中完成；完整官方 metric suite 需要 worldfoundry-evalcrafter-metrics，因为官方 scorer 同时依赖 TensorFlow/DeepFace、PaddleOCR、DOVER/scikit-video、PyTorch 视频指标和 MMAction2/MMCV action recognition。

可复用 foundation model 放在 worldfoundry/base_models，EvalCrafter runner 只保留 benchmark glue：

EvalCrafter metric 资产放到标准 checkpoint root，或显式设置变量：

export WORLDFOUNDRY_EVALCRAFTER_ROOT=worldfoundry/evaluation/tasks/execution/runners/evalcrafter/runtime/evalcrafter
export WORLDFOUNDRY_EVALCRAFTER_CHECKPOINTS_DIR="${WORLDFOUNDRY_CKPT_DIR}/evalcrafter"
export WORLDFOUNDRY_DOVER_CKPT="${WORLDFOUNDRY_EVALCRAFTER_CHECKPOINTS_DIR}/DOVER/pretrained_weights/DOVER.pth"
export WORLDFOUNDRY_VIDEOMAE_K400_CKPT="${WORLDFOUNDRY_EVALCRAFTER_CHECKPOINTS_DIR}/VideoMAE/vit-base-p16_videomaev2-vit-g-dist-k710-pre_16x4x1_kinetics-400_20230510-3e7f93b2.pth"

完整 EvalCrafter official run 还要求 generated-video 目录直接包含 0000.mp4 到 0699.mp4。runner 会在调用官方指标前拒绝外层 dataset root。

Embodied Simulator 环境

Host 侧只需要 Docker 和统一 WorldFoundry 环境：

bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
docker pull ghcr.io/allenai/vla-evaluation-harness/robotwin:latest
worldfoundry-eval embodied run \
  --config worldfoundry/data/benchmarks/eval_configs/embodied/robotwin/eval.yaml \
  --pull-docker

如果 benchmark config 直接写了 docker.image，或通过 worldfoundry/data/benchmarks/runtime_profiles/official/<benchmark>.yaml 解析出 docker.image，就会由 worldfoundry/evaluation/tasks/embodied/docker_runner.py 通过 Docker 启动。容器内 负责 simulator 依赖；host 侧只负责挂载 dataset/checkpoint/result，并提供 policy server endpoint。

常见问题排除 (Troubleshooting)

在处理涉及 CUDA、物理模拟器或外部评估器的复杂环境时，您可能会遇到以下问题：

1. CUDA 版本不匹配

现象：遇到 CUDA error: no kernel image is available for execution on the device 或者 PyTorch 找不到 GPU。 解决办法：确保主机的 NVIDIA 驱动足够新，能支持 Conda 安装的 CUDA 版本。如果您使用的是旧版驱动，可以在安装时强制指定旧的 CUDA bucket：

bash scripts/setup/unified_install.sh --cuda cu121

2. 缺失系统级依赖（针对 OpenGL/3D）

现象：运行具身模拟器或 3D benchmark 时，出现有关 libGL.so.1、EGL 或 headless 渲染失败的错误。 解决办法：安装必需的系统级图形库。在 Ubuntu/Debian 系统上：

sudo apt-get update && sudo apt-get install -y libgl1-mesa-glx libglib2.0-0

3. Flash Attention 安装失败

现象：在统一安装脚本编译 flash-attn 时卡住或报错。 解决办法：flash-attn 对 CUDA 编译器 (nvcc) 的版本匹配要求极其严格。请确保本机的 nvcc --version 和 PyTorch 携带的 CUDA 版本一致。如果实在无法编译，可以直接去官方 Release 页面下载对应的 pre-compiled wheel 手动安装。