📨 使用方法

1. 数据格式转换

• ⚠️⚠️⚠️ 从数采平台直接导出lerobot格式数据集，可跳过此步。

将 Kuavo 原生 rosbag 数据转换为 Lerobot 框架可用的 parquet 格式：

python kuavo_data/CvtRosbag2Lerobot.py \
  --config-path=../configs/data/ \
  --config-name=KuavoRosbag2Lerobot.yaml \
  rosbag.rosbag_dir=/path/to/rosbag \
  rosbag.lerobot_dir=/path/to/lerobot_data

说明：

• rosbag.rosbag_dir：原始 rosbag 数据路径
• rosbag.lerobot_dir：转换后的lerobot-parquet 数据保存路径，通常会在此目录下创建一个名为lerobot的子文件夹
• configs/data/KuavoRosbag2Lerobot.yaml：配置文件

配置文件

使用KuavoRosbag2Lerobot.yaml进行配置，关键配置项说明：

参数	描述	示例值
eef_type	末端执行器类型，可选：leju_claw,qiangnao	qiangnao
which_arm	需要哪一只手臂的关节 + 图像数据,可选: left, right, both	right
use_depth	是否需要深度图像数据	true
task_description	任务描述，自定义	"Pick and Place"
train_hz	训练数据的采样频率	10
resize/width	主相机图像缩放宽度	848

2. 模仿学习训练

使用转换好的数据进行模仿学习训练：

python kuavo_train/train_policy.py \
  --config-path=../configs/policy/ \
  --config-name=diffusion_config.yaml \
  task=your_task_name \
  method=your_method_name \
  root=/path/to/lerobot_data/lerobot \
  training.batch_size=32 \
  policy_name=diffusion

说明：

• --config-name: 配置文件，对应policy_name填写diffusion_config.yaml或act_config.yaml
• task：自定义，任务名称（最好与数转中的task定义对应），如pick and place
• method：自定义，方法名，用于区分不同的训练，如diffusion_bs128_usedepth_nofuse等
• root：训练数据的本地路径，注意加上lerobot，与1中的数转保存路径需要对应，为：/path/to/lerobot_data/lerobot
• training.batch_size：批大小，可根据 GPU 显存调整
• policy_name：使用的策略，用于策略实例化的，目前支持diffusion和act
• 其他参数可详见yaml文件说明，推荐直接修改yaml文件，避免命令行输入错误

配置文件

使用diffusion_config.yaml或act_config.yaml进行配置，关键配置项说明： |参数|描述|示例值| | :-: | :-: | :-: | |max_epoch|最大训练轮次|500| |save_freq_epoch|模型参数保存频率|10| |device|训练设备|cuda| |resume|是否开启断点续训|false| |resume_timestamp|从outputs/train/<task>/<method>/<resume_timestamp>中加载最后一个epoch参数续训|run_20251118_144927|

2.1 模仿学习训练：单机多卡模式

安装accelerate库： pip install accelerate (一般安装lerobot时已经安装)

accelerate launch kuavo_train/train_policy_with_accelerate.py \
  --config_file configs/accelerate/accelerate_config.yaml \
  --config-path=../configs/policy \
  --config-name=diffusion_config.yaml

说明：

• --config-name: 配置文件，对应policy_name填写diffusion_config.yaml或act_config.yaml参数配置参考上面2. 模仿学习训练详细参数说明

配置文件

使用accelerate_config.yaml进行配置，关键配置项说明： |参数|描述|示例值| | :-: | :-: | :-: | |num_processes|该实例中使用进程数（对应GPU数）|2| |gpu_ids|指定使用第几号GPU|"0,1"

3. 真机模型部署

完成训练后调用模型进行真机部署：

• 配置文件位于 ./configs/deploy/kuavo_env.yaml：真机运行配置

配置文件

使用kuavo_env.yaml进行配置，关键配置项说明： |参数|描述|示例值| | :-: | :-: | :-: | |env_name|kuavo环境名称|Kuavo-Real| |eef_type|末端执行器类型，可选：leju_claw,qiangnao|qiangnao| |which_arm|需要哪一只手臂的关节 + 图像数据,可选: left, right, both|right| |head_init|机器人头部初始位置|null| |ros_rate|推理控制频率|10| |image_size|主相机图像大小：宽，高|&IMGSIZE [848, 480]| |frame_alignment|是否启用帧对齐|true| |go_bag_path|到达工作位置的bag|/path/to/your/go.bag| |policy_type|策略名字 |"act"| |device|推理设备|cuda| |task|任务名|"your_task"| |method|方法名|"your_method"| |timestamp|时间戳|"your_timestamp"| |epoch|训练输出的轮次,可填50,100,best等|best| |max_episode_steps|最大回合步数|200|

⚠️ 注意：

1. 模型部署 配置文件中的参数需与 数据格式转换 或 数采平台导出 配置参数一致
2. 代码将在outputs/train/<task>/<method>/<timestamp>/epoch<epoch>中load policy的模型参数

• 启动自动化推理部署：

  bash kuavo_deploy/eval_kuavo.sh
• 按照指引操作，这步操作详见kuavo deploy

命令行弹出提示：

=== Kuavo机器人控制示例 ===
此脚本展示如何使用命令行参数控制不同的任务
-e 支持暂停、继续、停止功能

  📋 控制功能说明:
  🔄 暂停/恢复: 发送 SIGUSR1 信号 (kill -USR1 <PID>)
  ⏹️  停止任务: 发送 SIGUSR2 信号 (kill -USR2 <PID>)
  📊 查看日志: tail -f log/kuavo_deploy/kuavo_deploy.log

1. 显示帮助信息:
python kuavo_deploy/src/scripts/script.py --help

2. 干运行模式 - 查看将要执行的操作:
python kuavo_deploy/src/scripts/script.py --task go --dry_run --config /path/to/custom_config.yaml

3. 到达工作位置:
python kuavo_deploy/src/scripts/script.py --task go --config /path/to/custom_config.yaml

4. 从当前位置直接运行模型:
python kuavo_deploy/src/scripts/script.py --task run --config /path/to/custom_config.yaml

5. 插值至bag的最后一帧状态开始运行:
python kuavo_deploy/src/scripts/script.py --task go_run --config /path/to/custom_config.yaml

6. 从go_bag的最后一帧状态开始运行:
python kuavo_deploy/src/scripts/script.py --task here_run --config /path/to/custom_config.yaml

7. 回到零位:
python kuavo_deploy/src/scripts/script.py --task back_to_zero --config /path/to/custom_config.yaml

8. 仿真中自动测试模型，执行eval_episodes次:
python kuavo_deploy/src/scripts/script_auto_test.py --task auto_test --config /path/to/custom_config.yaml

9. 启用详细输出:
python kuavo_deploy/src/scripts/script.py --task go --verbose --config /path/to/custom_config.yaml

=== 任务说明 ===
go          - 先插值到bag第一帧的位置，再回放bag包前往工作位置
run         - 从当前位置直接运行模型
go_run      - 到达工作位置直接运行模型
here_run    - 插值至bag的最后一帧状态开始运行
back_to_zero - 中断模型推理后，倒放bag包回到0位
auto_test   - 仿真中自动测试模型，执行eval_episodes次

请选择要执行的示例: 1. 显示普通测试帮助信息 2. 显示自动测试帮助信息 3. 进一步选择示例
1. 执行: python kuavo_deploy/src/scripts/script.py --help
2. 执行: python kuavo_deploy/src/scripts/script_auto_test.py --help
3. 进一步选择示例
请选择要执行的示例 (1-3) 或按 Enter 退出:

在命令行输入3，按 Enter ，弹出提示

请输入自定义配置文件路径:

输入自定义配置文件路径，默认配置文件参考configs/deploy/kuavo_env.yaml，弹出提示

📁 配置文件路径: configs/deploy/kuavo_env.yaml
🔍 正在解析配置文件...
📋 模型配置信息:
   Task: your_task
   Method: your_methof
   Timestamp: your_timestamp
   Epoch: 300
📂 完整模型路径: your_path
✅ 模型路径存在
可选择要执行的示例如下:
1. 先插值到bag第一帧的位置，再回放bag包前往工作位置(干运行模式)
执行: python kuavo_deploy/src/scripts/script.py --task go --dry_run --config /path/to/config.yaml
2. 先插值到bag第一帧的位置，再回放bag包前往工作位置
执行: python kuavo_deploy/src/scripts/script.py --task go --config /path/to/config.yaml
3. 从当前位置直接运行模型
执行: python kuavo_deploy/src/scripts/script.py --task run --config /path/to/config.yaml
4. 到达工作位置并直接运行模型
执行: python kuavo_deploy/src/scripts/script.py --task go_run --config /path/to/config.yaml
5. 插值至bag的最后一帧状态开始运行
执行: python kuavo_deploy/src/scripts/script.py --task here_run --config /path/to/config.yaml
6. 回到零位
执行: python kuavo_deploy/src/scripts/script.py --task back_to_zero --config /path/to/config.yaml
7. 先插值到bag第一帧的位置，再回放bag包前往工作位置(启用详细输出)
执行: python kuavo_deploy/src/scripts/script.py --task go --verbose --config /path/to/config.yaml
8. 仿真中自动测试模型，执行eval_episodes次
执行: python kuavo_deploy/src/scripts/script_auto_test.py --task auto_test --config /path/to/config.yaml
9. 退出
请选择要执行的示例 (1-9)

• 选择需要的功能，一般先选择2再选择3，ctrl+\停止模型推理

⚠️⚠️⚠️ 首次执行需小心，可将机器人身旁物品先移开，观察到达工作位置和运行模型是否正常，符合预期

4. 说明

📡 ROS 话题说明

话题名	功能说明
/cam_h/color/image_raw/compressed	上方滤镜 RGB 彩色图像
/cam_h/深度/image_raw/compressedDepth	上方焦度深度图，realsense
/cam_l/color/image_raw/compressed	左边相机 RGB 彩色图像
/cam_l/深度/image_rect_raw/compressedDepth	左侧光圈深度图，realsense
/cam_r/color/image_raw/compressed	RGB 彩色图像
/cam_r/深度/image_rect_raw/compressedDepth	右侧相机深度图，realsense
/control_robot_hand_position	灵巧手关节角控制指令
/dexhand/state	灵巧手当前关节角状态
/leju_claw_state	乐聚夹爪当前关节角状态
/leju_claw_command	乐聚夹爪关节角控制指令
/joint_cmd	所有关节的控制指令
/kuavo_arm_traj	机器人机械臂仪表控制
/sensors_data_raw	所有传感器原始数据

📁 代码输出结构

输出/
├── train/<task>/<method>/run_<timestamp>/ # 训练模型与参数
├── eval/<task>/<method>/run_<timestamp>/ # 测试日志与视频

📂 核心代码结构

KUAVO-DATA-CHALLENGE/
├── configs/ #配置文件
├── kuavo_data/ # 数据处理转换模块
├── kuavo_deploy/ # 部署脚本（模拟器/真机）
├── kuavo_train/ # 模仿学习训练代码
├── lerobot_patches/ # Lerobot 运行补丁
├──outputs/ # 模型与结果
├──third_party/ # Lerobot 依赖
└──requirements_xxx.txt #依赖列表
└── README.md # 说明文档