用 LeRobot 打通机械臂从数据到部署的完整实战指南

【免费下载链接】lerobot 🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning 【免费下载链接】lerobot 项目地址: https://gitcode.com/GitHub_Trending/le/lerobot

如果你手上有两台 SO-101 机械臂、一张 RTX 3060 和一个 Hugging Face 账号,用 LeRobot——一个 PyTorch 原生、硬件无关的机器人学习框架——今晚就能走完「录数据 → 训模型 → 上真机」的完整闭环。下面按踩坑顺序讲:怎么装、它替你藏了什么、最短闭环怎么走、GPU 怎么选、往深了走去哪找。

SO-101 机械臂在 LeRobot 框架下的双臂协作演示

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 多机器人控制与 VLA 策略推理演示画面

LeRobot 统一控制接口下多机器人策略推理的实时画面

GPU 选型与四个让训练卡住的参数

显存选型先看这张表

据 docs/source/hardware_guide.mdx 的量级估算(BS=8、AdamW,实际会随分辨率/IO 偏差 ±50%),VRAM 是第一道过滤器:

策略组代表策略峰值显存起步 GPU
轻量 BCact、vqbet、tdmpc~2–6 GBRTX 3060
Diffusiondiffusion、multi_task_dit~8–14 GBRTX 4070+
小 VLAsmolvla~10–16 GBRTX 4080+
大 VLApi0、pi05、xvla~24–40 GBA100 40 GB
多模态groot、eo1~24–40 GBA100 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 架构:从视觉/语言输入到电机动作的处理流程

LeRobot VLA 模型架构,展示视觉编码器、语言编码与动作解码到电机输出的完整链路

多机协同:异步推理

async_inference 把「策略推理」和「机器人执行」拆到不同进程:起一个 PolicyServer,多台机器人用 RobotClient 连上来,GPU 只跑一次前向、多端并行执行,降低多臂场景的推理压力。

强化学习分支

模仿学习之外,src/lerobot/rl/ 提供 HIL-SERL(人在环强化学习)、TDMPC 等,配合 SARM、TOPReward、Robometer 等奖励模型,可以做「人类演示 + 自主探索」的混合训练,路径见 docs/source/hilserl.mdx。

LeRobot 把数据格式、硬件接口、策略实现三件事收敛到同一套 PyTorch 工具链里,剩下的工作就是把你的任务数据喂进去。

【免费下载链接】lerobot 🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning 【免费下载链接】lerobot 项目地址: https://gitcode.com/GitHub_Trending/le/lerobot

Logo

聚焦RDK与具身智能,汇集机器人开发教程、开源案例和技术交流

更多推荐