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

训练最低配置：

部署最低配置：

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

物料采购链接：

# 1. 任务概述 本次开源了基于 Pi05 实现的**叠衣服任务**完整方案，其中开源了数据集、模型权重以及训练与推理源码。该任务通过识别衣物的形态与摆放姿态触发折叠整理行为，旨在验证TRON2在柔性物体感知和精细操作场景下的基础抓取（pick）、折叠（fold）、放置（place）原子操作能力。开发者可参考本项目的标准化开发流程、将整套技术方案迁移至各类衣物操作与家政服务机器人任务中，依托配套的数据采集平台和具身平台，独立完成自定义任务的全流程开发，快速搭建适配自身业务需求的具身智能机器人应用场景任务。 如下图所示，双臂操作项目的开发过程中的 4 个主要环节：数据采集 - 数据处理 - 模型训练 - 模型部署。 Pi0.5 是由 Physical Intelligence 开发的视觉-语言-动作（VLA）模型。如果你正打算使用具身数据平台导出的数据来微调这些模型，本指南将带你走通基于官方 [OpenPI](https://github.com/Physical-Intelligence/openpi) 框架的完整流程。并介绍如何使用预训练的 Pi0.5 模型在自定义数据集上进行高效微调。 # 2. 账号及任务创建 1.账号：用户可选择以下两种工作模式开展数据集采集及处理流程： - **单人模式**：由项目管理员账号独立完成数据采集、标注、审核全流程工作； - **多人协作模式**：由项目管理员创建数据采集员、标注员、审核员三类账号，各角色登录对应账号分工完成各环节任务，具体的创建账号流程如下图所示： 2.自定义任务：您可以在项目界面中新建任务，将后续采集的数据分类归入不同项目，便于导出、训练时快速定位查找。 其他详细内容请参考：[逐际动力 具身数据平台使用手册](https://www.limxdynamics.com/zh/documents/890679841240780800)
创建角色
创建项目
多用户协作创建账号
创建任务
# 3. 数据采集 ## 3.1 环境布置 在叠衣服任务中，为更好地复用逐际动力已采集并公开的数据集，建议尽量复刻官方数据采集环境，具体布置要求如下：
  • 机器状态：手柄🎮调整至遥操作模式(TeleOperator)；
  • 桌子规格：尺寸160 * 80 * 75cm（长*宽*高），建议桌面为纯白色或深灰色；（我们开源的数据集包含在纯白色和纯深灰色桌面的采集数据；高度尽量保持不变）
  • 机器人放置：固定支架前，机器边缘距离桌面边缘15cm；
  • 道具摆放：需要将T恤（我们采集的深蓝色T恤较多）平整 / 杂乱放置在桌面靠近机器人一侧的中央区域，确保机器人双臂均可抓取到衣服；【已附采购链接】
## 3.2 连接TRON2机器人 参照[[逐际动力 数据采集软件使用手册](https://www.limxdynamics.com/zh/documents/889906272130961408#1.2-网络连接方法)]产品概述-网络连接方法，进行网络连接； ## 3.3 访问数据采集平台 参照[[逐际动力 数据采集软件使用手册](https://www.limxdynamics.com/zh/documents/889906272130961408#1.3-软件访问入口)]产品概述-软件访问入口，进入**数据采集软件**并按身份登录； ## 3.4 检查相机配置 `cloth_server.yaml`中已经标注了`client: observation_source: bridge `，其中bridge表示为自动获取相机SN，legacy需要手动输入sn。 ## 3.5 TRON2机器人配置
  • 机器人状态：将手柄切入遥操作（TeleOperator)模式后，机器人头部将自动调整至最低姿态，并旋转至中位（pitch = 1.04，yaw = 0）。连接机器人后，在数据采集软件概览页面https://10.192.1.4/检查视角是否合适。
  • 参照下面「TRON 2 用户手册」链接中「VR设备及遥操作使用说明」章节的「遥操作准备」与「遥操作使用」部分，完成机器人遥操作准备状态。
## 3.6 数据采集设置
⚠️
在正式开始采集前，还需要检查以下事项：
参照[[逐际动力 数据采集软件使用手册](https://www.limxdynamics.com/zh/documents/889906272130961408#2.2-数据录制（配置-%2B-开始停止）)]概述页面-数据录制，在**数据采集软件**进行参数设置
参数 参数填充
文件名 自拟
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.调整机器人双臂至准备姿态：使用🎮 L1 + X 将双臂调整至竖直准备姿态，随后同时长按 VR 左右手柄 X + A 键至双臂遥操回正姿态；

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

3.执行采集任务：通过遥操作叠桌面衣服。我们开源的数据集采集遵守以下原则：
叠衣服demo数采过程图示
- 相机识别到桌面衣服后，移动双臂使末端夹抓分别夹取T恤的肩膀和对应一侧的下摆，甩臂直至摊平衣服，使衣服领口对机器人的左向或右向（不要正对或背对机器人），随后末端夹抓分别夹取T恤的肩膀和对应一侧的下摆开始叠起，先从下向上折叠1/3衣服后，将衣服下拉，再从上向下折叠剩下的1/3衣服，最后将叠起的衣服沿1/2处从右向左折叠。 4.**复位**：同时长按 VR 左右手柄 **X + A** 按键，机器人双臂回到准备姿态； 5.**结束录制**：按下 VR 左手柄 **Y** 键（或在数据采集软件「概览」-「数据录制」中点击结束图标） 6.循环录制更多条； ## 3.7 数据上传至云端 - 数据采集完成后；点击数据采集平台「自动上传界面」->「配置并安装」->「自定义选择所属项目」+「云存储选择export（cn-shanghai）选项」->「启动」；
1、自动上传界面
2、配置-启动
3、自动上传中
- 系统会自动将今日采集且并未上传过的数据上传至云端；
4、上传结束
- 等待片刻上传结束后，可在具身平台账号的数据界面查看到该数据。
5、在具身平台数据界面查验
# 4. 数据处理 ## 4.1 数据标注
1. 在具身平台的数据界面，勾选需要进行数据标注的数据，点击「标注」（可通过高级搜索按项目筛选数据）
1、选择待标注数据
2.选择标注方式：创建新任务 / 追加旧任务 / 快速标注（不创建任务），并填写相关信息；
  • 对于叠衣服的标注内容可参考：
    • 英文：Fold clothes
    • 中文：叠衣服
2、选择任务
3.开始标注：可逐条点击标注，也可选择批量标注一次性处理全部所选数据；
逐条标注
批量标注
## 4.2 数据导出
1. 点击左侧导航栏「导出」，选择所需的数据格式；
1、选择导出格式
2. 若选择Pi05作为Baseline，建议将数据导出为LeRobot格式，便于直接对数据集进行训练；
2、选择数据
💡
此外我们也额外开源了数据转换脚本limx_mcap2lerobot.zip 可在用户自有的高性能服务器上运行，提供更高的灵活性和计算能力，适合有一定定制化需求的场景
## 4.3 数据集验证 ```Bash ~/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. 数据集说明 - 数据集统计：
指标 数值
数据描述 1820条；
数据地址 具身平台对应：开源-叠衣服数据集_Label
任务类型 叠衣服
采集方式 遥操作（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 20000
  --save-interval 5000
  --batch-size 64
  --rtc-delay 10
  --action-horizon 30
  --prompt-from-task
  --overwrite
## 6.2 基于自有算力训练
⚠️
注意：
使用自有算力训练模型前，请先参考本文开头「训练最低配置」部分。

💡
关于训练框架
如需在自有算力环境中，使用开源数据集或自定义数据集训练模型，可参考下文流程并结合开源代码实现。当前开源代码已完成 OpenPI 源码与 TRON2 的适配，本文以 Pi05 为例进行说明： ### 6.2.1 配置训练环境【同推理】 ```Bash 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`，便于配置隔离、版本管理与复用： ```Bash 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信息 ```Bash export HF_LEROBOT_HOME=/path/to/datasets ``` 3.数据集归一化参数是训练收敛的必要前置条件，首次训练前运行脚本 normalization statistics 计算统计文件： ```Bash uv run scripts/compute_norm_stats.py \ --task-config configs/train/tron2_tasks/my_task.yaml ``` 4.统计量计算完成后，执行训练脚本启动训练： ```Bash uv run scripts/train_tron2_task.py \ --task-config configs/train/tron2_tasks/my_task.yaml ```
❗
补充：
我们提供了一体化入口脚本 scripts/cloud_train_entrypoint_portable.sh，无需分步执行：
#### 6.2.2.1 本地自定义路径模式： 自有算力无统一挂载目录时，手动传入数据集、权重、输出完整路径： ```Bash 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`： ```Bash 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 ```
❗
补充规范说明：
  1. 自定义任务配置文件（如my_task.yaml）已配置在.gitignore 中，不会提交至代码仓库；仓库仅保留通用模型configs/train/tron2_tasks/example.yaml；
  2. 模版 YAML 支持配置项：数据集repo_id、任务文本prompt、数据列定义、 动作预测时长action_horizon、状态维度state_dim、预训练基准权重base checkpoint、训练输出路径，以及可选的 prompt_from_task 和 rtc_training_simulated_delay。
# 7. 模型部署 ## 7.1 推理部署流程
⚠️
  1. 机器人初始姿态要求：需保证机器人处于🎮 L1+X 标准初始状态：双臂自然竖直贴靠机身两侧。按序启动服务端 server 和客户端 client 后，机器人会自动侧展双臂，然后前伸，若非初始状态可能会直接抬起双臂，警惕前方物体风险。
  2. 在推理前必须将机器人🎮状态切换为高级开发者模式（High-Level Dev）。
    • 如果采集数据时没有改变桌子高度、支架距离桌子边缘距离、光照环境、头部角度，那么推理时需要保持一致。
  3. 其他环境相关约束可参考本文开头「部署最低配置」部分内容。
  4. 关于相机连接模式说明：
    1. Bridge 模式：通过 TRON2 Bridge 拉取图像数据，同步采用 Bridge 校正后的机器人状态信息；
    2. Legacy 本地直连模式：本地推理主机直连 RealSense 相机，并从机器人 WebSocket 获取状态【此时需要将机器人的三个相机的usb口接到推理机箱上】；
  5. 当 client.max_steps 为 null 时，需要手动停止客户端。
### 7.1.1 配置推理环境【同训练】
💡
说明：标题「同训练」指安装命令与【6.2.1 配置训练环境 】完全一样。如果用的是同一台电脑，环境在训练时已装好，此处无需重复安装，可直接跳到 7.1.2。
```Bash 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` ```Bash cd /home/linux_user_name/xxx/tron2_openpi mkdir checkpoints cd checkpoints hf download limxdynamics/tron2-openpi-models \ --repo-type model \ --include "pi05_tron2_cloth/**" \ --local-dir ./checkpoints ``` ### 7.1.3 部署配置 1.文件`/home/xxx/xxx/tron2_openpi/configs/deploy`下的三个yaml文件是我们的示例配置，其中`cloth_server.yaml`和`cloth_client.yaml`为关于叠衣服任务的公开示例配置，其中包含各类参数，你可以根据注释自行修改。 2.用于你自己的机器人前，请**重点确认** checkpoint 路径、机器人地址、Bridge 地址、初始化姿态和安全流程都适用于当前部署。 3.常见的修改参数【最小本地配置示例如下所示，地址在`tron2_openpi/configs/deploy/`下的任意您使用的`cloth_server.yaml`文件的policy内容（详细配置说明已写在yaml注释中）】： ```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默认fold cloth 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: cd tron2_openpi uv run scripts/serve_policy.py \ --deploy-config configs/deploy/cloth_server.yaml 2.在另一个终端启动 TRON2 客户端： cd tron2_openpi uv run examples/tron2/pi_client_rtc.py \ --deploy-config configs/deploy/cloth_client.yaml 3.运行客户端后机械臂会从竖直侧身状态平滑过渡到小臂垂直侧身的，随后即可以将衣服摊平放置在桌面上进行推理验证。 # 8. 参考资料 - 代码仓库：[tron2_openpi](https://github.com/limxdynamics/tron2_openpi) - 使用说明：[README_CN.md](https://github.com/limxdynamics/tron2_openpi/blob/main/README_CN.md) - 安装指南：[INSTALL_CN.md](https://github.com/limxdynamics/tron2_openpi/blob/main/INSTALL_CN.md)