# kuavo-il-opensource

**Repository Path**: leju-robot/kuavo-il-opensource

## Basic Information

- **Project Name**: kuavo-il-opensource
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2025-05-22
- **Last Updated**: 2025-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/image.png">
    <source media="(prefers-color-scheme: light)" srcset="docs/image.png">
    <img alt="Kuavo IL - 机器人模仿学习框架" src="docs/image.png" style="max-width: 100%;">
  </picture>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/image_1.png">
    <source media="(prefers-color-scheme: light)" srcset="docs/image_1.png">
    <img alt="Kuavo IL - 机器人模仿学习框架" src="docs/image_1.png" style="max-width: 100%;">
  </picture>
</p>
<div align="center">

[![Python versions](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![ROS](https://img.shields.io/badge/ROS-Noetic-green.svg)](http://wiki.ros.org/noetic)
[![LeRobot](https://img.shields.io/badge/LeRobot-Compatible-orange.svg)](https://github.com/huggingface/lerobot)

</div>

<h3 align="center">
    <p>Kuavo IL: 基于LeRobot的机器人模仿学习框架</p>
</h3>

---

🤖 **Kuavo IL** 是一个完整的机器人模仿学习框架，基于 [LeRobot](https://github.com/huggingface/lerobot) 构建，专为 Kuavo 人形机器人设计。该框架提供了从数据转换、模型训练到实际部署的完整工具链。

🎯 **核心特性**：
- 🔄 **数据转换**: 支持 ROS bag 到 LeRobot 格式的转换
- 🚀 **一键训练**: 提供数据转换与模型训练的一体化解决方案
- 🎮 **实时部署**: 支持训练模型在实际机器人上的实时推理和控制
- 📊 **完整评估**: 提供离线评估和在线部署的完整验证流程

🏗️ **项目架构**：
```
kuavo-il-opensource/
├── kuavo/                    # 核心功能模块
│   ├── kuavo_1convert/       # 数据转换工具
│   ├── kuavo_2train/         # 模型训练工具
│   ├── kuavo_3deploy/        # 模型部署工具
│   └── notebooks_check/      # 数据验证与可视化
└── lerobot/                  # LeRobot 框架 
```

## 🚀 快速开始

### 训练环境安装

1. **克隆仓库**
```bash
git clone https://gitee.com/leju-robot/kuavo-il-opensource.git
cd kuavo-il-opensource
```

2. **创建虚拟环境**
```bash
conda create -n kuavo_il python=3.10
conda activate kuavo_il
```

3. **安装依赖**
```bash
# 安装 LeRobot
pip install -e lerobot
```

## 📦 数据准备

### 目录结构

推荐的数据集目录结构如下：
```
your_task_name/
├── rosbag/          # 所有有效的数据rosbag包
└── sup_bag/         # 辅助的bag包（可选,如到达机器人起始工作位置的bag）
```

### 数据转换流程

Kuavo IL 支持从 ROS bag 数据快速转换为 LeRobot 格式。转换前需要先配置 `kuavo_1convert/lerobot_dataset.yaml` 文件：

### 配置文件
使用`lerobot_dataset.yaml`进行配置：

```yaml
only_arm: true  # 默认true, 是否只使用手臂数据, 目前的模仿学习只用于手臂数据
eef_type: dex_hand # or leju_claw
which_arm: both  # 可选: left, right, both

# task_description: "Pick the black workpiece from the white conveyor belt on your left and place it onto the white box in front of you"
task_description: "Place the black workpiece from the white desk onto the electronic scale, then move the it to the left white conveyor belt"

train_hz: 10  # 训练采样频率
main_timeline_fps: 30 # 主相机的帧率，必须稳定, 主相机来自head_cam_h, wrist_cam_l, wrist_cam_r
sample_drop: 10 # 丢弃回合前后的10帧

# dex_dof_needed是强脑手需要的自由度数目。强脑灵巧手有6个自由度。标准握拳状态[100] * 6, 张开状态[0] * 6。
# 1: 不需要精细操作或者多指协同操作时，通常为设置为1，表示只需要第一个关节作为开合依据,此时需要用[0, 100, 0, 0, 0, 0]表示张开状态, [100] * 6表示握拳状态。
# 2(暂未测试): 或者设置为2，目前的手柄遥操作只有两个自由度。0,2,3,4,5自由度绑定为1个自由度。
# 6(暂未测试): 如果脱离手柄使用手指灵巧操作，可以设置为6，表示需要所有6个自由度。
dex_dof_needed: 1   # default=1

is_binary: false  # 是否将开合二值化, default=false
delta_action: false # 是否使用增量动作，default=false
relative_start: false # 是否使用相对起始位置, default=false

resize:
  width: 848
  height: 480
```

#### 主要配置项说明
- `eef_type`: 末端执行器类型，可选'dex_hand'（灵巧手）或'leju_claw'（乐聚夹爪）
- `which_arm`: 使用的手臂，可选'left'（左臂）、'right'（右臂）或'both'（双臂）
- `train_hz`: 训练数据的采样频率
- `main_timeline`: 用于时间对齐的主时间线话题
- `dex_dof_needed`: 灵巧手使用的自由度数量

### 转换代码
`Zed`: 如果相机是zed相机，需要把`kuavo/kuavo_1convert/common/config_dataset.py`第51行`cameras = ['head_cam_h']`修改为`cameras = ['head_cam_l']`
```bash
# 转换 ROS bag 到 LeRobot 格式
python kuavo/kuavo_1convert/cvt_rosbag2lerobot.py --raw_dir RAW_DIR [-n NUM_OF_BAG] [-v PROCESS_VERSION]

# 例:
python kuavo/kuavo_1convert/cvt_rosbag2lerobot.py  --raw_dir kuavo/kuavo_1convert/Task0_example/rosbag -v v_example
```
必选参数:
  --raw_dir RAW_DIR    原始ROS包目录路径

可选参数:
  -n NUM_OF_BAG       要处理的包文件数量
  -v PROCESS_VERSION  处理版本（默认'v0'）

**注**:转换后的lerobot数据在指定存放在装载RosBag数据集的文件夹的同级目录，本案例的转换后目录结构如下
```bash
kuavo/kuavo_1convert/Task0_example
├── rosbag
│   └── example.bag
└── v_example
    └── lerobot
        ├── data
        │   └── chunk-000
        │       └── episode_000000.parquet
        ├── meta
        │   ├── episodes.jsonl
        │   ├── info.json
        │   ├── stats.json
        │   └── tasks.jsonl
        └── videos
            └── chunk-000
                ├── observation.images.head_cam_h
                │   └── episode_000000.mp4
                └── observation.images.wrist_cam_r
                    └── episode_000000.mp4
```

转换完成后可以可视化数据集：
```bash
# 可视化转换完毕的 lerobot dataset：
python lerobot/lerobot/scripts/visualize_dataset.py --repo-id lerobot/Task0_example --root kuavo/kuavo_1convert/Task0_example/v_example/lerobot  --episode 0 --local-files-only 1
```
这是Task0_example的可视化:
![alt text](docs/Task0_example_lerobot.png)
以下是一个双臂操作的可视化示例:
![4cam: plst-check](docs/vis_le.png)

## 🧠 模型训练

### 单卡训练

#### 基础训练命令

1. **进入项目根目录**
```bash
cd kuavo-il-opensource
```

2. **执行训练命令**
```bash
python lerobot/lerobot/scripts/train.py \
    --policy.type act \
    --dataset.repo_id kuavo/Task0_example \
    --dataset.local_files_only true \
    --dataset.root kuavo/kuavo_1convert/Task0_example/v_example/lerobot/ \
    --save_checkpoint true \
    --batch_size 32 \
    --num_workers 8 \
    --output_dir kuavo/kuavo_1convert/Task0_example/v_example/ \
    --steps 200000 \
    --save_freq 20000 \
    --log_freq 200
```

#### 启用 WandB 监控（可选）
如果需要记录训练过程，可以加上`--wandb.enable true` `--wandb.project Task0_example`参数。另需在终端`wandb login`根据提示输入API key登录wandb账户。
```bash
python lerobot/lerobot/scripts/train.py \
    --policy.type act \
    --dataset.repo_id kuavo/Task0_example \
    --dataset.local_files_only true \
    --dataset.root kuavo/kuavo_1convert/Task0_example/v_example/lerobot/ \
    --wandb.enable true \
    --wandb.project Task0_example \
    --save_checkpoint true \
    --batch_size 32 \
    --num_workers 8 \
    --output_dir kuavo/kuavo_1convert/Task0_example/v_example/ \
    --steps 200000 \
    --save_freq 20000 \
    --log_freq 200
```
若网络不允许实时上传wandb，可以在终端输入`wandb offline`，仍然使用`--wandb.enable true` `--wandb.project Task0_example`参数配置，这会把wandb存在`模型输出目录`里，之后查看可以`wandb sync wand/latest-run/`同步到wandb网站查看
#### 参数说明

|            参数            |                            描述                            |                         示例值                         |
| :------------------------: | :--------------------------------------------------------: | :----------------------------------------------------: |
|       `policy.type`        |                 policy类型(act)                 |                          act                           |
|     `dataset.repo_id`      | 从hf上拉数据需要，如果使用本地数据可以填<kuavo/TaskName> |          kuavo/Task0_example          |
| `dataset.local_files_only` |                    默认使用本地数据训练                    |                         `true`                         |
|       `dataset.root`       |                   本地lerobot数据集路径                    | kuavo/kuavo_1convert/Task0_example/v_example/lerobot/ |
|     `save_checkpoint`      |                      是否需要存储ckpt                      |                          true                          |
|        `batch_size`        |                     模型训练batch大小                      |                           32                           |
|       `num_workers`        |                    数据加载使用cpu数量                     |                           8                            |
|        `output_dir`        |                        模型输出目录                        |     kuavo/kuavo_1convert/Task0_example/v_example      |
|       `wandb.enable`       |         是否需要使用wandb记录训练过程,默认`false`          |                         `true`                         |
|      `wandb.project`       |                     为本次训练过程命名                     |              Task0_example              |
|          `steps`           |          总训练采样batch次数，一般100000～200000           |                         200000                         |
|        `save_freq`         |    每20000采样存储一次训练结果，可以取中间训练结果验证     |                         20000                          |
|         `log_freq`         |           每200次采样log一次loss等数据显示到终端           |                          200                           |

4. 训练如下图所示

![image-20250417171955671](./docs/single.png)

### 多卡分布式训练

#### 基础分布式训练命令

1. **进入项目根目录**
```bash
cd kuavo-il-opensource
```

2. **设置GPU环境并执行训练**
```bash
# 示例命令，如果显卡数量大于 >=4，使用前4张GPU进行分布式训练。
export CUDA_VISIBLE_DEVICES=0,1,2,3 GPUS=4
accelerate launch --num_processes=$GPUS --main_process_port 29399 --mixed_precision fp16 \
    lerobot/lerobot/scripts/train_distributed.py \
    --policy.type act \
    --dataset.repo_id kuavo/Task0_example \
    --dataset.local_files_only true \
    --dataset.root kuavo/kuavo_1convert/Task0_example/v_example/lerobot/ \
    --save_checkpoint true \
    --batch_size 32 \
    --num_workers 8 \
    --output_dir kuavo/kuavo_1convert/Task0_example/v_example/ \
    --epochs 500 \
    --save_epoch 50
```

#### 启用 WandB 监控（可选）
```bash
export CUDA_VISIBLE_DEVICES=0,1,2,3 GPUS=4
accelerate launch --num_processes=$GPUS --main_process_port 29399 --mixed_precision fp16 \
    lerobot/lerobot/scripts/train_distributed.py \
    --policy.type act \
    --dataset.repo_id kuavo/Task0_example \
    --dataset.local_files_only true \
    --dataset.root kuavo/kuavo_1convert/Task0_example/v_example/lerobot/ \
    --wandb.enable true \
    --wandb.project Task0_example \
    --save_checkpoint true \
    --batch_size 32 \
    --num_workers 8 \
    --output_dir kuavo/kuavo_1convert/Task0_example/v_example/ \
    --epochs 500 \
    --save_epoch 50
```

#### 分布式训练参数说明

|            参数            |           描述           |                       示例值                        |
| :------------------------: | :----------------------: | :-------------------------------------------------: |
|      `num_processes`       |   训练时使用的GPU数量    |                         3                         |
|    `main_process_port`     |   执行训练进程的端口号   |                       29599                       |
| `mixed_precision` |   是否使用混合精度训练   |                       fp16                        |
| `policy.type` |   policy类型(act)  |                         act                         |
| `dataset.repo_id` |    从hf上拉数据需要，如果使用本地数据可以填<TaskName/lerobot>  |                       kuavo/Task0_example                      |
| `dataset.local_files_only` |  默认使用本地数据训练    |                       `true`                        |
| `dataset.root` | 本地lerobot数据集路径 |              kuavo/kuavo_1convert/Task0_example/v_example/lerobot/              |
|       `save_checkpoint`       |   是否需要存储ckpt       |   true   |
|        `batch_size`        |    模型训练batch大小        | 32 |
| `num_workers` |    数据加载使用cpu数量   |                         8                         |
| `output_dir` |    模型输出目录  |                       kuavo/kuavo_1convert/Task0_example/v_example/                       |
| `wandb.enable` |   是否需要使用wandb记录训练过程,默认`false`   |                       `true`                        |
| `wandb.project` | 为本次训练过程命名 |              Task0_example              |
|       `epochs`       |   训练轮数(数据集遍历一轮)   |   600   |
|        `save_epoch`        |    每50轮存储一次训练结果        | 50 |

4.成功启动训练则显示下图

![image-20250417171955671](./docs/multi.png)



## 📊 性能评估(可选步骤)

### 离线评估

可以在训练的时候选取部分数据集不参与训练，转化为lerobot格式后进行离线评估作为初步模型的性能验证。

使用 Jupyter Notebook 进行离线评估：
进入 `kuavo/notebooks_check/` 目录，打开 `offlineEval_LeRobot.ipynb`：
1. 修改数据集路径和模型路径
    ```python
    class EvalConfig:
        """Evaluation configuration parameters"""
        
        # Dataset configuration
        dataset_root: str = "/Users/calmzeal/camille/code/kuavo_il/kuavo/kuavo_1convert/Task0_example/v_example/lerobot"
        local_files_only: bool = True
        
        # Model configuration
        model_checkpoint_path: str = "/Users/calmzeal/camille/code/kuavo_il/kuavo/kuavo_1convert/Task0_example/v_example/2025-08-05/22-12-36_act/checkpoints/000010/pretrained_model"
        
        # Evaluation configuration
        selected_episodes_num: int = 4  # 需要可视化的episode数量
        random_seed: int = 42
        
        # Data preprocessing configuration
        joint_slice_range: List[int] = field(default_factory=lambda: [0, 16])   # 模型输入的维度
        fps: int = 10   # 模型训练时的帧率
        
        # Noise configuration
        image_noise_level: float = 0.0
        state_noise_scale: float = 0.0
        
        # Timestamp configuration - convenient for adjusting sensor data
        camera_sensors: Dict[str, bool] = field(default_factory=lambda: {
            "head_cam_l": False,  # Enable head left camera
            "wrist_cam_r": True,   # Enable wrist right camera
            "wrist_cam_l": True,   # Enable wrist left camera
            "head_cam_h": True,    # Enable head main camera
        })
        
        # Visualization configuration
        # [(0, 8), (13, 21)]，表示左手和右手的关节组。如果是单手那么就只需要一个关节组，例如 [(0, 8)]
        visualization_joint_groups: List[List[int]] = field(default_factory=lambda: [(0, 8), (13, 21)])
        show_image_samples: int = 14    # 表示可视化图像的数量
        
        # Device configuration
        device: str = "cuda:0" if torch.cuda.is_available() else "cpu"
    ```
2. 运行所有单元格进行评估,最终绘图得到类似下图的离线评估结果(如图所示)：
    ![离线评估结果](docs/offline_eval_result.png)



## 🎮 模型部署

### 1. AGX ORIN运行环境配置
- 首先检查是否已经安装`py310kuavomimc`虚拟环境，如果可以`source ~/py310kuavomimic/bin/activate`，则已安装
- `pip show lerobot` 和 `pip show kuavo` 检查是否有输出，有则已安装依赖
-  终端输入`python`回车，输入`import torch;torch.cuda.is_available()`,如果结果是true则安装arm版本已torch已经安装
- `source ~/kuavo-il-opensource/kuavo/kuavo_3deploy/utils/kuavo_ws/devel/setup.bash`，如果成功则已编译消息。如果没有这个文件夹，可以source `~/kuavobrain/devel/setup.bash`。如果都没有，请把下位机的相关的`kuavo_msgs`包拷贝到上位机编译。
如果以上环境缺失，可以根据以下方法安装：
```bash
# 创建虚拟环境
cd ~
python3.10 -m venv py310kuavomimic
source ~/py310kuavomimic/bin/activate

# 安装依赖
git clone https://gitee.com/leju-robot/kuavo-il-opensource.git
cd kuavo-il-opensource
pip install -e lerobot
pip install -e kuavo

# 替换arm版本torch(来源: https://pypi.jetson-ai-lab.dev/jp5/cu114, 挂梯子更快)
cd ~
wget https://pypi.jetson-ai-lab.dev/jp5/cu114/+f/8b3/cd6e6090269bd/torch-2.2.0-cp310-cp310-linux_aarch64.whl#sha256=8b3cd6e6090269bd5f0ed3e1f7412f8616097b3493a08e1955b3d5f7f3481a44
wget https://pypi.jetson-ai-lab.dev/jp5/cu114/+f/a23/9d8b8b13c337e/torchvision-0.17.2+c1d70fe-cp310-cp310-linux_aarch64.whl#sha256=a239d8b8b13c337e742124669438e4152b4ead04c72486db330141b312404e86
如果上面两个连接失效，可以从以下地址下载：http://120.55.169.67/downloads/
wget http://120.55.169.67/downloads/torch-2.2.0-cp310-cp310-linux_aarch64.whl 
wget http://120.55.169.67/downloads/torchvision-0.17.2+c1d70fe-cp310-cp310-linux_aarch64.whl
如果太慢,可以从以下地址下载：
curl -o torchvision-0.17.2%2Bc1d70fe-cp310-cp310-linux_aarch64.whl "https://kuavo.ks3-cn-shanghai.ksyuncs.com/datahub/aarch_torch/torchvision-0.17.2%2Bc1d70fe-cp310-cp310-linux_aarch64.whl?AccessKeyId=TEMPb44a9a1HuBH0hYUBMuxcT96mUmQ7%2FD7eyBdpYJSfZpWiP9hqT3t3WVEi9bHbUjxPBr0rYfjzvbegtzdSd7%2BBAXe%2B6myw5n2FeB6evorDqjsn1XxFOg%2BbGQ9vogizdonKYSBUOrEwq9a0r79jX%2BUpOv1oQg%3D%3D&Expires=3902114989&Signature=tYXMJJMDKQ%2BfqAY73i4jHIfw%2B6o%3D"
curl -o torch-2.2.0-cp310-cp310-linux_aarch64.whl "https://kuavo.ks3-cn-shanghai.ksyuncs.com/datahub/aarch_torch/torch-2.2.0-cp310-cp310-linux_aarch64.whl?AccessKeyId=TEMPb44a9a1HuBH0hYUBMuxcT96mUmQ7%2FD7eyBdpYJSfZpWiP9hqT3t3WVEi9bHbUjxPBr0rYfjzvbegtzdSd7%2BBAXe%2B6myw5n2FeB6evorDqjsn1Xym1b6PvXWZhOrskAmexxsUAAkqLx5l%2F73Ikb4takUi1g%3D%3D&Expires=3902115231&Signature=eYdanbb4KtP00eDvYLXAabhaF8M%3D"

pip install torch-2.2.0-cp310-cp310-linux_aarch64.whl torchvision-0.17.2+c1d70fe-cp310-cp310-linux_aarch64.whl
# 安装完终端输入python，import torch;torch.cuda.is_available(),如果结果是true则安装arm版本torch成功

# 编译消息类型
cd ~/kuavo-il-opensource/kuavo/kuavo_3deploy/utils/kuavo_ws/
catkin_make -DPYTHON_EXECUTABLE=/usr/bin/python3 -DCMAKE_POLICY_VERSION_MINIMUM=3.5
source ~/py310kuavomimic/bin/activate
source ~/kuavo-il-opensource/kuavo/kuavo_3deploy/utils/kuavo_ws/devel/setup.bash

# 其他工具
sudo apt install direnv # 可以在项目目录下激活环境变量或者加载其他配置
```

### 部署配置
`注`：若未采集头部关节信息，尽量保证头部与头部摄像机视角与数据时一致(头部关节和机器人站位)。
`Zed`: 如果使用Zed相机，将`head_cam_h:  &head_cam_h_obs  ["/cam_h/color/image_raw/compressed", "CompressedImage", 30, [640, 480]]`修改为：`head_cam_l:  &head_cam_h_obs  ["/zedm/zed_node/left/image_rect_color/compressed", "CompressedImage", 30, [640, 480]]`
配置部署参数 (`kuavo/kuavo_3deploy/resources/deploy_config.yaml`)：
1. deploy_config.yaml(kuavo/kuavo_3deploy/resources/deploy_config.yaml), 与数据转换的配置文件对应
    - policy: `act`
    - ckpt_path:`pretrained_model`所在文件路径
    - which_arm: `left` or `right` or `both`
    - eef_type: `dex_hand` or `leju_claw`
    - frequency: `10` or `30` or ..., 这里与数据转换时候`train_hz`对齐
    - go_bag_path: 录制到达工作位置的bag，起始为0位，结束为数据集开始的位置

    ```yaml
    ### ATTENTION: 根据模型训练的配置修改以下参数
    policy: "act"                                                    # 策略类型
    ckpt_path: /home/leju_kuavo/model/Task26_waic_dex/model_preview  # 模型路径
    which_arm: "both"                                                # 使用手臂：left/right/both
    eef_type: "dex_hand"                                             # 末端执行器：dex_hand/leju_claw
    frequency: 10                                                    # 训练时采样的频率，默认是10hz(相机raw数据是30hz, 训练时采样频率是10hz)
    go_bag_path: "/home/leju_kuavo/kuavo_il/go_final.bag"            # 采集数据时录制的到达工作位置的bag包，即到达数据集开始位置的包
    use_temporal_ensembler: True                                     # 是否使用时域集成，用于平滑轨迹，但是轨迹输出频率会降低。若速度慢可以设置为False但是牺牲平滑度。

    ### ATTENTION: 灵巧手通常视为二值(抓/放），若需测试全自由度可将qiangnao_slice部分修改为left: [0, 6], right: [6, 12]
    kuavo_arm_of_sensors_data_raw_slice:  ### len(/sensors_data_raw.joint_data.joint_q) == 28, 
    left: [12, 19]                      # [12, 19]是左臂7个关节，
    right: [19, 26]                     # [19, 26]是右臂
    qiangnao_slice:                       ### len(/dexhand/state.position) == 12, 左右手各6个关节
    left: [0, 1]                        # [0, 1]是左手指第一个关节
    right: [6, 7]                       # [6, 7]指右手指第一个关节
    leju_claw_slice:                      ### len(/leju_claw_state.position) == 2, 左右夹爪各1个关节
    left: [0, 1]                        # [0, 1]是左手夹爪
    right: [1, 2]                       # [1, 2]指右手夹爪
    ```

2. example.py(kuavo/kuavo_3deploy/example/example.py)
    - `arm.kuavo_interface.control_head(yaw=-40, pitch=0)`, 头部控制，尽可能保证头部姿态与数据采集时相同
    - 任务设置
    ```python
    task = "go_run"  # go_run, here_run, back_to_zero
    task_map = {
        "go_run": arm.go_run,   # 到达工作位置直接运行模型
        "here_run": arm.here_run,   # 从go_bag的最后一帧状态开始运行
        "back_to_zero": arm.back_to_zero,   # 中断模型推理后，倒放bag包回到0位
        "run": arm.run,  # 从当前位置直接运行模型
        "go": arm.go    # 到达工作位置
    }  
    ```
3. 运行`example.py`(建议初次使用调试运行，并查看模型输出关节角度是否合理，以免出现问题)
    ```bash
    source ~/py310kuavomimic/bin/activate
    source ~/kuavo-il-opensource/kuavo/kuavo_3deploy/utils/kuavo_ws/devel/setup.bash
    python kuavo/kuavo_3deploy/examples/example.py --task go
    python kuavo/kuavo_3deploy/examples/example.py --task run
    ```
    | 任务类型 | 说明 |
    |---------|------|
    | `go` | 到达工作位置 |
    | `run` | 从当前位置直接运行模型 |
    | `go_run` | 到达工作位置直接运行模型 |
    | `here_run` | 从go_bag的最后一帧状态开始运行 |
    | `back_to_zero` | 中断模型推理后，先插值回bag最后一帧的位置，然后倒放bag包回到0位 |



## 📊 数据验证
在数据转换后，建议使用 Jupyter Notebook 进行数据集验证和可视化。
在 `kuavo/notebooks_check/` 目录下，您可以找到以下 Jupyter Notebook 文件：
- `dataset_check_lerobot.ipynb`: 用于检查和可视化转换后的 LeRobot 数据集。

## 📁 项目结构详解

```
kuavo-il-opensource/
├── kuavo/
│   ├── kuavo_1convert/           # 数据转换模块
│   │   ├── cvt_rosbag2lerobot.py # ROS bag 转 LeRobot 格式
│   │   ├── common/               # 通用工具函数
│   │   └── collect_data/         # 数据采集工具
│   ├── kuavo_2train/             # 训练模块
│   │   ├── convert_and_train.py  # 一键训练脚本
│   │   ├── convert_and_train.sh  # Shell 版本训练脚本
│   │   └── train_distributed.sh  # 分布式训练脚本
│   ├── kuavo_3deploy/            # 部署模块
│   │   ├── eval.py               # 评估脚本
│   │   ├── env.py                # 环境接口
│   │   ├── examples/             # 部署示例
│   │   ├── resources/            # 配置文件
│   │   └── utils/                # 工具函数
│   └── notebooks_check/          # 验证和可视化
│       ├── dataset_check_lerobot.ipynb
│       ├── offlineEval_LeRobot.ipynb
│       └── eval_offline_doc/     # 评估文档
├── lerobot/                      # LeRobot 框架 (子模块)
├── docs/                         # 项目文档
├── ci_scripts/                   # CI/CD 脚本
└── README.md                     # 项目说明
```



## 🙏 致谢

- 感谢 [LeRobot](https://github.com/huggingface/lerobot) 团队提供的优秀框架
- 感谢 [Diffusion Policy](https://diffusion-policy.cs.columbia.edu/) 的原始实现
- 感谢 [ACT](https://tonyzhaozh.github.io/aloha/) 和 [VQ-BeT](https://sjlee.cc/vq-bet/) 的开源贡献

## 📚 参考文献

如果您在研究中使用了本框架，请引用：

```bibtex
@misc{kuavo_il2024,
    title={Kuavo IL: A Complete Imitation Learning Framework for Humanoid Robots},
    author={Kuavo Team},
    year={2024},
    howpublished={\url{https://gitee.com/leju-robot/kuavo-il-opensource.git}}
}
```

同时请引用相关的原始工作：

- **LeRobot**: [LeRobot GitHub](https://github.com/huggingface/lerobot)
- **Diffusion Policy**: Chi et al., "Diffusion Policy: Visuomotor Policy Learning via Action Diffusion"
- **ACT**: Zhao et al., "Learning fine-grained bimanual manipulation with low-cost hardware"
- **VQ-BeT**: Lee et al., "Behavior generation with latent actions"

## 📞 联系我们

- 项目主页: [GitHub Repository](https://gitee.com/leju-robot/kuavo-il-opensource.git)
- 问题反馈: [Issues](https://gitee.com/leju-robot/kuavo-il-opensource.git/issues)
- 技术文档: [Documentation](https://kuavo.lejurobot.com/beta_manual/basic_usage/kuavo-ros-control/docs/5%E5%8A%9F%E8%83%BD%E6%A1%88%E4%BE%8B/%E6%8B%93%E5%B1%95%E6%A1%88%E4%BE%8B/%E6%A8%A1%E4%BB%BF%E5%AD%A6%E4%B9%A0%E4%BD%BF%E7%94%A8%E6%A1%88%E4%BE%8B/%E6%A1%88%E4%BE%8B%E6%A6%82%E8%BF%B0/)

---

<div align="center">
  <p>🤖 让机器人学习变得简单高效 🚀</p>
</div>