LeRobot 数据集与训练
LeRobot 是 Hugging Face 维护的机器人学习数据与策略训练框架。平台把已标注的录制数据导出为 LeRobot 数据集，交由平台训练服务或平台外的 LeRobot 训练栈使用。
支持的模型与数据集版本
适用场景
| 读者 | 关心什么 | 入口 |
|---|---|---|
| 算法工程师 | 数据集字段、版本兼容、模型与训练入口 | 数据导出、模型训练 |
| 训练运维 | 训练镜像、GPU 与挂载、日志与 checkpoint | 模型训练 |
| 项目经理 | 交付数据格式、可选模型范围 | 数据导出 |
核心能力
| 能力 | 说明 | 入口 |
|---|---|---|
| 数据集导出 | 导出 LeRobot v3.0 或 v2.1，可配置图像格式、采样频率与子任务 | 数据 → 导出 |
| 在线预览 | 浏览器内播放已入库的 LeRobot 数据 | 数据 → LeRobot |
| 格式校验 | 以 LeRobotDataset 加载或经 LeRobot Studio 检查目录与元数据 | 见「数据集校验」 |
| 平台内训练 | 选择模型与框架发起训练，查看日志与 checkpoint | 模型 → 训练 |
数据 → LeRobot 的预览入口见 LeRobot 可视化。
模型与框架
平台训练服务注册 11 个策略模型。模型标识、训练框架与数据集版本如下。
| 模型标识 | 训练框架 | 数据集版本 | 专项页 |
|---|---|---|---|
act | act、lerobot | v2、v3 | ACT 模型训练 |
diffusion | lerobot | v2、v3 | Diffusion Policy 模型训练 |
groot | lerobot | v2、v3 | — |
pi0 | lerobot、jax | v2、v3 | π0 与 π0.5 模型微调 |
pi05 | lerobot、jax | v2、v3 | π0 与 π0.5 模型微调 |
reward_classifier | lerobot | v2、v3 | — |
sac | lerobot | v2、v3 | — |
smolvla | lerobot | v2、v3 | SmolVLA 模型微调 |
spirit-v1.5 | spirit | robochallenge、v2、v3 | Spirit-v1.5 模型微调 |
tdmpc | lerobot | v2、v3 | — |
vqbet | lerobot | v2、v3 | — |
「—」表示暂无专项页，参数与限制以 LeRobot 官方文档为准。
数据集版本
LeRobot 数据集版本由导出选项决定，与 Python 包版本无关。
| 导出选项 | 数据格式版本 | 说明 |
|---|---|---|
| v3.0（默认） | v3.0 | 支持子任务模式；部分模型尚不支持 |
| v2.1 | v2.1 | 兼容性最好；不支持子任务模式 |
界面选项 v3.0 对应导出参数 version=latest，v2.1 对应 version=v2.1。训练服务使用 v2、v3 两个数据集版本标识。版本差异见 LeRobot v2 与 v3 格式差异。
训练准备
训练镜像
平台训练服务按数据集版本选择 LeRobot 训练镜像，默认值如下，可由部署环境覆盖。
| 数据集版本 | 默认镜像 | 训练入口 |
|---|---|---|
| v2 | lerobot:v0.3.3 | /lerobot/.venv/bin/lerobot-train |
| v3 | lerobot:v0.4.4 | /lerobot/.venv/bin/lerobot-train |
| 未指定 | lerobot:latest | /lerobot/.venv/bin/lerobot-train |
训练任务将 v2 数据转换为 v3 时，使用 v3 默认镜像。单卡以外使用 accelerate launch 进入同一入口。以下模型使用专用镜像。
| 模型 | 默认镜像 |
|---|---|
pi0 | ioaitech/train_openpi:pi0 |
pi05 | ioaitech/train_openpi:pi05 |
act | ioaitech/train_act:cuda |
spirit-v1.5 | ioaitech/train_spirit:1.5 |
训练链路
数据集校验
导出后先做一次校验，再接入训练。优先用 LeRobot Studio 打开归档或解压目录；脚本化校验可直接加载数据集。
from lerobot.datasets import LeRobotDataset
dataset = LeRobotDataset("local/my_dataset", root="/path/to/lerobot_dataset")
print(dataset.num_frames, dataset.num_episodes)
能加载不等于适合训练，但可先排除目录层级、元数据缺失与文件缺号。
数据集导出要点
导出配置
数据选择与参数面板见下图。
| 参数 | 取值 | 说明 |
|---|---|---|
| 数据采样频率 | 1–60 Hz，默认 30 | 越低数据集越小，推荐 10–30 |
| 图像格式 | MP4、JPG | 默认 MP4；MP4 相对 JPG 约省 80% 存储 |
| 严格 匹配模型输入输出 | 允许 / 禁止 | 开启后裁切观测与指令一一对应，减少噪声 |
| 自动模糊人脸 | 允许 / 禁止 | 开启后模糊画面人脸，用于数据合规 |
| 启用子任务 | 允许 / 禁止 | 开启后每条标注成为 episode 内的子任务，仅 v3.0 |
| 适配映射 | 允许 / 禁止 | 配置后按映射生成字段，strict_match 被忽略 |
| LeRobot 版本 | v3.0、v2.1 | 版本差异见上一节 |
完整格式与配额说明见 数据导出。
字段映射
平台按 ROS 话题名后缀推断状态与动作字段。话题命名不同时，在录制阶段统一命名；已有数据无法改名时，用适配映射补齐。
| 数据集字段 | 话题名后缀 | 依据 |
|---|---|---|
observation.state | /joint_state、/joint_states、/arm_joint_state | tools/mcap2lerobot/mcap2lerobot.py |
action | /joint_command | tools/mcap2lerobot/mcap2lerobot.py |
导出结果
导出完成后下载归档并解压到独立目录。--dataset.root 指向含 meta/info.json 的目录。
your_dataset/
├── meta/
│ └── info.json
├── data/
└── videos/
使用限制
导出与训练受以下既有边界约束。
| 项目 | 限制 | 说明 |
|---|---|---|
| 导出格式版本 | v3.0、v2.1 | 界面选项 v3.0 对应参数 version=latest，v2.1 对应 version=v2.1 |
| 子任务模式 | 仅 v3.0 | 勾选启用子任务后仅可选 v3.0，创建任务时选择 v2.1 也会被拒绝 |
| 数据采样频率 | 1–60 Hz，默认 30 | 推荐 10–30；频率越低数据集越小 |
| 图像格式 | MP4、JPG | 默认 MP4 |
| 严格匹配 | 配置适配映射后忽略 | 两条设置互斥，以适配映射为准 |
| 适配映射大小 | 256 KiB 以内 | 超出上限时拒绝创建导出任务 |
| 模型图像输入 | vqbet、tdmpc 仅保留一张图像 | 训练时多余图像被忽略并记录日志 |
| 质检门禁 | 默认开启 | 质检未通过的数据集禁止导出 |
| 人脸模糊 | 依赖 SCRFD 模型且仅用 CPU | 模糊失败时中止本次导出 |
| 训练数据集版本 | v2、v3 | spirit-v1.5 另支持 robochallenge，见「支持的模型与数据集版本」 |
阅读顺序
- 导出数据集：数据导出
- 校验数据：LeRobot 可视化
- 安装环境：安装 LeRobot
- 选择模型：ACT、Diffusion Policy、π0 与 π0.5、SmolVLA、Spirit-v1.5
- 发起训练：模型训练