RoboEvolve 快速开始

本文带你完成 RoboEvolve 的最小闭环：准备容器环境，运行 Lambda Sim 后端 smoke test，采集专家示范数据，准备训练数据，训练策略并获取 checkpoint，最后在评测容器中运行策略评测。示例任务为 adjust_bottle。

本流程使用数据采集、训练和评测三个隔离容器。开始前，请完成 Lambda Sim 运行环境准备，并准备共享存储、场景资产和对应容器镜像。

流程概览

本教程按以下顺序完成一条“环境 → 数据 → 训练 → 评测”路径：

步骤	操作	执行容器	本步结果	是否必需
1	准备环境	数据采集容器、训练容器和评测容器	三个容器的依赖、路径、设备和共享数据已准备。	是
2	运行 smoke test	数据采集容器	使用一个 episode 确认 RoboEvolve 可以启动 Lambda Sim 后端。	是
3	采集专家示范数据	数据采集容器	生成 HDF5、语言指令、场景信息和演示视频。	是
4	准备训练数据	训练容器	将步骤 3 的数据转换为目标策略所需格式，并生成 norm_stats.json。	是
5	训练策略并获取 Checkpoint	训练容器	使用步骤 4 的训练数据训练策略，并生成可供评测加载的 checkpoint。	是
6	启动策略评测	评测容器	启动 Policy Server 和 Eval Client，生成成功率、结果文件和视频。	是

完成步骤 1～3 后，可以确认仿真后端和数据采集链路可用。完成步骤 4～6 后，才算完成 RoboEvolve 的训练和评测闭环。

前提条件

容器环境

准备以下三个容器。训练和评测依赖不能与数据采集容器混用：

容器	镜像或目录	用途	需要预置的数据
数据采集容器	roboevolve_5.2.0_torch2.9.1post_axinfra-ektro_20260814_release，工作目录为 /workspace/RoboEvolve。	运行 RoboEvolve 任务、调用 Lambda Sim、采集专家示范数据。	RoboEvolve 源码、Lambda Sim 和 axinfra 运行依赖、assets_usd 场景资产、assets/ 下指向资产目录的软链接，以及 config/ 中的任务和采集配置。该容器不需要步骤 3 以前的数据。
训练容器	sh-harbor.mthreads.com/mcctest/musa-train:4.3.4_kuae2.1_20260109_torch2.7.1_ubuntu；Pi_05/RLinf 环境使用 jinxinghua_rlinf-pi05-musa-271。	将采集数据转换为训练格式，运行策略训练。	步骤 3 生成的 HDF5 和相关文件、目标策略的处理脚本和配置、策略基座模型及其 tokenizer 或资产文件，以及用于保存处理后数据、归一化统计和 checkpoint 的可写数据盘。
评测容器	harbor.mthreads.com:4433/robotwin/eval-musa:robotwin_eval_20260804_v0.1.0，工作目录为 /workspace/RoboTwin-lambdasim-eval。	加载策略 checkpoint，运行 Policy Server 和 Eval Client。	步骤 5 生成的 Torch checkpoint（至少包含 model.safetensors）、assets/<repo_id>/norm_stats.json、评测配置、RoboTwin/Lambda Sim 场景资产和评测脚本。S5000 评测不能直接加载 JAX/Orbax checkpoint。

共享数据和权限

开始前请确认：

• 已完成 Lambda Sim 运行环境准备，并确认三个容器使用与当前版本匹配的依赖。
• 三个容器可以访问同一份共享数据，或可以在步骤之间复制数据和 checkpoint。
• 数据采集容器可以访问 /workspace/RoboEvolve/assets_usd，并且 assets/embodiments、assets/desks、assets/objects 和 assets/manifest.json 使用绝对路径软链接指向该目录。
• 训练容器可以读取步骤 3 的 data/<task>/<mode>/，并可以写入处理后的训练数据、norm_stats.json 和 checkpoint。
• 评测容器可以读取 Torch checkpoint、归一化统计文件和评测场景资产。
• 数据采集和评测使用的 GPU 可用；训练容器根据策略配置准备对应数量的 MTT S5000 GPU。

当前验证范围

/home/ctrl/LambdaSim-master 提供 Lambda Sim 源码、USD 导入和渲染测试，不包含 RoboEvolve、RLinf、XPolicyLab 或评测容器脚本。完整闭环仍需要在对应容器和数据环境中执行验证。

步骤 1：准备环境

数据采集容器

进入数据采集容器的项目目录，并设置仿真环境变量：

cd /workspace/RoboEvolve
source scripts/setup_env.sh --configure
export MUSA_VISIBLE_DEVICES=5
export ROBOEVOLVE_BACKEND_SETUP=none
export USD_ASSETS_PATH=/workspace/RoboEvolve/assets_usd
export PYTHONPATH=/workspace/RoboEvolve:$PYTHONPATH

MUSA_VISIBLE_DEVICES=5 表示宿主机上的第 5 张卡对进程可见；进程内通常会将它重编号为 musa:0，因此仿真配置中的 gpu_ids 应使用进程内编号。

训练容器

在训练容器中设置训练侧变量：

export MTHREADS_VISIBLE_DEVICES=0,1
export XLA_PYTHON_CLIENT_MEM_FRACTION=0.8
export WANDB_MODE=disabled
export HF_ENDPOINT=https://hf-mirror.com

训练侧使用 MTHREADS_VISIBLE_DEVICES。不要用仿真侧的 MUSA_VISIBLE_DEVICES 代替训练侧变量。

评测侧的 PI05_MODEL_PATH、PI05_REPO_ID 和 PI05_DEVICE 在步骤 6 中设置，因为这些变量依赖步骤 5 生成的 checkpoint。

步骤 2：运行 smoke test

在数据采集容器中运行一个 episode，检查 RoboEvolve 是否可以启动 Lambda Sim 后端：

ROBOEVOLVE_BACKEND_SETUP=none \
  python -m roboevolve.collect_data adjust_bottle \
  --cfg config/mode/demo_clean_<user>_smoke.yaml --headless

命令成功返回并生成一个 episode 后，说明最小任务可以启动。该结果只验证启动链路，不代表正式数据采集、策略训练或评测已经完成。

步骤 3：采集专家示范数据

在数据采集容器中选择一种采集方式。单任务采集适合先验证数据产物；并行采集适合批量生成数据；后台采集适合长时间运行。

单任务采集

MUSA_VISIBLE_DEVICES=5 ROBOEVOLVE_BACKEND_SETUP=none \
USD_ASSETS_PATH=/workspace/RoboEvolve/assets_usd \
bash scripts/collect_data.sh adjust_bottle \
  --cfg config/collect/single_task_demo.yaml --headless

并行采集

bash scripts/collect_data.sh \
  --cfg config/collect/parallel_demo.yaml --headless

后台采集

mkdir -p .cache_<user>
nohup env ROBOEVOLVE_BACKEND_SETUP=none \
  python -m roboevolve.collect_data shake_bottle \
  --cfg config/mode/demo_clean.yaml --headless \
  > .cache_<user>/shake_bottle.log 2>&1 &
echo $! > .cache_<user>/shake_bottle.pid

采集完成后，在数据采集容器或共享数据目录中检查任务数据：

data/<task>/<mode>/
├── data/episode<N>.hdf5
├── instructions/episode<N>.json
├── video/episode<N>.mp4
├── seed.txt
└── scene_info.json

其中 episode<N>.hdf5 是训练数据的主要输入；语言指令、视频、随机种子和场景信息会在后续处理或评测中使用。

步骤 4：准备训练数据

在训练容器中处理步骤 3 生成的任务数据。先将 data/<task>/<mode>/ 通过共享存储挂载到训练容器，例如挂载到 /data/<collection-output>，再将处理结果写入训练容器可写的数据目录。

不同策略需要不同的数据格式：

目标策略	处理入口	输入和输出	必须产物
ACT	process_data.sh <task> <task_config> <expert_data_num>	HDF5 → HDF5 + Zarr。	norm_stats.json。
DP / DP3	使用 ACT 的处理入口；DP3 还需要点云数据。	HDF5 → Zarr。	norm_stats.json。
Pi_0	process_data_pi0.sh → generate.sh <hdf5> <repo_id>。	HDF5 → LeRobot。	norm_stats.json。
Pi_05	RLinf convert → LeRobot dataset。	HDF5 → LeRobot parquet。	norm_stats.json 和 tokenizer。
RDT_1B	使用策略自带处理入口。	HDF5 → RDT 内部格式。	T5/SigLIP 权重和 norm_stats。

归一化统计必须在训练前生成。处理入口为：

scripts/compute_norm_stats.py --config-name=<train_config_name>

该入口的工作目录、配置文件名、输入数据路径和输出路径需要与目标策略匹配。没有研发提供的完整示例时，不要直接复制上面的占位命令运行。

待研发补充

当前工程只列出了处理脚本名称和参数占位符，没有给出每个策略的完整命令、工作目录、配置文件、输入挂载路径、输出目录和预期结果。研发需要至少补充 ACT、DP/DP3 和 Pi_05 的可复制示例，并说明 norm_stats.json 和 tokenizer 的实际位置。

步骤 4 完成的判定条件是：训练容器能够读取转换后的数据集，目标策略所需的 norm_stats.json 已生成，Pi_05 还能够读取 tokenizer 和对应资产文件。

步骤 5：训练策略并获取 Checkpoint

在训练容器中使用步骤 4 生成的数据训练策略。训练配置中的数据路径必须指向处理后的数据集，而不是步骤 3 的原始 HDF5 目录。

以 Pi_05/RLinf SFT 配置为例，至少需要确认以下字段：

data:
  train_data_paths: "/data/<processed-dataset>"

runner:
  task_type: sft
  max_steps: 30000
  save_interval: 5000

训练前按以下顺序验证：

1. 使用一个样本检查图像、状态、指令和动作的 shape，以及归一化转换是否成功。
2. 在单卡上运行少量训练步，确认 loss、梯度和参数更新均为有限值。
3. 在目标多卡配置上运行短训练，确认 FSDP/MCCL、数据并行和显存配置正常。
4. 使用小规模数据过拟合，再启动正式训练。

不同策略的训练入口不同，可能使用 train.py、train_pytorch.py 或 RLinf SFT。当前工程没有给出与每个数据处理入口相匹配的完整启动命令，因此研发需要补充训练配置、启动命令、checkpoint 输出目录和单卡/多卡验证命令。

训练完成后，确认 checkpoint 至少包含模型权重和评测所需的资产。Pi_05 在 S5000 评测中使用 Torch checkpoint；如果训练输出是 JAX/Orbax 格式，请在训练容器中转换：

CHECKPOINT=/workspace/models/<checkpoint>
test -f "${CHECKPOINT}/model.safetensors"
test -f "${CHECKPOINT}/params/_METADATA"

TORCH_CHECKPOINT=${CHECKPOINT}_torch
python /workspace/XPolicyLab/policy/Pi_05/openpi/scripts/convert_pi05_orbax_to_pytorch.py \
  --checkpoint-dir "${CHECKPOINT}" \
  --output-dir "${TORCH_CHECKPOINT}" \
  --precision bfloat16

将最终的 Torch checkpoint 和对应 assets/<repo_id>/norm_stats.json 放到评测容器可以读取的共享目录。评测容器不能直接使用 JAX/Orbax checkpoint。

步骤 6：启动策略评测

在评测容器中进入评测项目目录，并设置步骤 5 生成的 Torch checkpoint：

cd /workspace/RoboTwin-lambdasim-eval

export PI05_MODEL_PATH=/workspace/models/<checkpoint>
export PI05_REPO_ID=$(find "${PI05_MODEL_PATH}/assets" -mindepth 2 -maxdepth 2 -name norm_stats.json -printf '%h\n' -quit | xargs -r basename)
export PI05_DEVICE=musa:0

test -f "${PI05_MODEL_PATH}/model.safetensors"
test -f "${PI05_MODEL_PATH}/assets/${PI05_REPO_ID}/norm_stats.json"

配置仿真评测

编辑 config/eval/simulation_eval.yaml：

mode: demo_gauss_lambdasim
episodes: 100
seed: 0
model: pi05
env_cfg_type: arx_x5
action_type: joint

重要参数如下：

参数	说明
mode	选择场景和仿真后端。demo_gauss_lambdasim 表示使用 3DGS 场景和 Lambda Sim，适合在 MUSA 容器中运行。
episodes	每个任务运行的回合数。值越大，成功率统计越稳定，但运行时间越长。
seed	随机种子。多台服务器或多次对比评测时，应保持协议一致；当前评测约定使用 0～99 的种子范围。
model	评测配置中使用的策略键。它必须与推理服务配置中的 models.pi05 对应。
env_cfg_type	机器人和环境配置类型。它必须与训练数据、checkpoint 和推理服务配置保持一致；示例使用 arx_x5。
action_type	策略动作表示方式。joint 表示使用关节动作。

配置推理服务

编辑 config/eval/inference_server.yaml：

gpu_ids: "0-7"
base_port: 19100
models:
  pi05:
    policy_name: Pi_05
    ckpt_name: <checkpoint>
    env_cfg_type: arx_x5
    replicas: 8

重要参数如下：

参数	说明
gpu_ids	推理 worker 使用的 GPU 范围。"0-7" 表示使用 8 张 GPU。
base_port	Policy Server 的基础端口。客户端连接地址和 SSH 端口转发必须使用同一端口。
models.pi05	名为 pi05 的策略配置块；它应与仿真评测配置中的 model: pi05 对应。
policy_name	策略加载器使用的策略名称。Pi_05 checkpoint 使用 Pi_05。
ckpt_name	要加载的 checkpoint 名称或目录。它必须与 PI05_MODEL_PATH 指向同一份模型。
env_cfg_type	推理服务使用的机器人和环境配置，必须与 simulation_eval.yaml 一致。
replicas	推理服务实例数量。示例配置启动 8 个 worker，通常与 gpu_ids 中的 GPU 数量对应。

启动评测进程

在评测容器的三个终端中分别启动推理服务、评测 worker 和 GPU 监控：

bash scripts/serve_policy.sh --config config/eval/inference_server.yaml

bash scripts/eval_policy.sh --config config/eval/simulation_eval.yaml --headless

watch -n 0.5 mthreads-gmi

停止服务时，先停止评测 worker，再停止推理服务，最后使用 mthreads-gmi 确认显存已释放。

验证结果

评测完成后，在评测容器中查看总成功率和单任务结果：

cat /workspace/RoboTwin-lambdasim-eval/eval_result/task_success_rates.txt

TASK=adjust_bottle
RESULT_FILE=$(find "/workspace/RoboTwin-lambdasim-eval/eval_result/${TASK}" -type f -name _result.txt -printf '%T@ %p\n' | sort -nr | head -1 | cut -d' ' -f2-)
cat "${RESULT_FILE}"

评测结果通常位于以下目录：

eval_result/<task>/<policy>/<mode>/<checkpoint>/<run-id>/
├── _result.txt
├── video/episode<ID>.mp4
└── 3DGS_views/

完整闭环的判定条件如下：

• 步骤 2 能够生成一个 smoke test episode。
• 步骤 3 能够生成可读取的专家示范数据。
• 步骤 4 能够生成目标策略所需的数据集、norm_stats.json 和 tokenizer（适用时）。
• 步骤 5 能够生成评测容器可加载的 Torch checkpoint。
• 步骤 6 能够生成 _result.txt、成功率和评测视频。

本地 Lambda Sim 源码可以验证 USD 场景导入、状态创建、动画回放和图像合成接口；RoboEvolve 数据转换、策略训练和评测必须在对应项目、容器和数据环境中执行。当前流程不把尚未提供完整示例的步骤 4 和步骤 5 写成已经验证的单条命令。

下一步

需要查看 Lambda Sim 模块、函数和参数时，请打开 API 参考。