Skip to content
DroidFlight Wiki

LeRobot (Hugging Face)

概念速览

  • LeRobot：Hugging Face 维护的开源机器人学习库
  • 核心理念：把 NLP 的「Hugging Face 范式」搬到机器人 —— 数据集 / 模型 / 训练脚本全部开源
  • 支持任务：模仿学习 (ACT, Diffusion Policy)、强化学习、VLA 微调

仓库结构

huggingface/lerobot/
├── src/lerobot/
│   ├── datasets/       # 数据集抽象 (LeRobotDataset)
│   ├── policies/       # 模型实现 (ACT, Diffusion, VQ-BeT, OpenVLA)
│   ├── robots/         # 硬件抽象 (Aloha, SO-100, Koch)
│   ├── cameras/        # 相机抽象
│   ├── envs/           # 仿真环境 (Gym, MuJoCo)
│   └── scripts/        # CLI 入口
├── examples/           # 端到端笔记本
└── benchmarks/         # 标准测试集

主流硬件平台

硬件类型价格自由度
SO-100桌面机械臂~$2006
Aloha双臂桌面~$20K14
Koch v1.1桌面机械臂~$3006
Stretch 3移动操作~$20K12
Open-Duck Mini桌面四足~$3008

核心数据格式

from lerobot.datasets import LeRobotDataset


# 创建或加载数据集
dataset = LeRobotDataset.create(
    repo_id="your-org/my-dataset",
    robot_type="so100",
    fps=30,
    features={
        "observation.state": {"shape": (6,), "dtype": "float32"},
        "observation.image": {"shape": (3, 480, 640), "dtype": "uint8"},
        "action": {"shape": (6,), "dtype": "float32"},
    },
)

训练一行启动

Terminal window
lerobot-train \
  --policy.type=act \
  --dataset.repo_id=lerobot/aloha_sim_transfer_cube_human \
  --batch_size=8 --steps=100000

集成 VLA 模型

Terminal window
lerobot-train \
  --policy.type=openvla \
  --policy.pretrained_path=openvla/openvla-7b \
  --dataset.repo_id=your-org/your-dataset \
  --use_lora=true --lora_rank=32

社区生态

  • Hugging Face Hub：超过 200 个公开机器人数据集
  • Discord：官方 10K+ 工程师社区
  • Papers With Code：标准基准 (Sim / Real) 公开

📋 复现条件

类别必备可选 / 备注
硬件x86_64 PC (i7+32GB 或 RTX 4090) · 16GB RAM多 GPU (4× A100 训练大模型)
操作系统Ubuntu 22.04 / 24.04macOS 14 (M1+/M2+) · Windows WSL2
软件版本Python 3.10 · LeRobot 0.3+ · PyTorch 2.3+ · Hugging Face Hub CLIwandb 0.17+
网络千兆网 · 能访问 HuggingFace / GitHub云 GPU 走 WAN
账号Hugging Face 账号 (免费)Weights & Biases (训练可视化)
时间装环境 30 min · 下载预训练 30 min · 训练 50 条任务 2 h训练 7B VLA 7 天
难度⭐⭐⭐ 进阶库更新快，pin 版本
前置知识Python · PyTorch · 模仿学习概念机器人学 (kinematics)

⛔ 别这么做 (Anti-patterns)

经验证的坑 —— 跳过 = 至少浪费半天，严重的烧板 / 锁机。

❌ 错误做法💥 后果⚠️ 风险范围
不要在 Ubuntu 22.04 上 apt 装 ROS 2 Iron / Rollingapt 源是滚动版 = 兼容性没保证。ROS 2 永远装 LTS 版 (Humble / Jazzy)。🟡ROS 2
不要直接 pip install 全局包做机器人项目系统 Python 升级 = 依赖破。永远用 venv / uv venv / pixi。🟡LeRobot / ACT / OpenVLA 训练
不要把机械臂 / 移动机器人直接接到 12V 铅酸电池反接 / 短路 = 烧控制板。永远先串 5A 保险丝再接。🔴SO-100 / Mobile ALOHA / 自制机器人
不要在没看 dmesg / lsusb 前插 USB 设备并假设会被识别插上没反应 = 没供电 / 没权限 / 没驱动。先 lsusb -t，再 sudo chmod 666 /dev/ttyUSB0。🟢USB 相机 / 串口 / 飞控
不要让 micro-ROS 节点在没看门狗的情况下跑在真机上死循环 = 整机失控，永远给嵌入式节点加 heartbeat 看门狗。🔴micro-ROS / 飞控固件
不要直接拿 GitHub main 分支跑 Mobile ALOHA / LeRobot 训练main = 正在开发，可能 dataset format 改了 = 跑不通。锁 git checkout v0.4.0 标签。🟡Mobile ALOHA / LeRobot
不要在 LeRobot 训练时把 4K 视频存进 dataset4K 1 小时 ≈ 50GB，30 小时 = 1.5TB IO 瓶颈。先 ffmpeg -vf scale=640:480 降采样。🟢LeRobot / ACT 数据采集
不要用 ROS_DOMAIN_ID=0 跑多机协同0 = 默认域 = 任何人都能收到你的话题。多机实验 = 改 ID (0-232) + Foxy+。🟢ROS 2 DDS

🚨 风险总览 (Risk Matrix)

风险等级含义例子
🟢 低改错可回滚 / 几分钟恢复pip 全局装包、DHCP IP 写死
🟡 中需要重新刷机 / 重装 / 1-2 小时恢复装错 ROS 2 版本、没 OTA 升级看版本
🔴 高不可逆 / 烧板 / 安全风险电池反接、micro-ROS 没看门狗、刷机中途断电

参考资料