用 LeRobot 打通机械臂从数据到部署的完整实战指南
用 LeRobot 打通机械臂从数据到部署的完整实战指南
如果你手上有两台 SO-101 机械臂、一张 RTX 3060 和一个 Hugging Face 账号,用 LeRobot——一个 PyTorch 原生、硬件无关的机器人学习框架——今晚就能走完「录数据 → 训模型 → 上真机」的完整闭环。下面按踩坑顺序讲:怎么装、它替你藏了什么、最短闭环怎么走、GPU 怎么选、往深了走去哪找。
SO-101 机械臂在 LeRobot 数据收集与推理流程中的实际运行画面
装好它:一条命令 + 一张硬件清单
pip 一条命令装完
当前版本是 0.6.2,要求 Python ≥ 3.12。核心依赖(torch、opencv、gymnasium、huggingface-hub)会随包一起装好:
pip install lerobot # 从 PyPI 安装,含核心依赖
lerobot-info # 打印版本、已注册机器人/策略,验证环境
装完跑 lerobot-info,如果能看到策略列表和版本号,说明环境通了。想跑特定硬件(比如 Feetech 舵机),再装对应 extras:pip install -e ".[feetech]"。
硬件清单先过一遍
据项目 README,内置机器人覆盖 12 类:SO100、LeKiwi、Koch、HopeJR、OMX、EarthRover、Reachy2、手柄、键盘、手机、OpenARM、Unitree G1、reBot B601。新手最便宜、文档最全的是 SO-101 机械臂:6 个 STS3215 舵机 + 一个 MotorBus 串口适配器,follower(被控臂)和 leader(示教臂)各一套,再加 2 个 USB 相机。
先让端口和相机被找到
连上机器后,先用两个探测命令确认硬件能被系统识别:
lerobot-find-port # 拔插 USB,自动定位每个 MotorBus 的串口(如 /dev/ttyACM0)
lerobot-find-cameras # 打印各相机编号并保存测试帧到 outputs/captured_images
Linux 下若提示无权限,先 sudo chmod 666 /dev/ttyACM0 /dev/ttyACM1 再跑。⚠️ 串口记错了后面所有命令都会找不到设备,这一步别省。
Robot 抽象层到底替你藏了什么
统一接口长什么样
LeRobot 的核心是一个 Robot 基类(源码在 src/lerobot/robots/robot.py),它把「硬件差异」挡在 4 个方法后面:connect()、get_observation()、send_action()、disconnect()。对你来说,换一台机器人 = 换一个 config,主循环代码一行不动:
robot = MyRobot(config=...)
robot.connect()
obs = robot.get_observation() # 读观测:关节角 + 相机帧
action = model.select_action(obs) # 策略出动作
robot.send_action(action) # 写回电机
白话讲:它给你装了一套「眼-脑-手」的联动总线,你只管喂观测、收动作,底层是串口、CAN 还是网络不用管。
12 种内置机器人 + 插件机制
内置机器人之外,社区用「插件」扩到 xArm、UR5e、Franka、AgileX Piper、WidowX、ROS 2 桥接等。插件按包名自动发现:任何已安装的 lerobot_robot_*、lerobot_teleoperator_*、lerobot_camera_* 包,都会被 CLI 直接识别,--robot.type= 就能选。你不需要改 LeRobot 源码。
| 集成方式 | 你要做的事 | 触发条件 |
|---|---|---|
| 内置机器人 | 填 config 即用 | 12 类官方平台 |
| 社区插件 | pip install lerobot_robot_<name> | 包名以 lerobot_robot_ 等前缀开头 |
| 自研机器人 | 继承 Robot 实现 4 个方法 | 复用记录/训练/可视化全套工具 |
抽象层的代价
抽象不是免费的:get_observation() 返回的是一个 dict(相机名 → 图像,加关节向量),字段名必须和你录数据时一致,否则训练/推理时对不上。这是后面「四条命令闭环」里最容易被忽略的约定。
LeRobot 机械臂最短闭环:录数据、训模型、上真机
第一条:lerobot-record 录数据
以双相机 SO-101 为例,lerobot-record 会把视频(MP4)和状态/动作(Parquet)按帧同步存成 LeRobotDataset 格式。录制中用键盘控制:→ 保存当前集、← 删掉重来、ESC 结束并上传(需先 hf auth login)。
lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--dataset.repo_id=${HF_USER}/so101_dataset_test \
--dataset.num_episodes=30 \
--dataset.single_task="put the red brick in a bowl" \
--dataset.streaming_encoding=true
🔧 相机分辨率、fps、相机名必须和后面 rollout 完全一致,这是第一处最容易翻车的地方。
第二条:lerobot-train 训模型
数据集在 Hub 上之后,训练只需一条命令。act 是入门最轻的策略:
lerobot-train \
--dataset.repo_id=${HF_USER}/so101_dataset_test \
--policy.type=act \
--policy.device=cuda \
--output_dir=outputs/train/act_so101 \
--job_name=act_so101 \
--steps=20000
微调别人训好的模型时,把 --policy.type 换成 --policy.path=username/the_policy 即可,路径优先、可省略 type。
第三条:lerobot-rollout 上真机
训练完,lerobot-rollout 把策略跑回真机(v0.5.1 及以前这步叫 lerobot-record,注意版本差异)。--task 给一句任务描述,--duration 单位是秒,不填就一直跑:
lerobot-rollout \
--strategy.type=base \
--policy.path=${HF_USER}/my_policy \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM1 \
--robot.cameras="{ up: {type: opencv, index_or_path: /dev/video1, width: 640, height: 480, fps: 30}, side: {type: opencv, index_or_path: /dev/video5, width: 640, height: 480, fps: 30} }" \
--task="Put lego brick into the transparent box" \
--duration=60
没有真机想验证策略?用 lerobot-eval 在 LIBERO、MetaWorld 等仿真基准上跑,比如 lerobot-eval --policy.path=... --env.type=libero --env.task=libero_object --eval.n_episodes=10。
LeRobot 统一控制接口下多机器人策略推理的实时画面
GPU 选型与四个让训练卡住的参数
显存选型先看这张表
据 docs/source/hardware_guide.mdx 的量级估算(BS=8、AdamW,实际会随分辨率/IO 偏差 ±50%),VRAM 是第一道过滤器:
| 策略组 | 代表策略 | 峰值显存 | 起步 GPU |
|---|---|---|---|
| 轻量 BC | act、vqbet、tdmpc | ~2–6 GB | RTX 3060 |
| Diffusion | diffusion、multi_task_dit | ~8–14 GB | RTX 4070+ |
| 小 VLA | smolvla | ~10–16 GB | RTX 4080+ |
| 大 VLA | pi0、pi05、xvla | ~24–40 GB | A100 40 GB |
| 多模态 | groot、eo1 | ~24–40 GB | A100 40 GB |
RTX 3060 只能碰轻量 BC 组;想训 Pi0/Pi0.5 这种 VLA,没有 A100 40 GB 会非常紧。没有本地 GPU 时,给训练命令加 --job.target=a10g-small 就能丢到 Hugging Face Jobs 上按秒计费跑。
四个常见卡点
| 现象 | 定位方法 | 处理 |
|---|---|---|
| OOM | 看日志峰值显存 | 降 batch、开梯度累积;smolvla 可 freeze_vision_encoder=true |
| 训练慢但没报错 | 查 step_s 里 update_s 占比 | 4 卡 accelerate launch --num_processes=4 约 4× 加速 |
| 学习率不衰减 | 看 LR 曲线是否一直贴着峰值 | --policy.scheduler_decay_steps≈--steps,短训时同步缩短 |
| 推理对不上数据 | rollout 画面乱动 | 相机名/分辨率/fps 必须与录数据时逐字一致 |
🔧 另外:模仿学习通常 5–10 个 epoch 就收敛,别按「几十万步」的直觉去估时长;单卡 RTX 4090 上 50 集数据的 ACT 大约 30–60 分钟。
想再深入:VLA 微调与多机部署指南
VLA 微调:从 Pi0 开始
VLA——你可以理解为给机器人装上「眼睛 + 耳朵 + 手」的联动系统:视觉编码器看场景、文本分词器听指令、动作头出电机指令。LeRobot 纯 PyTorch 实现了 Pi0、Pi0Fast、Pi0.5、GR00T N1.7、SmolVLA、XVLA、EO-1、MolmoAct2 等一批 VLA,外加 VLA-JEPA、FastWAM 等世界模型。微调 Pi0 时开 --policy.compile_model=true、--policy.gradient_checkpointing=true、--policy.dtype=bfloat16 能显著省显存。
LeRobot VLA 模型架构,展示视觉编码器、语言编码与动作解码到电机输出的完整链路
多机协同:异步推理
async_inference 把「策略推理」和「机器人执行」拆到不同进程:起一个 PolicyServer,多台机器人用 RobotClient 连上来,GPU 只跑一次前向、多端并行执行,降低多臂场景的推理压力。
强化学习分支
模仿学习之外,src/lerobot/rl/ 提供 HIL-SERL(人在环强化学习)、TDMPC 等,配合 SARM、TOPReward、Robometer 等奖励模型,可以做「人类演示 + 自主探索」的混合训练,路径见 docs/source/hilserl.mdx。
LeRobot 把数据格式、硬件接口、策略实现三件事收敛到同一套 PyTorch 工具链里,剩下的工作就是把你的任务数据喂进去。
- 仓库地址:
git clone https://gitcode.com/GitHub_Trending/le/lerobot - 官方文档:docs/source/(安装、SO-101 组装、策略选型都在这里)
- 命令速查:docs/source/cheat-sheet.mdx
- 第一个示例脚本:examples/tutorial/act/act_training_example.py
- 社区:README 中列出的 Discord 服务器
更多推荐



所有评论(0)