RoboTwin 2.0：双臂数字孪生的数据工厂

What this is

RoboTwin 2.0 是一个面向双臂机器人操作的仿真数据生成与策略评测平台，核心目标是用可控的数字孪生环境生成大规模演示数据，并在统一条件下比较不同 VLA/机器人策略的泛化能力。项目服务于机器人模仿学习、视觉鲁棒性、多任务操作和跨本体评测研究；当前主分支对应 RoboTwin 2.0，配套 ICML 2026 论文、数据集、排行榜和官方 checkpoint。

Stack

• Language(s): Python 为主，Shell 用于安装、数据下载和评测入口
• Framework / runtime: SAPIEN 3.0 仿真引擎、Gymnasium 环境接口、PyTorch
• Robot planning: mplib / TOPPRA，用于双臂运动规划和时间参数化
• Policy/evaluation integration: XPolicyLab，提供 policy server、WebSocket/TCP client 和统一评测协议
• 数据与视觉： HDF5、OpenCV、Open3D、trimesh、RGB/深度/点云/关节状态/end-pose 数据格式

How it's organized

复制envs/
  _base_task.py       双臂任务基类、SAPIEN 场景、观测、动作和成功判定接口
  *.py                具体操作任务，例如 adjust_bottle、handover_block、stack_blocks_two
  robot/              机器人本体和运动控制
  camera/             头部及腕部相机
  utils/              actor、姿态、场景和数据处理工具

env_cfg/
  task_config/        demo_clean、demo_randomized 等任务配置
  eval/               多任务评测及远程 policy server 配置
  robot/              机器人动作维度和本体信息
  *.yml               aloha-agilex、ARX-X5、Franka 等环境 profile

scripts/
  collect_data.py     种子筛选、专家轨迹复用、演示数据采集
  eval_policy_xpolicylab.py
                      XPolicyLab 与 RoboTwin 的单任务/批量评测适配层
  eval_policy_multitask.py
                      多任务、多 GPU、远程 server 调度器
  eval_policy_server.py
                      policy server 池启动、健康检查和生命周期管理
  download_xpolicylab_data.sh
                      预采集数据下载

code_gen/
  task_generation.py  基于代码/LLM 的任务生成
  observation_agent.py
                      对生成任务进行观测和验证
  task_info.py        任务元信息和任务描述

description/
  gen_*               任务、物体和 episode 语言描述生成
  task_instruction/   seen/unseen 指令数据

XPolicyLab/
  Git submodule       策略适配器、policy server、数据格式和部署工具

How it fits together： 一个任务由 envs/<task_name>.py 定义，并继承 envs/_base_task.py。基类负责创建 SAPIEN 场景、加载双臂机器人和相机、执行规划动作、生成 RGB/关节状态/end-pose 等观测，并将 episode 保存为 HDF5/视频。评测时，eval_policy_xpolicylab.py 将 RoboTwin 观测转换成 XPolicyLab 格式，把策略输出转换回 RoboTwin 的 joint 或 end-pose action，最后由任务自身的 check_success() 判定成功或失败。

1. 任务集

RoboTwin 2.0 主分支的评测配置 env_cfg/eval/all_tasks.yml 显式列出了 50 个任务，覆盖以下几类双臂操作：

• 抓取、搬运和放置
• adjust_bottle
• pick_diverse_bottles
• pick_dual_bottles
• move_can_pot
• place_object_basket
• place_container_plate
• put_object_cabinet
• 双臂协作和交接
• handover_block
• handover_mic
• place_a2b_left
• place_a2b_right
• place_dual_shoes
• 堆叠、排序和组合操作
• stack_blocks_two
• stack_blocks_three
• stack_bowls_two
• stack_bowls_three
• blocks_ranking_rgb
• blocks_ranking_size
• 工具和交互操作
• beat_block_hammer
• press_stapler
• stamp_seal
• turn_switch
• click_bell
• click_alarmclock
• 开合、倾倒和摇晃
• open_laptop
• open_microwave
• dump_bin_bigbin
• shake_bottle
• shake_bottle_horizontally
• 物体和场景理解相关操作
• scan_object
• rotate_qrcode
• place_object_scale
• place_object_stand
• place_phone_stand

每个任务通常包含四个核心部分：

1. load_actors()：随机生成物体及其初始姿态；
2. play_once()：用专家规划器完成一次任务；
3. check_success()：根据物体最终位置、姿态、接触关系等判断是否完成；
4. info：记录物体 model id、使用的手臂、场景随机变量等，用于生成自然语言指令。

例如 envs/adjust_bottle.py 中，瓶子的方向和模型会随机变化，系统根据瓶子位置选择左手或右手，然后执行抓取、抬升和放置；成功条件是瓶子被放到指定侧且高度超过阈值。

数据方面，项目 README 声称提供超过 100,000 条预采集轨迹，可以从 RoboTwin 2.0 Dataset 下载。数据包括：

• 头部和腕部相机图像；
• 双臂 joint state；
• 双臂 end-pose；
• episode instruction；
• HDF5 trajectory；
• 可选评测视频。

2. 引擎 & 本体

仿真引擎

核心仿真运行在 SAPIEN 3.0 上，相关逻辑集中于 envs/_base_task.py：

• 创建 sapien.Engine 和 SapienRenderer；
• 默认仿真 timestep 为 1/250；
• 支持光栅化/光线追踪渲染配置；
• 创建桌面、墙面、地面和灯光；
• 通过物理材质控制摩擦系数、恢复系数等；
• 在场景初始化后检查物体是否稳定；
• 支持评测阶段的视频输出。

任务环境通过 Gymnasium 风格的 Base_Task 暴露观测和动作接口，但它不是典型的离散 RL benchmark，而是更偏向于：

复制任务初始化
  -> SAPIEN 场景和物体随机化
  -> 双臂规划或执行 policy action
  -> 采集视觉和机器人状态
  -> check_success() 判定 episode 结果

本体配置

项目使用配置文件将“任务配置”和“机器人本体配置”解耦：

• env_cfg/aloha_agilex.yml：默认的 Aloha/AgileX 双臂配置；
• env_cfg/arx_x5.yml：ARX-X5 配置；
• env_cfg/franka.yml：Franka 配置；
• env_cfg/robot/_robot_info.json：本体动作维度和布局；
• env_cfg/task_config/*.yml：任务随机化、相机、数据类型和 embodiment 选择。

默认 demo_clean.yml 使用：

• aloha-agilex；
• D435 头部相机和腕部相机；
• RGB、joint state、end-pose；
• 不启用背景、灯光和桌面杂物随机化。

demo_randomized.yml 则加入：

• 随机背景；
• 桌面杂物；
• 桌面高度变化；
• 随机灯光；
• unseen evaluation instruction。

因此，RoboTwin 的主要研究变量不是简单地更换任务，而是可以组合：

复制任务 × 物体模型/姿态 × 相机设置 × 背景/灯光 × 桌面杂物 × 语言指令 × 机器人本体

动作和规划

Base_Task 支持两种主要策略动作：

• joint/qpos action： 直接给出左右机械臂关节和夹爪动作；
• end-pose action： 给出左右末端 7D pose，再由 mplib 规划到关节轨迹。

专家数据采集阶段还会：

• 先用规划器寻找可行 seed；
• 检查 plan_success；
• 检查 check_success()；
• 检查轨迹是否超出合法关节范围；
• 只保存通过检查的轨迹。

collect_data.py 中的 planned_joints_legal() 检查尤其重要，它会过滤规划器生成的越界或未展开关节轨迹，避免把无效专家轨迹写入数据集。

3. 评估指标和分数基线

主要评估指标：成功率

项目的核心指标是 episode success rate：

复制success rate = 成功 episode 数 / 有效评测 episode 数

在 eval_policy_xpolicylab.py 中，单任务最终会写出类似：

复制Final success rate: suc_num/test_num

默认评测数量通常是 test_num=100，批量评测模式则允许通过 --test-num 指定目标 episode 数。

成功不是由模型自己声明，而是由环境中的任务逻辑决定。例如：

• 物体是否到达目标区域；
• 是否达到指定高度；
• 是否与目标物体接触；
• 是否完成堆叠；
• 是否在规定 step limit 内完成。

这使得评估不依赖人工打分，能够自动化批量运行。

有效 episode 和 seed 过滤

RoboTwin 2.0 并不是简单地固定运行连续的随机种子。评测时通常有一个 expert check 流程：

1. 用当前 seed 初始化场景；
2. 执行专家轨迹；
3. 检查场景是否稳定；
4. 检查专家规划是否成功；
5. 检查专家动作是否达到任务目标；
6. 通过后才把该 seed 作为有效测试 episode。

因此，代码中的 test_num=100 更准确地表示：

这能降低随机生成不稳定场景、专家轨迹不可行等因素对策略分数的干扰。

评估条件维度

项目 README 将实验重点概括为：

1. 单任务 fine-tuning 能力；
2. 视觉鲁棒性；
3. 语言多样性和语言条件鲁棒性；
4. 多任务能力；
5. 跨本体性能。

从配置和代码看，至少有以下可比较条件：

• demo_clean vs demo_randomized；
• seen instruction vs unseen instruction；
• 单任务 vs 50 任务多任务；
• joint/qpos action vs end-pose action；
• 本地 policy server vs 远程 policy server；
• Aloha/AgileX、ARX-X5、Franka 等不同本体配置；
• 不同 checkpoint；
• 不同任务和随机 seed。

分数基线

仓库代码本身没有把完整 leaderboard 数值硬编码进主分支；README 将官方结果指向：

• RoboTwin 2.0 Leaderboard
• Official Benchmark Checkpoints

因此，基线应理解为：

• 不同策略/模型在统一任务集上的 success rate；
• 不同 checkpoint 在 clean/randomized 条件下的 success rate；
• 单任务、多任务和跨 embodiment 的对比结果。

从仓库当前能确认的是指标定义、任务集、评测流程和官方 checkpoint 入口；如果需要精确列出 ACT、DP3 或其他方法的 leaderboard 分数，应以排行榜页面当前内容为准，而不能仅根据仓库代码推断具体数值。

4. 支持 harness 做了什么优化

这里的 “harness” 更准确地说是 RoboTwin 2.0 新增的 XPolicyLab-based evaluation harness，入口主要是：

• scripts/eval_policy_xpolicylab.py
• scripts/eval_policy_multitask.py
• scripts/eval_policy_server.py
• scripts/eval_policy.sh

它不是只增加了一个启动脚本，而是把“策略服务、仿真环境、数据格式、并发调度和结果记录”统一起来。

观测和动作协议统一

eval_policy_xpolicylab.py 完成 RoboTwin 与 XPolicyLab 之间的双向适配：

• RoboTwin 相机名称映射到 XPolicyLab：
• head_camera -> cam_head
• left_camera -> cam_left_wrist
• right_camera -> cam_right_wrist
• 统一 vision 数据结构；
• 统一 joint state、gripper、end-pose 和 TCP pose；
• 支持策略返回数组、字典、action chunk 等多种形式；
• 兼容 joint/qpos 和 EE/end-pose 两种动作；
• 缺少部分 action 时可回退到当前状态；
• 检查 action 维度和字段合法性。

这样，新策略只需要实现 XPolicyLab policy adapter，不需要为每个 benchmark 单独重写 RoboTwin 环境调用逻辑。

从单任务评测扩展到多任务、多 GPU 调度

eval_policy_multitask.py 把 50 个任务转换为一组 EvalJob，并提供：

• GPU 列表和 GPU range，例如 0-7；
• 每张 GPU 的并发任务数；
• 多任务调度；
• dry-run 配置检查；
• fail-fast；
• 每个任务独立日志；
• Rich 进度条；
• 任务级 success rate；
• 最终 summary.json。

默认配置 env_cfg/eval/all_tasks.yml 可以一次性调度完整任务集，而不需要手动逐个运行任务。

支持远程 policy server 和本地 simulator 分离

新增的部署形态是：

复制机器 A：启动一个或多个 XPolicyLab policy server
机器 B：启动 RoboTwin SAPIEN simulator client

eval_policy_server.py 做了以下工程化处理：

• 按 GPU 和端口启动多个 policy server；
• 自动分配端口；
• 检查端口是否已被占用；
• 通过 WebSocket handshake 做健康检查；
• 等待所有 server ready 后再开始评测；
• 为每个 server 保存独立日志；
• Ctrl-C 或异常时统一终止进程组；
• 支持 --dry-run 打印部署计划。

这解决了策略模型和仿真环境必须处于同一台机器、同一个 Conda 环境的问题。

本地/远程模式统一

多任务调度器通过同一个入口支持：

• Local mode： 本地启动 policy evaluation script 和 simulator；
• Remote mode： simulator 连接预先启动的远程 policy server；
• 单个 server；
• 多个 server pool；
• 多 IP、多端口配置。

同时会验证：

• task 文件是否存在；
• policy adapter 是否存在；
• task config 是否存在；
• seen/unseen instruction 配置是否合法；
• RoboTwin 和 XPolicyLab 的 robot action layout 是否一致；
• arm_dim 和 ee_dim 是否匹配。

这类启动前检查可以避免评测跑到一半才发现动作维度、环境配置或 policy script 不兼容。

批量评测优化

eval_policy_xpolicylab.py 增加了 batch evaluation：

• 使用 multiprocessing 的 spawn 模式；
• 每个 worker 持有一个仿真环境和一个 policy client；
• 多 worker 并行获取 seed；
• 通过共享 episode counter 保证只生成目标数量的有效 episode；
• 自动跳过 unstable seed、expert failed seed 和环境初始化失败 seed；
• 支持 max_seed_attempts；
• policy server 支持 action chunk；
• 每个 episode 通过 prepare_case、reset、trial_end 管理策略状态。

这比简单地串行执行 100 个 episode 更适合大规模 benchmark，尤其是策略推理和仿真可以同时并发时。

结果与可复现性优化

每次运行会按以下维度保存结果：

复制eval_result/
  <task>/
    <policy>/
      <task_config>/
        <checkpoint>/
          <timestamp>/
            _result.txt
            episode videos

多任务模式还会额外生成：

复制eval_result/multitask/<run_id>/
  logs/
  jobs/
  summary.json

这使得结果可以和以下信息绑定：

• task；
• seed；
• checkpoint；
• policy name；
• task config；
• embodiment；
• instruction type；
• GPU；
• remote policy server；
• episode 日志和视频。

How to run it

最短路径是先递归克隆，因为 XPolicyLab 是 Git submodule：

复制git clone --recurse-submodules https://github.com/RoboTwin-Platform/RoboTwin.git
cd RoboTwin
bash scripts/_install.sh

依赖中比较关键的版本包括：

复制torch==2.4.1
numpy==1.26.4
sapien==3.0.0b1
mplib==0.2.1
gymnasium==0.29.1

下载预采集数据：

复制bash scripts/download_xpolicylab_data.sh

采集单个任务数据：

复制bash collect_data.sh beat_block_hammer demo_randomized 0

多任务评测前先做 dry-run：

复制bash scripts/eval_policy.sh multitask \
  --config env_cfg/eval/all_tasks.yml \
  --policy-name <policy_name> \
  --ckpt-name <checkpoint> \
  --env-cfg-type arx_x5 \
  --policy-conda-env <policy_env> \
  --eval-env-conda-env <robotwin_env> \
  --action-type joint \
  --dry-run

本地多任务评测：

复制bash scripts/eval_policy.sh multitask \
  --config env_cfg/eval/all_tasks.yml \
  --policy-name <policy_name> \
  --ckpt-name <checkpoint> \
  --env-cfg-type arx_x5 \
  --policy-conda-env <policy_env> \
  --eval-env-conda-env <robotwin_env> \
  --action-type joint

远程模式则先启动 policy server，再让本地模拟器连接：

复制bash scripts/eval_policy.sh serve \
  --config env_cfg/eval/remote_server.yml

复制bash scripts/eval_policy.sh multitask \
  --config env_cfg/eval/all_tasks.yml \
  --policy-name <policy_name> \
  --env-cfg-type arx_x5 \
  --eval-env-conda-env <robotwin_env> \
  --enable-remote \
  --policy-server-ip <server_ip> \
  --policy-server-port <port>

Try asking

• RoboTwin 的 demo_clean 和 demo_randomized 在评测协议上具体有哪些差异？
• RoboTwin 的 check_success() 如何为不同任务定义成功，能否整理成任务类型和判定条件表？
• XPolicyLab 的 policy adapter 需要实现哪些接口，如何接入一个新的 VLA 模型？

---