跳到主要内容

LeRobot 数据集与训练

LeRobot 是 Hugging Face 维护的机器人学习数据与策略训练框架。在艾欧数据平台上，用户可以把已标注的机器人数据导出为可复用的 LeRobot 数据集，然后把这些数据交给 LeRobot、OpenPI、ACT 或 Spirit-v1.5 等训练栈继续微调。

本文先说明数据导出和校验，再给出模型训练的总览。使用 LeRobot 官方训练栈前，请先阅读 安装 LeRobot；具体模型的训练命令请进入对应专项页。

导出数据​

平台支持将已标注数据导出为 LeRobot 格式。导出前请确认三类信息已经稳定：

  • observation.images.*：相机图像或视频，建议相机命名在整个项目中保持一致。
  • observation.state：机器人状态，通常是关节或末端状态。
  • action：控制动作，应与 observation.state 的时间轴严格对齐。
  • task：语言任务描述。VLA 模型通常依赖该字段；若缺失，部分镜像会允许用命令行 --prompt 兜底。

导出配置​

导出界面中的关键参数建议按训练目标设置：

参数建议
数据采样频率先按机器人控制频率保留，常见范围为 10-30 Hz；不要为了减小体积过早降采样。
图像格式大规模训练优先选 MP4；若要排查图像质量问题，可临时导出 JPG。
严格匹配模型输入输出建议开启，用于减少观测、语言指令与动作错位。
自动模糊人脸含人员画面且需要外部分发数据时建议开启。

导出完成后，下载 .tar.gz 并解压到独立目录。训练命令中的 /path/to/lerobot_dataset 应指向包含 meta/info.json 的目录，而不是其上一级目录。

your_dataset/
├── meta/
│   └── info.json
├── data/
└── videos/

Topic 映射​

平台按 ROS/ROS2 topic 名称推断状态与动作字段：

  • 以 /joint_state 或 /joint_states 结尾的话题，其 position 会写入 observation.state。
  • 以 /joint_cmd 或 /joint_command 结尾的话题，其 position 会写入 action。

如果项目中的 topic 命名不同，建议在录制阶段统一命名；已有数据无法改名时，请提前做映射适配，不要等训练失败后再排查。

数据校验​

训练前至少做一次格式校验。优先使用 LeRobot Studio 打开导出的压缩包或解压目录；它会检查 meta/info.json、features、episodes、数据文件与视频文件的基本一致性。

需要本地脚本化校验时，可以直接让 LeRobot 加载数据集：

from lerobot.datasets import LeRobotDataset

dataset = LeRobotDataset("local/my_dataset", root="/path/to/lerobot_dataset")
print(dataset.num_frames, dataset.num_episodes)

能加载不代表数据一定适合训练，但可以先排除目录层级、元数据和文件缺失问题。

训练路径​

训练文档采用“官方源码依据优先，镜像用于复现”的原则。也就是说，模型能力、限制和关键命令以官方仓库或模型卡为依据；实际运行时，推荐先用艾欧智能已经构建并公开发布的 ioaitech/* 镜像跑通训练闭环，再按需回到官方源码做深度修改。

模型推荐入口适用场景专项页
Pi0 / Pi0.5ioaitech/train_openpi:pi0、ioaitech/train_openpi:pi05高容量 VLA 微调；需要 OpenPI 基座权重与 JAX/FSDP/LoRA 路径Pi0 与 Pi0.5
SmolVLAioaitech/lerobot-gpu:v0.5.0单卡起步、快速验证 LeRobot v0.5.0 官方训练链路SmolVLA
ACTioaitech/train_act:cuda单任务模仿学习；希望用 LeRobot 数据直接桥接到 ACT/HDF5ACT
Spirit-v1.5ioaitech/train_spirit:1.5前沿 VLA 微调；RoboChallenge 数据布局或可转换的 LeRobot 数据Spirit-v1.5
Diffusion Policyioaitech/lerobot-gpu:v0.5.0 或官方源码需要平滑、连续动作序列的策略学习Diffusion Policy
国内镜像

文档默认使用 Docker Hub 镜像名。若中国大陆访问 Docker Hub 较慢，在镜像名前增加 swr.cn-east-3.myhuaweicloud.com/ 即可，例如：

  • swr.cn-east-3.myhuaweicloud.com/ioaitech/train_openpi:pi0
  • swr.cn-east-3.myhuaweicloud.com/ioaitech/train_act:cuda
  • swr.cn-east-3.myhuaweicloud.com/ioaitech/train_spirit:1.5
  • swr.cn-east-3.myhuaweicloud.com/ioaitech/lerobot-gpu:v0.5.0

挂载路径与训练参数保持不变。

训练前自检​

所有 GPU 镜像都依赖 NVIDIA 容器运行时。先确认宿主机能在容器内看到 GPU：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

训练目录建议分开：

workspace/
├── dataset/     # 解压后的 LeRobot 数据集
└── output/      # checkpoint、日志、manifest

LeRobot v0.5.0 训练入口​

LeRobot v0.5.0 安装后提供 lerobot-train 命令。本文档中所有 LeRobot 框架训练都以该命令为准。

最小命令形态如下：

lerobot-train \
  --dataset.repo_id=local/my_dataset \
  --dataset.root=/path/to/lerobot_dataset \
  --policy.type=act \
  --output_dir=outputs/train/act_baseline \
  --job_name=act_baseline \
  --policy.device=cuda

从预训练策略微调时使用 --policy.path，例如 SmolVLA：

lerobot-train \
  --policy.path=lerobot/smolvla_base \
  --dataset.repo_id=local/my_dataset \
  --dataset.root=/path/to/lerobot_dataset \
  --output_dir=outputs/train/smolvla_finetune \
  --job_name=smolvla_finetune \
  --policy.device=cuda

官方依据​

以下链接在重写时已检查可访问，文档中的技术判断优先来自这些材料：

常见问题​

数据集版本与 LeRobot 版本如何对应​

meta/info.json 中的 codebase_version 是数据格式版本，不是 Python 包版本。常见对应关系如下：

数据格式建议训练代码
v2.1旧流程通常使用 LeRobot v0.3.x；OpenPI/ACT 镜像会做兼容处理。
v3.0建议使用 LeRobot v0.4+，当前推荐 v0.5.x。

训练时提示找不到数据集​

先检查挂载层级。容器内必须存在 /data/input/meta/info.json。如果你把数据集外层目录挂进去了，容器会找不到真正的数据根目录。

应该先训练哪个模型​

如果目标是最快建立训练闭环，先用 SmolVLA 或 ACT。若任务需要更强的语言条件泛化，再转向 Pi0/Pi0.5 或 Spirit-v1.5。不要同时大规模尝试多个模型；先固定数据、评估方式和一个基线模型。

如何判断训练是否有效​

离线 loss 只能说明模型在训练分布上拟合得如何。机器人策略最终应看：

  • 固定测试初始状态下的成功率。
  • 不同物体位置、光照、背景下的成功率。
  • 推理时动作是否连续、是否有停顿、是否越界。
  • 失败样本是否集中在某一类场景或某一个相机视角。

什么时候需要回到官方源码​

以下情况建议从镜像切到源码复现：

  • 需要改数据映射、动作空间或机器人接口。
  • 需要修改模型结构、冻结策略或优化器。
  • 需要复现实验论文或官方 benchmark。
  • 需要定位镜像封装之外的底层框架问题。