LeTools-Learning
[](LICENSE)
[](https://www.python.org/)
[](https://github.com/huggingface/lerobot)
[](http://wiki.ros.org/noetic)
[](https://www.lejurobot.com/zh)
📖 [完整文档](https://www.letools.lejurobot.com)
---
## 🚀 News
- **[2026-05-30]** : 支持lerobot0.5.2内置的10种模型与原版模型(lingbotvla, pi0, pi0fast, pi05, gr00tN1.7)
- **[2026-06-13]** : 新增离线推理、异步推理与RTC
- **[2026-07-09]** : 新增LingbotVLA-v2模型
## ✨ 核心特性
| 特性 | 说明 |
|:---:|:---|
| 📦 **数据转换** | Rosbag → LeRobot Dataset v3 格式 |
| 🧠 **lerobot集成** | 模仿学习（ACT、DPT、Multi-task DIT）+ VLA（PI0、PI0_FAST、PI0.5、GR00T N1.5、WALL-X、XVLA、SmolVLA）|
| 🔌 **外部模型** | Pi0 / Pi0.5 / GR00T N1.7 / LingbotVla / LingbotVla-v2 |
| 🚀 **仿真&真机** | Kuavo 仿真与真机部署评测流程 |
| 🦾 **多平台支持** | Kuavo 4 Pro · Kuavo 5 · Kuavo 5W |
---
## 📋 环境要求
推荐环境：
- Ubuntu 20.04
- Python 3.12
- ROS Noetic
- 支持 CUDA 的 NVIDIA GPU（训练需要）
- Conda / Miniforge
- Docker 与 NVIDIA Container Toolkit（仿真或容器化 ROS 工作流需要）
---
## 🛠️ 安装
**1. 克隆仓库**
```bash
git clone https://github.com/LejuRobotics/LeTools-Learning.git
cd LeTools-Learning
```
**2. 创建环境**
```bash
conda create -n letools python=3.12
conda activate letools
```
**3. 一键安装依赖**
```bash
source /opt/ros/noetic/setup.bash
chmod +x setup_env.sh
bash setup_env.sh
```
> 📘 完整安装步骤见 [安装指南](https://www.letools.lejurobot.com/docs.html#get_started/installation.md)
---
## 🚀 快速开始
### 📊 Step 1 — 数据转换：Rosbag → LeRobot
编辑 `configs/data/KuavoRosbag2Lerobot.yaml`：
```yaml
rosbag:
mode: normal
rosbag_dir: /path/to/rosbags
target_dir: /path/to/output_parent
dataset:
platform_type: "4pro" # 4pro, 5, or 5w
eef_type: leju_claw # leju_claw, rq2f85, or qiangnao
which_arm: both # left, right, or both
task_description: "Pick and Place"
```
```bash
python kuavo_data/CvtRosbag2Lerobot.py
```
> 输出目录：`/path/to/output_parent/lerobot` · 详情见 [数据准备](https://www.letools.lejurobot.com/docs.html#tutorials/data_preparation.md)
---
### 🧠 Step 2 — 策略训练
编辑配置文件，例如 `configs/train/lerobot/act.yaml`：
```yaml
dataset:
repo_id: "lerobot/your_dataset" # 标识名，可任意起
root: /path/to/your/lerobot # 本地 lerobot 数据集目录
training:
resume: false
output_dir: "outputs/train/act"
job_name: "act"
batch_size: 32
steps: 100000
save_freq: 20000
num_workers: 8
seed: 1000
```
```bash
python kuavo_model/train.py --policy act
```
📝 常用训练参数
| 参数 | 说明 |
|:---|:---|
| `--policy` | **必填**，支持：`act` `diffusion` `pi0` `pi0_fast` `pi05` `gr00t` `smolvla` `xvla` `multi_task_dit` `wall_x` |
| `--mode simple` | 默认模式，先读 `total/_total.yaml`，再用 `.yaml` 覆盖常用字段 |
| `--mode total` | 只读取完整配置 |
| `--launcher python` | 默认，单机单卡 |
| `--launcher accelerate` | 单机多卡，需先配置 `configs/accelerate/accelerate_config.yaml` |
| `--dry-run` | 只打印解析后的命令和配置，不真正启动训练 |
| `--no-timestamp` | 不为输出目录追加时间戳 |
> 📘 更多说明见 [LeRobot 模型训练](https://www.letools.lejurobot.com/docs.html#tutorials/lerobot_training.md) · [原生模型训练](https://www.letools.lejurobot.com/docs.html#tutorials/model_training.md)
---
### 🚁 Step 3 — 推理部署
编辑 `configs/deploy/deploy.yaml`：
```yaml
env:
inference_env: sim # sim=仿真, real=真机
platform_type: "4pro"
which_arm: both
eef_type: rq2f85
ros_rate: 10
inference:
policy_type: act # 策略名称
pretrained_path: /path/to/checkpoint # 权重路径
task_prompt: "robot manipulation" # VLA 策略需指定 prompt
```
```bash
python kuavo_deploy/eval.py
```
🔌 外部模型部署
外部模型位于 `kuavo_model/external_models/`，当前集成：
- `openpi` · `gr00tn1d7` · `lingbot-vla` · `lingbot-vla-v2`
均可通过 `kuavo_server` adapter 接入统一部署流程。使用外部模型时：
1. 先启动模型服务器
2. 在部署配置中设置 `inference.policy_type: client`
> 📘 详情见 [推理与部署](https://www.letools.lejurobot.com/docs.html#tutorials/inference.md)
---
## 🗂️ 项目结构
```text
.
├── configs/ # 数据、训练、部署、平台配置
│ ├── data/ # Rosbag -> LeRobot 数据转换配置
│ ├── train/lerobot/ # LeRobot simple/total 训练配置
│ ├── deploy/ # 仿真 / 真机部署配置
│ ├── platform/ # Kuavo 平台关节与机器人映射
│ └── accelerate/ # 多卡训练配置
├── kuavo_data/ # 数据转换与数据处理工具
├── kuavo_model/ # 训练入口与外部模型目录
├── kuavo_deploy/ # ROS 部署、评测、仿真/真机环境
├── kuavo_server/ # 标准化模型服务 adapter
├── third_party/ # LeRobot 等第三方子模块
├── lerobot_patches/ # 上游兼容补丁
└── outputs/ # 训练与评测输出
```
## 📚 文档导航
| 主题 | 文档 |
| ------------ | ------------------------------------------------------------------------------------------------ |
| 项目介绍 | [查看文档](https://www.letools.lejurobot.com/docs.html#get_started/intro.md) |
| 安装指南 | [查看文档](https://www.letools.lejurobot.com/docs.html#get_started/installation.md) |
| 快速开始 | [查看文档](https://www.letools.lejurobot.com/docs.html#tutorials/quick_start.md) |
| 数据准备 | [查看文档](https://www.letools.lejurobot.com/docs.html#tutorials/data_preparation.md) |
| LeRobot 模型训练 | [查看文档](https://www.letools.lejurobot.com/docs.html#tutorials/lerobot_training.md) |
| 外挂模型训练 | [查看文档](https://www.letools.lejurobot.com/docs.html#tutorials/model_training.md) |
| 推理与部署 | [查看文档](https://www.letools.lejurobot.com/docs.html#tutorials/inference.md) |
| 新策略拓展 | [查看文档](https://www.letools.lejurobot.com/docs.html#tutorials/bring_policies.md) |
## 💬 支持与反馈
我们鼓励通过 GitHub 渠道反馈问题，使之可被搜索、归档，也方便后来者复用。
| 我想要... | 推荐渠道 |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 报告 Bug 或运行时报错 | [GitHub Issues](https://github.com/LejuRobotics/LeTools-Learning/issues/new?labels=bug)（请附环境信息、复现步骤、完整 traceback） |
| 提交新功能建议 / 模型接入需求 | [GitHub Issues](https://github.com/LejuRobotics/LeTools-Learning/issues/new?labels=enhancement) | |
| 国内用户交流群 | QQ 群 / 微信群入群方式见 [社区交流](https://www.letools.lejurobot.com/docs.html#troubleshooting/community.md) |
| 项目合作 / 企业级支持 | [lejurobot@lejurobot.com](mailto:lejurobot@lejurobot.com) |
**提交 Issue 前请先：**
1. 搜索 [已有 Issues](https://github.com/LejuRobotics/LeTools-Learning/issues?q=is%3Aissue) 和 [常见问题 FAQ](https://www.letools.lejurobot.com/docs.html#troubleshooting/faq.md)，避免重复。
2. 阅读 [贡献指南](https://github.com/LejuRobotics/LeTools-Learning/blob/main/CONTRIBUTING.md) 了解分支策略与 PR 流程。
3. 使用对应的 [Issue 模板](https://github.com/LejuRobotics/LeTools-Learning/issues/new/choose)，填全环境与复现信息。
**响应预期：** 本项目由乐聚机器人算法团队在工作时间维护。我们会尽力响应所有公开渠道的反馈，但**不对修复时间作正式 SLA 承诺**；如需企业级保障，请走商业合作邮箱。
**乐聚内部成员：内部沟通渠道**（外部用户可忽略）
内部沟通流程不公开维护在本仓库，请通过以下入口：
- **KDC 用户群**（飞书）：日常使用答疑
- **飞书表格**：缺陷提报 / 意见反馈 填入飞书表格，将会按严重等级流转（严重缺陷 → 紧急修复；普通缺陷 → 算法部临时方案 + 正式版本修复；意见建议 → 评审后纳入计划）
- **飞书项目**：如需新增全新的功能（如新模型接入）走正式需求流程
详细流程请见公司内部 Wiki。
## 🙏 致谢
本项目构建在以下开源项目和生态之上：
- [LeRobot](https://github.com/huggingface/lerobot)
- [OpenPI](https://github.com/Physical-Intelligence/openpi)
- [NVIDIA Isaac GR00T](https://github.com/NVIDIA/Isaac-GR00T)
- [Lingbot-VLA](https://github.com/robbyant/lingbot-vla)
- Kuavo 人形机器人软件生态
## 📄 许可证
本仓库基于 [GNU General Public License v3.0](LICENSE) 开源。