❗

电脑硬件配置及开发环境要求：

训练最低配置：

Python 3.11+（推荐使用 uv 包管理器）
GPU: 训练需要 NVIDIA GPU（推荐 A100/H100）
内存: 32GB+ 系统 RAM
存储: 100GB+ 可用磁盘空间 NVMe SSD 固态硬盘
操作系统：ubuntu22.04LTS及以上版本
网络: 能正常访问Github

部署最低配置：

Python 3.11+（推荐使用 uv 包管理器）
GPU：NVIDIA GPU至少 6GB 显存。推荐 GeForce RTX 3090 (12 GB) 或更高
CPU：至少六核处理器，推荐Intel: Core i7-10700K/AMD:Ryzen55600X/或更高版本
内存：16GB以上
存储空间：至少 30GB 可用空间
操作系统：Ubuntu 20.04 LTS及以上版本
网络环境：能正常访问Github

物料采购链接：

糖果：一盒【大白兔500克钱兔似锦礼盒】
奶油色果盘：使用“轻奢水果盘2个装【奶油白+透明】”的奶油色果盘

1. 任务概述

本次开源了基于 Pi05 实现的糖果递送任务完整方案，其中开源了数据集、模型权重以及训练与推理源码。该任务通过识别人手「手心向上」的姿态触发糖果递送行为，旨在验证TRON2在目标感知和末端跟随场景下的基础抓取（pick）、放置（place）原子操作能力。开发者可参考本项目的标准化开发流程、将整套技术方案迁移至各类抓取放置机器人任务中，依托配套的数据采集平台和具身平台，独立完成自定义任务的全流程开发，快速搭建适配自身业务需求的具身智能机器人应用场景任务。

如下图所示，双臂操作项目的开发过程中的 4 个主要环节：数据采集 - 数据处理 - 模型训练 - 模型部署。

Pi0.5 是由 Physical Intelligence 开发的视觉-语言-动作（VLA）模型。如果你正打算使用具身数据平台导出的数据来微调这些模型，本指南将带你走通基于官方 OpenPI 框架的完整流程。并介绍如何使用预训练的 Pi0.5 模型在自定义数据集上进行高效微调。

2. 账号及任务创建

1.账号：用户可选择以下两种工作模式开展数据集采集及处理流程：

单人模式：由项目管理员账号独立完成数据采集、标注、审核全流程工作；
多人协作模式：由项目管理员创建数据采集员、标注员、审核员三类账号，各角色登录对应账号分工完成各环节任务，具体的创建账号流程如下图所示：

2.自定义任务：您可以在项目界面中新建任务，将后续采集的数据分类归入不同项目，便于导出、训练时快速定位查找。

其他详细内容请参考：逐际动力数据采集软件使用手册

创建角色	创建项目
多用户协作创建账号	创建任务

3. 数据采集

3.1 环境布置

在糖果递送任务中，为更好地复用逐际动力已采集并公开的数据集，建议尽量复刻官方数据采集环境，具体布置要求如下：

机器状态：手柄🎮调整至遥操作模式(TeleOperator)；
桌子规格：尺寸160 * 80 * 75cm（长*宽*高），桌面为纯白色；（高度尽量保持不变）
机器人放置：固定支架前，机器边缘距离桌面边缘10-15cm；
道具摆放：糖果密集放置在桌面靠近机器人一侧的中央区域，同时底部放置米色果盘，确保机器人双臂均可抓取到糖果；【已附采购链接】

3.2 连接TRON2机器人

参照[逐际动力数据采集软件使用手册]产品概述-网络连接方法，进行网络连接；

3.3 访问数据采集平台

参照[逐际动力数据采集软件使用手册]产品概述-软件访问入口，进入数据采集软件并按身份登录；

3.4 检查相机配置

candy_server.yaml中已经标注了client: observation_source: bridge ，其中bridge表示为自动获取相机SN，legacy需要手动输入sn。

💡

原有相机损坏维修，或者想使用自己的相机，请参考相机SN配置方法

3.5 TRON2机器人配置

机器人状态：将手柄切入遥操作（TeleOperator)模式后，机器人头部将自动调整至最低姿态，并旋转至中位（pitch = 1.04，yaw = 0）。连接机器人后，在数据采集软件概览页面https://10.192.1.4/检查视角是否合适。
参照下面「TRON 2 用户手册」链接中「VR设备及遥操作使用说明」章节的「遥操作准备」与「遥操作使用」部分，完成机器人遥操作准备状态。

3.6 数据采集设置

⚠️

在正式开始采集前，还需要检查以下事项：

网络连接是否畅通
数据盘可用空间是否足够（录制1条1分钟的数据占用空间大约为800M-1.5G）

参照[逐际动力数据采集软件使用手册]概述页面-数据录制，在数据采集软件进行参数设置

参数	参数填充
文件名	自拟
Dominid	一般填0，多机共用机器人进行操作时可按需分配id号
格式	mcap
topic	推荐勾选以下13个topic 1、/camera/left/color/image_resized/compressed sensor_msgs/msg/CompressedImage 2、/camera/right/color/image_resized/compressed sensor_msgs/msg/CompressedImage 3、/camera/top/color/image_raw/compressed sensor_msgs/msg/CompressedImage 4、/gripper_command sensor_msgs/msg/JointState 5、/gripper_state sensor_msgs/msg/JointState 6、/joint_command sensor_msgs/msg/JointState 7、/joint_states sensor_msgs/msg/JointState 8、/left_arm/ee_pose geometry_msgs/msg/PoseStamped 9、/left_arm/ee_pose_cmd geometry_msgs/msg/PoseStamped 10、/right_arm/ee_pose geometry_msgs/msg/PoseStamped 11、/right_arm/ee_pose_cmd geometry_msgs/msg/PoseStamped 12、/lifter/state 13、/chassis/twist

数据采集录制操作：

1.调整机器人双臂至准备姿态：同时长按 VR 左右手柄X+A键；

2.开始录制：按下 VR 右手柄 B键（或在数据采集软件「概览」→「数据录制」中点击绿色开始图标）

3.执行采集任务：通过遥操作抓取桌面上的糖果并递至人手中。采集遵守以下原则：

系统识别到「手心向上」姿态后，双臂才开始移动夹取糖果并递送；未识别到手心向上时，机械臂保持静止。

4.复位：同时按下 VR 左右手柄握把按键，机器人双臂回到准备姿态；

5.结束录制：按下 VR 左手柄Y键（或在数据采集软件「概览」-「数据录制」中点击结束图标）

6.循环录制更多条；

递糖果demo数采过程图示

3.7 数据上传至云端

数据采集完成后；点击数据采集平台「自动上传界面」->「配置并安装」->「自定义选择所属项目」+「云存储选择export（cn-shanghai）选项」->「启动」；

1、自动上传界面

2、配置-启动

3、自动上传中

系统会自动将今日采集且并未上传过的数据上传至云端；

4、上传结束

等待片刻上传结束后，可在具身平台账号的数据界面查看到该数据。

5、在具身平台数据界面查验

4. 数据处理

4.1 数据标注

1. 在具身平台的数据界面，勾选需要进行数据标注的数据，点击「标注」（可通过高级搜索按项目筛选数据）	1、选择待标注数据
2.选择标注方式：创建新任务 / 追加旧任务 / 快速标注（不创建任务），并填写相关信息；对于递糖果的标注内容可参考：英文：Hand out the candy 中文：递糖果	2、选择任务

3.开始标注：可逐条点击标注，也可选择批量标注一次性处理全部所选数据；

逐条标注

批量标注

4.2 数据导出

1. 点击左侧导航栏「导出」，选择所需的数据格式；	1、选择导出格式
2. 若选择Pi05作为Baseline，建议将数据导出为LeRobot格式，便于直接对数据集进行训练；	2、选择数据

💡

此外我们也额外开源了数据转换脚本limx_mcap2lerobot.zip 可在用户自有的高性能服务器上运行，提供更高的灵活性和计算能力，适合有一定定制化需求的场景

4.3 数据集验证

~/Desktop/lerobot_dataset$ tree -d      
.
├── data
│   └── chunk-000
├── meta
│   └── episodes
│       └── chunk-000
└── videos
    ├── observation.images.cam_high
    │   └── chunk-000
    ├── observation.images.cam_left_wrist
    │   └── chunk-000
    └── observation.images.cam_right_wrist
        └── chunk-000

5. 数据集说明

数据集统计：

指标	数值
数据描述	1953条；
数据地址	具身平台对应：递糖果数据集_Label
任务类型	糖果递送（Pick \& Place）
采集方式	遥操作（VR Teleoperation）
数据格式	当前为Mcap；可导出为任意格式

6. 模型训练

训练模型目前有两种方式，您可以根据情况自由选择：

训练方式	适用情况	优势
基于具身数据平台训练	暂无算力资源，或已有算力但希望快速跑通开发流程的初学者	- 无代码训练: 通过可视化界面完成全训练流程，无需编程经验 - 实时监控: 提供训练指标、模型输出、系统日志的实时监控 - 自动化管理: 支持检查点管理、断点续训、参数调整等功能 - 自定义镜像：提供完整镜像，可直接复现官方开发流程
基于自有算力训练	已有算力（本地服务器或云资源）且熟悉云端开发的资深开发者	- 复用已有算力资源 - 已开源训练与推理源码，开放性更强，可自行迭代优化（不可商用）

6.1 基于具身平台训练

具身数据平台提供完整的模型训练功能，当前支持 OpenPI、ACT、自定义镜像这几种机器人学习模型的训练，具体的训练方式如下述：

6.1.1 选择基座模型训练

具体使用流程请查阅逐际动力具身数据平台使用手册 模型功能模块 - 训练工作流程。

6.1.2 选择自定义镜像训练

当用户需要借助具身平台的算力、基于我们的开源代码进行模型训练时，需通过自定义镜像的方式实现。具体填写内容如下：

序号	参数名称	填写内容
1	训练镜像	`limx-acr-wlcb-registry.cn-wulanchabu.cr.aliyuncs.com/limx_emb/hum:pytorch210-gpu-py312-cu128-ubuntu22-tron2-openpi-3`
2	仓库用户名	不需要填写
3	仓库密码	不需要填写
4	EntryPoint	`bash /root/tron2_openpi/scripts/cloud_train_entrypoint_portable.sh`
5	启动参数	以下内容作为命令行参数传递给上述启动脚本，您可根据需要灵活调整steps、batch_size等参数： `--data-dir /data --repo-id input --weight /models/openpi-assets/checkpoints/pi_base/params --output-dir /data/output --exp test --steps 30000 --save-interval 10000 --batch-size 64 --rtc-delay 10 --action-horizon 30 --prompt-from-task --overwrite`

6.2 基于自有算力训练

⚠️

注意：

使用自有算力训练模型前，请先参考本文开头「训练最低配置」部分。

💡

关于训练框架

OpenPI 开源项目中的底层技术栈包含 JAX 和 PyTorch 两种框架，由于训练其核心模型 Pi05。由于 OpenPI 原生训练框架为JAX，且核心模型、训练流程及基础 Checkpoint 均基于 JAX/Flax 构建，因此本项目默认使用 Jax 框架进行训练。
JAX 是一种用于模型训练的计算工具，定位类似 PyTorch — 它不是模型，也不是算法，只是“用来跑模型的框架”。
JAX 的优势在于计算效率高，尤其适合大模型训练场景。本项目选用 JAX 正是因为其在 Pi0.5 这类大模型训练中更为高效。

如需在自有算力环境中，使用开源数据集或自定义数据集训练模型，可参考下文流程并结合开源代码实现。当前开源代码已完成 OpenPI 源码与 TRON2 的适配，本文以 Pi05 为例进行说明：

6.2.1 配置训练环境【同推理】

git clone https://github.com/limx-tron2/tron2_openpi.git
git clone https://github.com/limx-tron2/tron2_env.git

cd tron2_openpi

sudo apt install pkg-config
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ubuntuhandbook1/ffmpeg7 -y
sudo apt install ffmpeg libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev -y

uv sync
uv pip install -e .

source .venv/bin/activate 
uv pip install -e "../tron2_env[bridge,openpi]" # 激活当前环境 

# 验证是否正常安装成功，应输出路径：../tron2_env/src/tron2_env/__init__.py
PYTHONPATH="$(cd ../tron2_env/src && pwd)" uv run python -c "import tron2_env; print(tron2_env.__file__)"

6.2.2 训练流程

1.训练统一推荐独立 YAML 任务配置文件管理参数，不建议直接修改 src/openpi/training/config.py，便于配置隔离、版本管理与复用：

cp configs/train/tron2_tasks/example.yaml configs/train/tron2_tasks/my_task.yaml

2.打开配置文件： configs/train/tron2_tasks/my_task.yaml，修改数据集地址参数：repo_id: my_dataset；系统通过环境变量 HF_LEROBOT_HOME 拼接完整数据集路径，本地目录必须满足固定结构：

1.`$HF_LEROBOT_HOME/my_dataset/data/`：存放图像、轨迹、动作等原始数据

2.`$HF_LEROBOT_HOME/my_dataset/meta/`：存放数据集统计、任务描述、episode信息

export HF_LEROBOT_HOME=/path/to/datasets

3.数据集归一化参数是训练收敛的必要前置条件，首次训练前运行脚本 normalization statistics 计算统计文件：

uv run scripts/compute_norm_stats.py \
  --task-config configs/train/tron2_tasks/my_task.yaml

4.统计量计算完成后，执行训练脚本启动训练：

uv run scripts/train_tron2_task.py \
  --task-config configs/train/tron2_tasks/my_task.yaml

❗

补充：

我们提供了一体化入口脚本 `scripts/cloud_train_entrypoint_portable.sh`，无需分步执行：

不传 `--skip-norm` 参数时，脚本会自动先计算归一化统计量，再启动训练；
如需跳过统计量计算，增加入参 `--skip-norm`。

6.2.2.1 本地自定义路径模式：

自有算力无统一挂载目录时，手动传入数据集、权重、输出完整路径：

scripts/cloud_train_entrypoint_portable.sh \
  --data-dir /path/to/datasets \
  --repo-id my_dataset \
  --weight /path/to/checkpoint/params \
  --output-dir /path/to/output \
  --exp my_task \
  --prompt "perform the configured task" \
  --max-frames 100000

6.2.2.2 绑定自定义 YAML 配置文件模式：

直接加载已编辑完成的my_task.yaml，文件内统一管理repo_id、加载权重weight_loader、资源根目录assets_base_dir和保存路径checkpoint_base_dir等参数；仅需通过--data-dir 指定 HF_LEROBOT_HOME：

scripts/cloud_train_entrypoint_portable.sh \
  --task-config configs/train/tron2_tasks/my_task.yaml \
  --exp my_task \
  --data-dir "$HF_LEROBOT_HOME" \
  --max-frames 100000

❗

补充规范说明：

自定义任务配置文件（如`my_task.yaml`）已配置在`.gitignore` 中，不会提交至代码仓库；仓库仅保留通用模型`configs/train/tron2_tasks/example.yaml`；
模版 YAML 支持配置项：数据集`repo_id`、任务文本`prompt`、数据列定义、动作预测时长`action_horizon`、状态维度`state_dim`、预训练基准权重`base checkpoint`、训练输出路径，以及可选的 `prompt_from_task` 和 `rtc_training_simulated_delay`。

7. 模型部署

7.1 推理部署流程

⚠️

机器人初始姿态要求：需保证机器人处于 L1+X 标准初始状态：双臂自然竖直贴靠机身两侧。启动客户端后，机器人会自动侧展双臂，然后前伸，若非初始状态可能会直接抬起双臂，警惕前方物体风险。
在推理前必须将机器人🎮状态切换为高级开发者模式（High-Level Dev）。
- 如果采集数据时没有改变桌子高度、支架距离桌子边缘距离、光照环境、头部角度，那么推理时需要保持一致。
其他环境相关约束可参考本文开头「部署最低配置」部分内容。
关于相机连接模式说明：
1. Bridge 模式：通过 TRON2 Bridge 拉取图像数据，同步采用 Bridge 校正后的机器人状态信息；
2. Legacy 本地直连模式：本地推理主机直连 RealSense 相机，并从机器人 WebSocket 获取状态【此时需要将机器人的三个相机的usb口接到推理机箱上】；
当 `client.max_steps` 为 `null` 时，需要手动停止客户端。

7.1.1 配置推理环境【同训练】

💡

说明：标题「同训练」指安装命令与【6.2.1 配置训练环境】完全一样。如果用的是同一台电脑，环境在训练时已装好，此处无需重复安装，可直接跳到 7.1.2。

git clone https://github.com/limx-tron2/tron2_openpi.git
git clone https://github.com/limx-tron2/tron2_env.git

cd tron2_openpi

sudo apt install pkg-config
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ubuntuhandbook1/ffmpeg7 -y
sudo apt install ffmpeg libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev -y

uv sync
uv pip install -e .

source .venv/bin/activate 
uv pip install -e "../tron2_env[bridge,openpi]" 

# 验证是否正常安装成功，应输出路径：../tron2_env/src/tron2_env/__init__.py
PYTHONPATH="$(cd ../tron2_env/src && pwd)" uv run python -c "import tron2_env; print(tron2_env.__file__)"

7.1.2 权重拉取

在地址/home/xxx/xxx/tron2_openpi中新建文件夹checkpoints，在该文件夹中拉取权重：https://huggingface.co/limxdynamics/tron2-openpi-models/tree/main

cd /home/xxx/xxx/tron2_openpi
mkdir checkpoints
cd checkpoints
hf download limxdynamics/tron2-openpi-models \
  --repo-type model \
  --include "pi05_tron2_candy/**" \
  --local-dir ./checkpoints

7.1.3 部署配置

1.文件/home/linux_user_name/xxx/tron2_openpi/configs/deploy下的三个yaml文件是我们的示例配置，其中candy_server.yaml和candy_client.yaml为关于 Candy 任务的公开示例配置，其中包含各类参数，你可以根据注释自行修改。

2.用于你自己的机器人前，请**重点确认**** **checkpoint 路径、机器人地址、Bridge 地址、初始化姿态和安全流程都适用于当前部署。

3.常见的修改参数【最小本地配置示例如下所示，地址在tron2_openpi/configs/deploy/下的任意您使用的candy_server.yaml文件的policy内容（详细配置说明已写在yaml注释中）】：

policy:
  config: TASK_CONFIG_NAME # 训练配置名称，具体位置和/home/xxx/xxx/tron2_openpi/src/openpi/training/config.py中第642-653行内容一致；
  repo_id: DATASET_REPO_ID # 需要与checkpoint文件的asset子目录一致，我们的开源权重默认为input；
  checkpoint_dir: /path/to/checkpoints/TASK_CONFIG_NAME/experiment/step # checkpoint地址，可以为绝对路径或相对于 tron2_openpi 的相对路径
  default_prompt: TASK_PROMPT # 递糖果demo默认Hand out the candy
robot:
  ip: ROBOT_IP
client:
  observation_source: bridge 
  max_steps: null

7.1.4 机器人环境

1.需要确保机器人处于 L1+X 后的初始状态，即双臂竖直摆放在侧身状态；

2.切换手柄遥控器到高级开发者模式【High-Level-Develop】；

7.1.5 启动策略服务

1.在一个终端启动policy server:

```Bash
cd tron2_openpi
uv run scripts/serve_policy.py   --profile configs/deploy/candy_server.yaml
```

2.在另一个终端启动TRON2 客户端：

```Bash
cd tron2_openpi
uv run examples/tron2/pi_client_rtc.py   --profile configs/deploy/candy_client.yaml
```

3.运行客户端后机械臂会从竖直侧身状态平滑过渡到小臂垂直侧身的，随后即可以将手心向上放置在相机视角推理验证。

8. 参考资料

代码仓库：tron2_openpi
使用说明：README_CN.md
安装指南：INSTALL_CN.md

本文第 6、7 章的安装、训练、部署命令均整理自以上仓库，遇到本文未覆盖的细节可前往仓库文档查阅。

【递糖果】TRON2 双臂操作项目快速上手（基于pi05模型）