LeRobot VLA从零上手到完全掌握
文章目录

0. 一页速览(TL;DR)
官方学习主线只有一句话:Teleoperate → Record → Train → Deploy(遥操作 → 录数据 → 训练 → 部署),这是 LeRobot 文档首页给出的官方工作流(docs 索引)。围绕它,本报告给出 阶段 0-5 的路线:
| 阶段 | 时间 | 内容 | 验收标志 |
|---|---|---|---|
| 阶段 0 | 第 1 周内 | 组装、装环境、setup-motors、calibrate | 从臂能被主臂平滑镜像控制 |
| 阶段 1 | 第 1-2 周 | 录数据集(≥50 条)、replay 回放、可视化 | replay 与录制动作一致 |
| 阶段 2 | 第 3-4 周 | 训练 ACT 并 rollout 自主执行 | 抓放任务成功率明显提升 |
| 阶段 3 | 第 2 个月 | Diffusion Policy / SmolVLA 微调,云训练 | 掌握多策略与泛化调参 |
| 阶段 4 | 第 3 个月 | 仿真(gym-pusht/LIBERO/MuJoCo)、读代码库、自定义硬件、HIL-SERL 强化学习 | 能贡献/修改代码库 |
| 阶段 5 | 第 3-6 个月 | pi0/pi05 大模型微调、社区活动、论文 | 跟上研究前沿 |
最重要的四个结论:
- 入门第一策略选 ACT——官方文档明确写着 "Start with ACT, our recommended first policy"(docs 索引),仅需 ~2-6GB 显存,50 条数据、RTX 4090 上 30-60 分钟即可跑通(硬件指南)。
- 数据量起步线是 50 条 episode:官方建议"至少 50 条,每个摆放位置 10 条";SmolVLA 文档实测"25 条不够,50 条(5 个位置×10 条)才work"(SmolVLA 文档、il_robots 教程)。
- 新版 CLI 与旧博客命令不同:2025 年中的博客(如 SmolVLA 发布文)还在写
python lerobot/scripts/train.py,现在的官方命令是lerobot-train/lerobot-record/lerobot-rollout等;且 v0.6.0 起pip install lerobot不再自带训练/数据依赖,需要pip install 'lerobot[core_scripts,training]'(Release notes)。 - 校准(calibrate)必须做,且所有命令中的
--robot.id必须一致:校准文件按 id 存储,id 变了等于没校准(Cheat Sheet)。校准质量直接决定训练后策略能否复现(SO-101 文档)。
1. 版本与 CLI 现状(2026 年 10 月,必读)
1.1 版本时间线(来源:GitHub Releases)
- v0.4.0(2025-10):LeRobotDataset v3 格式、streaming 数据集。
- v0.5.0(2026-03):要求 Python 3.12+。
- v0.5.1(2026-04):推理时加 policy 与录制分离(HiL/DAgger 采集);文档提示此版本用
lerobot-record跑推理。 - v0.6.0(2026-07,重大破坏性更新):
pip install lerobot默认轻量安装,训练/数据/硬件依赖改为 extras(lerobot[training]、lerobot[core_scripts]等)(安装文档);- 新增
lerobot-rolloutCLI,"把策略部署与数据录制解耦"——这是 v0.6+ 的推理命令,v0.5.1 用lerobot-record替代; - 参数改名:
--dataset.vcodec→--dataset.rgb_encoder.vcodec,eval_freq→env_eval_freq;RL 栈重构(sac→gaussian_actor)。
- v0.6.1(2026-08):
lerobot.types改名lerobot_types等修复。
1.2 新旧命令对照(关键!)
| 用途 | 旧写法(2024-2025 上半年博客/视频常见) | 现行写法(v0.5.x/v0.6.x) |
|---|---|---|
| 训练 | python lerobot/scripts/train.py --policy.type=act --dataset.repo_id=...(SmolVLA 博客原文) | lerobot-train --policy.type=act --dataset.repo_id=...(Cheat Sheet) |
| 推理/评测 | python lerobot/scripts/eval.py --pretrained_policy.path=...(pi0 博客原文) | lerobot-rollout(真机)/ lerobot-eval(仿真基准)(Cheat Sheet) |
| 录制 | python lerobot/scripts/control_robot.py | lerobot-record(il_robots 教程) |
看到老教程里
python lerobot/scripts/xxx.py一律按上表替换;反之,如果想逐字复现 2025 年中的 SmolVLA 博客命令,需回退pip install lerobot==0.5.1之前的源码版。
1.3 全部官方 CLI 工具(Cheat Sheet + README)
lerobot-info(自检安装)、lerobot-find-port(找串口)、lerobot-find-cameras(找相机)、lerobot-setup-motors(设置电机 ID/波特率)、lerobot-calibrate(校准)、lerobot-teleoperate(遥操作)、lerobot-record(录数据)、lerobot-replay(回放数据)、lerobot-train(训练)、lerobot-rollout(真机推理)、lerobot-eval(仿真评测)、lerobot-edit-dataset/lerobot-dataset-viz(数据集编辑/可视化)。
2. 阶段 0:组装与点亮(第 1 周)
目标
完成 SO-101 双臂组装、电机配置、校准,并用主臂平滑控制从臂。
2.1 组装(SO-101 官方文档)
- 零件清单(BOM)与 3D 打印指南在 TheRobotStudio/SO-ARM100 仓库 README(PLA+,0.4mm 喷嘴/0.2mm 层高或 0.6/0.4,15% 填充;先打校准量规件验证打印机精度)。双臂全套物料约 230 美元,单从臂约 122 美元;也可直接买 Seeed Studio 等整机套件。
- 从臂 = 6 个 STS3215 电机(1/345 减速);主臂用三种减速比混搭(底盘/肩抬 1/191 与 1/345、肘 1/191、腕/夹爪 1/147),以便"既撑得住自重、又推得动"——这是 SO-101 主臂的手感设计(SO-101 文档电机表)。
- 官方文档内嵌每一步的组装视频(Joint1-5、Gripper、Leader)与"设电机 ID"视频、校准视频,照着敲即可。
2.2 安装环境(安装文档)
# 官方推荐 conda(miniforge),Python 3.12(文档在 macOS/Linux 验证;Windows 原生 pip 亦可,WSL 需额外装 evdev)
conda create -y -n lerobot python=3.12
conda activate lerobot
# 视频解码需要 ffmpeg(TorchCodec);Windows+PyTorch<2.8 会自动回退 pyav,可跳过 ffmpeg
conda install ffmpeg -c conda-forge # 若报 libsvtav1 问题,改装 ffmpeg=7.1.1
# PyPI 安装(推荐新手;v0.6.0 起必须用 extras 组合)
pip install 'lerobot[core_scripts,training]' # 录制+回放+校准 与 训练
pip install 'lerobot[feetech]' # SO-100/SO-101 的 Feetech 电机 SDK
# 或源码安装(要读代码/贡献时用)
git clone https://github.com/huggingface/lerobot.git && cd lerobot
pip install -e ".[all]"
lerobot-info # 自检
WSL(Windows 子系统)注意:官方文档明确要求额外安装
evdev(conda install evdev -c conda-forge或sudo apt install libevdev-dev && uv pip install evdev)。文档中的pip install -e ".[feetech]"写法仅适用于源码仓库内。
2.3 找串口 + 设电机 ID(SO-101 文档)
lerobot-find-port # 按提示拔插 USB,识别主/从臂端口(文档在 macOS/Linux 验证:/dev/tty.usbmodem*、/dev/ttyACM*)
# 从臂:逐个(只接一个电机!)连板子设 ID,从夹爪=6 逆推到肩转=1
lerobot-setup-motors --robot.type=so101_follower --robot.port=/dev/ttyACM0
# 主臂:
lerobot-setup-motors --teleop.type=so101_leader --teleop.port=/dev/ttyACM1
要点(全部来自官方文档):
- 电机出厂默认 ID 都是 1,必须逐个单独接线设置;ID 写入 EEPROM 只需做一次。
- 从臂 ID 约定:
1=shoulder_pan, 2=shoulder_lift, 3=elbow_flex, 4=wrist_flex, 5=wrist_roll, 6=gripper。 - Waveshare 控制板跳线要在
B通道(USB);报错先查电源/USB/三-pin 线三处。
2.4 校准(SO-101 文档 + Cheat Sheet)
lerobot-calibrate --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=my_follower_arm
lerobot-calibrate --teleop.type=so101_leader --teleop.port=/dev/ttyACM1 --teleop.id=my_leader_arm
校准流程与要点:
- 先把所有关节摆到行程中位,回车;然后把每个关节掰满全行程各一次,脚本记录 range 并生成 homing offset(官方内嵌 calibrate_so101 演示视频)。
- 校准的目的:让主/从臂在同一物理位置时读数一致;"这使在一台机器人上训练的网络能直接用在另一台上"——官方原话。
- 校准文件按
--robot.id存盘:Cheat Sheet 警告"之后所有命令必须用与校准时相同的 id,LeRobot 靠它找校准文件"。 - 大多数情况每台设备只需校准一次;若出现腕转(wrist_roll)零点对不上、主臂校准报错,官方 issue 区的高频问题即在此(#3193 wrist_roll 校准损坏、#2387 so101Leader 校准问题),处置:重新单独校准该电机、检查舵盘安装。
验收标准(阶段 0)
lerobot-teleoperate双臂镜像流畅无报警(il_robots 教程命令):
lerobot-teleoperate \
--robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=my_follower_arm \
--teleop.type=so101_leader --teleop.port=/dev/ttyACM1 --teleop.id=my_leader_arm
- teleoperate 会自动检测缺失校准并引导补校准(官方行为说明)。
3. 阶段 1:遥操作 + 录制第一批数据(第 1-2 周)
目标
理解 LeRobotDataset 格式,录出一条合格的 ≥50 episode 数据集,并用 replay 验证机械可重复性。
3.1 带相机遥操作(先看 Rerun 可视化)
lerobot-teleoperate \
--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 \
--display_data=true
(命令与相机字典语法出自 Cheat Sheet;找相机用 lerobot-find-cameras,测试帧存到 lerobot/outputs/captured_images。)
相机数量与机位:官方教程惯例是 2 路——一个 top(俯视全局)+ 一个 wrist(腕部);好数据集清单要求"最好两个视角、主臂不出镜、背景静止、光照稳定、至少 480×640"(数据集质量官方博客)。
3.2 录制数据集
hf auth login # 先登录 HF(需要 write token,录完自动上传 Hub)
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=50 \
--dataset.single_task="put the red brick in a bowl" \
--dataset.streaming_encoding=true \
--display_data=true
录制环节官方参数与建议(出处:il_robots + Cheat Sheet + SmolVLA 文档):
- fps:30(SO-101 社区/官方数据集标准;HIL-SERL 强化学习用 10fps,见 hilserl 文档)。
- episode 数:起步 ≥50。il_robots 原话:"We suggest recording at least 50 episodes, with 10 episodes per location"(即 5 个不同抓取位置 × 10 条);SmolVLA 文档补充:"我们试过 25 条,不够,效果差"。
- episode 时长
--dataset.episode_time_s=60(默认 60s)、--dataset.reset_time_s=10(演示完给从臂归位的时间)、--dataset.num_episodes默认 50。 - 录制中键盘控制:
→/n提前结束本条、←/r作废重录、ESC/q结束并上传(支持 Windows 桌面;Linux Wayland/SSH 下终端按键也可)。 - 任务描述
single_task要具体(如 "Grab the black cube" 而不是 "task1"),官方建议 25-50 字符、明确目标(数据集博客)。 - 数据存本地
~/.cache/huggingface/lerobot/{repo-id},录完自动推送到https://huggingface.co/datasets/${HF_USER}/xxx并打上LeRobot标签;不想上传加--dataset.push_to_hub=False。断点续录:同一命令加--resume=true(此时 num_episodes 是追加条数,还要指定--dataset.root)。 - v0.6 编码参数改名:
--dataset.rgb_encoder.vcodec=h264(旧写法--dataset.vcodec已弃用)。
好数据自检(官方 checklist 精选):物体在相机里看得见——"如果你只看相机画面也能自己完成这个任务,数据才合格"(il_robots 原话);保持机位固定、抓取手法一致;不要一上来加太多变化,"Avoid adding too much variation too quickly, as it may hinder your results"。
3.3 回放与可视化
# 回放第 0 条 episode,验证机械重复性(排除标定/抖动问题)
lerobot-replay \
--robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=my_follower_arm \
--dataset.repo_id=${HF_USER}/so101_dataset_test --dataset.episode=0
- 在线可视化(无需安装):把 repo_id 粘进 lerobot/visualize_dataset Space,可逐帧看相机+状态+动作(官方示例:lerobot/svla_so101_pickplace episode_0)。
验收标准(阶段 1)
- 数据集在 Hub/本地可打开,视频与关节状态对齐;
lerobot-replay复现动作与录制基本一致(不一致 → 先查校准与装配,别急着训练);- 至少 50 条、每类摆放位置 10 条、任务描述清晰。
4. 阶段 2:训练第一个策略(ACT)并自主执行(第 3-4 周)
4.1 为什么先 ACT
- 官方文档钦定入门策略:"Start with ACT, our recommended first policy"(docs 索引)。
- 硬件门槛最低:峰值显存 ~2-6GB(batch 8),笔记本 GPU(RTX 3060)即可;50 episode 数据在 RTX 4090 上 ~30-60 分钟、L4/A10G 上 1-2 小时(Compute & Hardware Guide)。
- 训练时会自动适配你数据集里的电机数、动作维度与相机名(il_robots 说明:"this policy will automatically adapt to the number of motor states, motor actions and cameras of your robot")。
4.2 训练命令
lerobot-train \
--dataset.repo_id=${HF_USER}/so101_dataset_test \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--wandb.enable=true \
--policy.repo_id=${HF_USER}/policy_test \
--steps=20000
(Cheat Sheet 原样命令;policy.type 可选 act/diffusion/smolvla/pi05 等;policy.device 支持 cuda/mps(Apple)/cpu。)
- 断点续训:
lerobot-train --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json --resume=true(也接受 Hub repo id)。 - 没有本地 GPU 的三条官方出路(il_robots):
- Hugging Face Jobs:
lerobot-train ... --job.target=a10g-small(按秒计费;数据集会自动以私有仓库推上 Hub);hf jobs hardware列配置; - Google Colab:官方 ACT 训练 notebook / quickstart notebook;
- 借云 GPU(RunPod 等,参考硬件指南)。
- Hugging Face Jobs:
- 训练轮次直觉:模仿学习通常 5-10 个 epoch 收敛,不是堆几十万步;缩步数时记得同步缩 LR 衰减
--policy.scheduler_decay_steps≈--steps(硬件指南)。
4.3 用训练好的策略自主执行
v0.6.x 用 lerobot-rollout(Cheat Sheet):
lerobot-rollout \
--strategy.type=base \
--policy.path=${HF_USER}/policy_test \
--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
要点:
- 相机配置必须与录数据时一致(名称、数量、分辨率——Cheat Sheet 原文:"Your cameras configuration needs to match what was used when collecting the dataset")。
--strategy.type五种:base(纯执行)、sentry(持续录制并自动上传,用于规模化评测)、highlight(按键保存精彩片段)、dagger(人在环数据采集)、episodic。- 慢速大模型(SmolVLA/pi0)可加
--inference.type=rtc(Real-Time Chunking)平滑执行。 - v0.5.1 用户:推理仍用
lerobot-record加载 policy(官方提示链接:il_robots v0.5.1)。
验收标准(阶段 2)
- 训练 loss 下降、W&B 曲线正常;rollout 能稳定完成抓放(可 10 次一统计成功率);
- 若"训练完机械臂乱动/不抓"→ 见第 9 章坑 7(官方 issue #2213 即此类:多为数据质量/校准不一致/相机机位变动)。
5. SO-ARM100 vs SO-ARM101:怎么选、差在哪
来源:TheRobotStudio/SO-ARM100 README + SO-101 文档:
| 维度 | SO-ARM100(旧) | SO-ARM101(现行旗舰) |
|---|---|---|
| 状态 | 文档已标 deprecated(SO100.md) | 官方推荐新装机首选(README 原话) |
| 装配 | 需拆减速齿轮 | "easier to assemble (no gear removal)" 免拆齿轮 |
| 布线 | 旧布线 | improved wiring |
| 主臂电机 | — | 更新过,且三档减速比混搭(1/191、1/345、1/147),可平滑跟随从臂(HILSERL 文档:"SO101 leader has reduced gears ... taking over is much smoother than the gearless SO100") |
| LeRobot 类型名 | so100_follower / so100_leader | so101_follower / so101_leader |
| 电机版本 | 同 | 从臂 STS3215 有 7.4V(16.5kg.cm)与 12V(30kg.cm)两版,12V 版必须配 12V 5A+ 电源(README 警告) |
结论:已有 SO-100 完全能跟完本路线(把命令里 so101_* 换成 so100_* 即可,官方教程 v0.5.1 时代即以 so100 演示);新购/重装优先 SO-101。两者的数据集/校准不通用,跨臂迁移正是"校准让网络可跨机器人工作"要解决的问题。
6. 官方预训练模型与数据集(先用社区数据,再录自己的)
6.1 没有机械臂也能先跑通训练(官方 "No hardware yet" 路线,来源:docs 索引)
# 用社区数据集直接训练(README 示例)
lerobot-train --policy.type=act --dataset.repo_id=lerobot/aloha_mobile_cabinet
# 评测预训练策略(README 示例,LIBERO 仿真基准)
lerobot-eval --policy.path=lerobot/pi0_libero_finetuned --env.type=libero --env.task=libero_object --eval.n_episodes=10
6.2 lerobot 组织在 Hub 上的关键资产(来源:huggingface.co/lerobot)
- SmolVLA:
lerobot/smolvla_base(450M,下载量最高的旗舰)及smolvla_libero、smolvla_robotwin、smolvla_metaworld、smolvla_robocasa等微调版。 - pi0 系列:
lerobot/pi0、pi0_base、pi0_libero_finetuned;pi0.5:pi05_base等;pi0-FAST:pi0fast-base。 - XVLA:
xvla-base(跨本体)。 - 仿真环境包(EnvHub):lerobot/so101-tabletop-mujoco(SO-101 MuJoCo 抓方块)、lerobot/so101-tabletop-isaac、
lerobot/cartpole-env(EnvHub 文档)。
6.3 关键数据集(LeRobot 标签页:huggingface.co/datasets?other=LeRobot)
- lerobot/svla_so101_pickplace:50 条 episode 的 SO-100 抓放数据,SmolVLA 论文所用,官方用它做入门参照(SmolVLA 文档链接其可视化)。SO-100 系还有
svla_so100_stacking、svla_so100_sorting(lerobot 组织页)。 - 大规模社区数据:cadene/droid(92.2k episodes)、IPEC-COMMUNITY/language_table_lerobot(442k)等;总量:Hub 上带 LeRobot 标签的数据集数以万计(该标签页显示 8 万+,含大量个人测试集)。
- 建议顺序:第 1 个月先用
lerobot/svla_so101_pickplace或lerobot/pusht/lerobot/aloha_mobile_cabinet这类标准数据集把lerobot-train全流程跑通(不依赖机械臂、验证 GPU 环境);第 2 个月起再换自己录的数据。
7. 四大策略对比与入门顺序
| ACT | Diffusion Policy | SmolVLA | pi0 / pi0.5 | |
|---|---|---|---|---|
| 定位 | 轻量模仿学习(CVAE+Transformer,动作分块) | 去噪扩散动作生成,平滑高维轨迹 | HF 自家轻量 VLA(SmolVLM2 骨干 + flow-matching 动作专家) | Physical Intelligence 通用 VLA(PaliGemma 3B + flow-matching 动作专家) |
| 参数量 | ~几十 M | ~几十-百 M | 450M | ~3B(论文口径,见 pi0 论文) |
| 峰值显存(BS8) | ~2-6GB | ~8-14GB | ~10-16GB(小 VLA 组) | ~24-40GB(A100 40GB+,24GB 只够 BS1)(硬件指南) |
| 训练时长参考(50ep 数据) | 4090 上 30-60 分钟 | 4090 上 2-4 小时 | A100 上 ~4 小时/20k 步(SmolVLA 文档);L4/A10G 3-6 小时 | A100 40GB 上 4-8 小时(BS4) |
| 数据需求 | 50 条起步 | 50 条起步 | 微调必须:--policy.path=lerobot/smolvla_base + 自己的 ≥50 条;从零训练需 ~487 个社区数据集/10M 帧(SmolVLA 博客) | Jax→PyTorch 转换有损,官方明确建议微调到自己的环境再用(pi0 博客) |
| 入门性价比 | ★★★★★(首选) | ★★★(ACT 之后练) | ★★★★(第二个月主力;可下语言指令,泛化更好) | ★★(需要大显存或云 GPU,阶段 5 再碰) |
官方推荐的入门顺序:ACT(文档钦点第一策略)→ Diffusion Policy(同属轻量模仿学习,练去噪超参直觉)→ SmolVLA(第一次碰 VLA:显存友好、支持自然语言任务、有完整微调文档)→ pi0/pi0.5(阶段 5,配 A100 或 HF Jobs)。
SmolVLA 微调命令(现行 CLI 版,改写自 SmolVLA 文档;注意博客原版是旧 CLI):
lerobot-train \
--policy.path=lerobot/smolvla_base \
--dataset.repo_id=${HF_USER}/mydataset \
--batch_size=64 --steps=20000 \
--output_dir=outputs/train/my_smolvla --job_name=my_smolvla \
--policy.device=cuda --wandb.enable=true
8. 进阶路线(第 2-6 个月)
8.1 读懂代码库结构
src/lerobot/下核心模块:robots/(硬件接口,Robot类解耦控制与硬件)、cameras/、teleoperators/、policies/(act、diffusion、smolvla、pi0 等)、datasets/(LeRobotDataset)、rl/(HIL-SERL)、scripts/(各 CLI 入口)——见 README 特性清单与 贡献指南。examples/目录(github.com/huggingface/lerobot/tree/main/examples)按主题分:dataset/(加载/创建/编辑数据集)、training/、port_datasets/(他格式转 LeRobot)、notebooks/(quickstart.ipynb:填一次机器人配置自动生成全部命令,官方强烈推荐)、rtc/(慢模型推理)、isaac_teleop_to_so101、phone_to_so100、remote_inference、lekiwi等。- 自定义硬件:第三方生态走插件包约定
lerobot_robot_*/lerobot_teleoperator_*/lerobot_camera_*,pip 装上即被发现(README);自带硬件照 贡献指南 fork →pre-commit→pytest→ PR 流程。 - 自定义相机:见 Cameras 指南(OpenCV/Intel RealSense 原生支持,RealSense 支持
use_depth: true深度流录制,Cheat Sheet 有完整示例)。
8.2 仿真环境
- 官方内置 sim:gym-pusht 与 gym-aloha(
pip install -e ".[aloha]"/".[pusht]",安装文档)。 - 基准套件(v0.6.0 新增):LIBERO、LIBERO-plus、Meta-World、RoboCasa365、RoboTwin 2.0、VLABench、RoboMME(Releases),配合
lerobot-eval使用(README 有 LIBERO 示例)。 - EnvHub:仿真环境做成 Hub 仓库一键加载(
make_env("lerobot/so101-tabletop-mujoco", trust_remote_code=True)),自己写env.py暴露make_env()即可发布(EnvHub 文档)。SO-101 专用:MuJoCo 与 Isaac Sim 桌面抓取环境各一个(模型列表)。
8.3 强化学习:HIL-SERL(人在环采样高效 RL)
来源:HILSERL 官方教程,论文 arXiv:2410.21845:
- 流程:录少量演示 →(可选)训视觉奖励分类器 →
lerobot-find-joint-limits定工作空间 → actor/learner 双进程 gRPC 训练(learner 跑 SAC 梯度更新,actor 在真机探索,人随时按键接管纠正); - 安装
pip install -e ".[hilserl]";fps 用 10;官方称"几小时内在真机训出接近满分成功率的策略"; - 实用建议:任务选 5-10 秒能完成的短时程;端-effector 空间比关节空间好学;干预率应随训练逐步下降(文档有判读图)。
8.4 微调 pi0 / openpi
- HF 版:
pip install 'lerobot[pi]'后lerobot-train --policy.path=lerobot/pi0 --dataset.repo_id=...(现行 CLI;pi0 博客 中的python lerobot/scripts/train.py为旧版写法)。原始 Jax 实现在 Physical Intelligence 的 openpi 仓库(博客提及)。 - 没有 40GB 级显存就上 HF Jobs(
--job.target=a100-large)(硬件指南)。
8.5 社区与赛事(2025-2026)
- LeRobot Discord(官方答疑主阵地):discord.gg/s3KuuzsPFb(文档)。
- LeRobot Worldwide Hackathon(2025-06-13~15):全球 100+ 本地场、48 小时,以 SO-100/SO-101 为指定硬件,官方设新手教程;主站 huggingface.co/LeRobot-worldwide-hackathon,获奖案例见 Lightning AI 博客(冠军作品:叠 T 恤+分药)。
- 后续赛事/挑战以 Discord 与 lerobot 组织页 公告为准(本次调研未检索到名为 "World Cup" 的官方赛事;2025 年社区活动以 Worldwide Hackathon 为主,勿轻信二手转述)。
- 免费官方课程:🤗 Robotics Course,基于 LeRobot 团队教程论文 "Robot Learning: A Tutorial"(arXiv:2510.12403),配套 Space 交互版 与 源码——系统补理论的最佳入口。
9. 常见新手坑与官方对策(全部有出处)
| # | 坑 | 官方建议/出处 |
|---|---|---|
| 1 | 数据太少学不会 | 起步 ≥50 条、每变体 10 条;25 条被实测判定"不够,效果差"(SmolVLA 文档、il_robots) |
| 2 | fps 不匹配 / 慢模型卡顿 | 录制统一 30fps;推理相机 fps 与录制一致;慢 VLA(SmolVLA/pi0)用 --inference.type=rtc 平滑执行(Cheat Sheet) |
| 3 | 相机画面糊/曝光差 | "光照比分辨率重要";先跑 lerobot-find-cameras 验帧;好数据要求机位固定、主臂出镜会引入噪声(docs 常见问题、Cameras 指南、数据集博客) |
| 4 | 校准不一致 | 所有命令复用同一个 --robot.id;腕转(wrist_roll)零点漂移是高频 bug(#3193),主臂校准失败查 #2387;建议用 homing offset 缓解角度回绕(#3587) |
| 5 | 从臂抖动/断连/堵转 | 查电源(12V 舵机必须 12V 5A+,7.4V 别混用,SO-ARM100 README);Waveshare 板跳线置 B 通道(SO-101 文档);断连案例 #3131、舵机异常 #2819 |
| 6 | 训练过拟合、换位置就废 | 别过早加变化;先固定机位与手法练"单位置成功",再逐步加位置/手法多样性(il_robots 官方原话);泛化本质是数据现象(数据集博客) |
| 7 | 训完策略乱动/不抓(#2213) | 排查顺序:数据质量 → replay 是否复现(排除校准)→ 推理相机配置是否与录制完全一致(Cheat Sheet) |
| 8 | 安装报错(cmake/ffmpeg/CUDA) | 见安装文档 Troubleshooting:缺 cmake/build-essential/ffmpeg 头文件;TorchCodec 平台限制(macOS Intel/ARM Linux/旧版 Windows 回退 pyav);conda 装 ffmpeg=7.1.1 解编码器缺失 |
| 9 | 任务描述乱写 | "task1"、"Hold" 这类标注会让数据不可用;写 25-50 字符具体指令(数据集博客) |
| 10 | 旧教程命令跑不动新版 | python lerobot/scripts/train.py → lerobot-train;v0.6.0 起需 extras 安装、--dataset.vcodec 改名(Releases、安装文档) |
10. 学习资料总清单
官方文档(核心 6 页)
- docs 索引(工作流总览+常见问题)
- SO-101 组装/校准 | Cheat Sheet(全部命令)
- il_robots 模仿学习教程(录数→训练→评测全流程)
- Compute & Hardware Guide(显存/时长选型)
- LeRobotDataset v3 | LeLab 浏览器 GUI(免 CLI 工作流)
- EnvHub 仿真 | HILSERL 强化学习 | SmolVLA
官方视频/课程
- SO-101 文档内嵌官方视频:组装(每关节)、设电机 ID、校准演示
- 🤗 Robotics Course(免费官方课程),配套 论文版教程 arXiv:2510.12403
- quickstart.ipynb(配置一次生成全部命令) + SmolVLA 官方 Colab
- Dataset Visualizer Space(先"看"别人的数据)
官方博客
- SmolVLA 发布文(2025-06) | pi0 移植文 | LeRobot 数据集质量指南(2025-05)
- 社区实战:How I trained ACT on SO-101(sherryxychen)
论文
- ACT:Learning Fine-Grained Bimanual Manipulation with Low-Cost Hardware(Zhao et al., RSS 2023)
- Diffusion Policy:arXiv:2303.04137(Chi et al., RSS 2023)
- SmolVLA:arXiv:2506.01844 | pi0:arXiv:2410.24164 | HIL-SERL:arXiv:2410.21845
- 教程综述:Robot Learning: A Tutorial, arXiv:2510.12403;LeRobot 系统论文:ICLR 2026, arXiv:2602.22818(README 引用)
中文社区教程
- 同济子豪兄《LeRobot+SO-ARM101 中文教程》:被 LeRobot 官方 README "Chinese Tutorials" 收录("Detailed doc for assembling, teleoperate, dataset, train, deploy");作者主页 github.com/TommyZihao、B 站空间、组装+模仿学习实战视频(BV1jNQnYQEpA)。时效性注意:其命令基线为 2025 年版本,与现行 v0.6 CLI 有差异,看思路、命令以上文官方文档为准。
- Seeed Studio 中文 Wiki:SO-ARM100/101 入门(套件厂商官方教程,含视频,持续更新到 2026-03)
- NVIDIA 免费课程:Physical AI - Sim-to-Real SO-101(含 LeRobot 章)
社区
- LeRobot Discord(官方答疑,文档多页指向) | GitHub Issues | LeRobot Worldwide Hackathon 主站
11. 参考来源(全链接汇总)
- LeRobot 官方文档索引 — https://huggingface.co/docs/lerobot/index
- SO-101 官方教程(组装/电机/校准)— https://huggingface.co/docs/lerobot/so101
- 模仿学习官方教程(il_robots)— https://huggingface.co/docs/lerobot/il_robots
- CLI Cheat Sheet — https://huggingface.co/docs/lerobot/cheat-sheet
- 安装指南 — https://huggingface.co/docs/lerobot/installation
- Compute & Hardware Guide — https://huggingface.co/docs/lerobot/hardware_guide
- LeRobot GitHub README — https://github.com/huggingface/lerobot
- GitHub Releases(v0.6.0/v0.6.1 变更)— https://github.com/huggingface/lerobot/releases
- examples 目录 — https://github.com/huggingface/lerobot/tree/main/examples
- quickstart notebook — https://github.com/huggingface/lerobot/blob/main/examples/notebooks/quickstart.ipynb
- 贡献指南 — https://huggingface.co/docs/lerobot/contributing
- TheRobotStudio/SO-ARM100(BOM/打印/SO-100 vs 101)— https://github.com/TheRobotStudio/SO-ARM100
- SmolVLA 发布博客 — https://huggingface.co/blog/smolvla
- SmolVLA 文档(微调命令)— https://huggingface.co/docs/lerobot/smolvla
- pi0 博客 — https://huggingface.co/blog/pi0
- LeRobot 数据集质量博客 — https://huggingface.co/blog/lerobot-datasets
- HIL-SERL 官方教程 — https://huggingface.co/docs/lerobot/hilserl
- EnvHub 文档 — https://huggingface.co/docs/lerobot/envhub
- lerobot 组织(Hub 模型/环境)— https://huggingface.co/lerobot
- LeRobot 标签数据集页 — https://huggingface.co/datasets?other=LeRobot
- svla_so101_pickplace 数据集 — https://huggingface.co/datasets/lerobot/svla_so101_pickplace
- Dataset Visualizer — https://huggingface.co/spaces/lerobot/visualize_dataset
- 🤗 Robotics Course — https://huggingface.co/learn/robotics-course/en/unit0/1
- Robot Learning: A Tutorial 论文 — https://huggingface.co/papers/2510.12403 / 交互版 https://huggingface.co/spaces/lerobot/robot-learning-tutorial
- LeRobot Worldwide Hackathon — https://huggingface.co/LeRobot-worldwide-hackathon
- Hackathon 获奖报道(Lightning AI)— https://lightning.ai/blog/lerobot-hackathon-winners
- ACT 论文 — https://arxiv.org/abs/2304.13705
- Diffusion Policy 论文 — https://arxiv.org/abs/2303.04137
- SmolVLA 论文 — https://huggingface.co/papers/2506.01844
- pi0 论文 — https://huggingface.co/papers/2410.24164
- HIL-SERL 论文 — https://arxiv.org/abs/2410.21845
- 常见问题 issue:#3193 https://github.com/huggingface/lerobot/issues/3193 、#2387 https://github.com/huggingface/lerobot/issues/2387 、#2213 https://github.com/huggingface/lerobot/issues/2213 、#3587 https://github.com/huggingface/lerobot/issues/3587 、#3131 https://github.com/huggingface/lerobot/issues/3131 、#2819 https://github.com/huggingface/lerobot/issues/2819
- 同济子豪兄教程(官方 README 收录)— https://github.com/TommyZihao / B站 https://space.bilibili.com/1900783 / 视频 https://www.bilibili.com/video/BV1jNQnYQEpA
- Seeed Studio 中文 Wiki — https://wiki.seeedstudio.com/cn/lerobot_so100m_new
- NVIDIA Sim-to-Real SO-101 课程 — https://docs.nvidia.com/learning/physical-ai/sim-to-real-so-101/latest/04-lerobot.html
- 社区博客:How I trained ACT on SO-101 — https://huggingface.co/blog/sherryxychen/train-act-on-so-101
- gym-pusht — https://github.com/huggingface/gym-pusht | gym-aloha — https://github.com/huggingface/gym-aloha
- LeRobot Discord — https://discord.gg/s3KuuzsPFb