人工智能

LeRobot VLA从零上手到完全掌握

阅读 — 次

vlalerobotSO-ARM101pi0act

文章目录

图片

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 大模型微调、社区活动、论文跟上研究前沿

最重要的四个结论:

  1. 入门第一策略选 ACT——官方文档明确写着 "Start with ACT, our recommended first policy"(docs 索引),仅需 ~2-6GB 显存,50 条数据、RTX 4090 上 30-60 分钟即可跑通(硬件指南)。
  2. 数据量起步线是 50 条 episode:官方建议"至少 50 条,每个摆放位置 10 条";SmolVLA 文档实测"25 条不够,50 条(5 个位置×10 条)才work"(SmolVLA 文档、il_robots 教程)。
  3. 新版 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)。
  4. 校准(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-rollout CLI,"把策略部署与数据录制解耦"——这是 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.pylerobot-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

校准流程与要点:

  1. 先把所有关节摆到行程中位,回车;然后把每个关节掰满全行程各一次,脚本记录 range 并生成 homing offset(官方内嵌 calibrate_so101 演示视频)。
  2. 校准的目的:让主/从臂在同一物理位置时读数一致;"这使在一台机器人上训练的网络能直接用在另一台上"——官方原话。
  3. 校准文件按 --robot.id 存盘:Cheat Sheet 警告"之后所有命令必须用与校准时相同的 id,LeRobot 靠它找校准文件"。
  4. 大多数情况每台设备只需校准一次;若出现腕转(wrist_roll)零点对不上、主臂校准报错,官方 issue 区的高频问题即在此(#3193 wrist_roll 校准损坏、#2387 so101Leader 校准问题),处置:重新单独校准该电机、检查舵盘安装。

验收标准(阶段 0)

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

验收标准(阶段 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):
    1. Hugging Face Jobs:lerobot-train ... --job.target=a10g-small(按秒计费;数据集会自动以私有仓库推上 Hub);hf jobs hardware 列配置;
    2. Google Colab:官方 ACT 训练 notebook / quickstart notebook;
    3. 借云 GPU(RunPod 等,参考硬件指南)。
  • 训练轮次直觉:模仿学习通常 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_leaderso101_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. 四大策略对比与入门顺序

ACTDiffusion PolicySmolVLApi0 / pi0.5
定位轻量模仿学习(CVAE+Transformer,动作分块)去噪扩散动作生成,平滑高维轨迹HF 自家轻量 VLA(SmolVLM2 骨干 + flow-matching 动作专家)Physical Intelligence 通用 VLA(PaliGemma 3B + flow-matching 动作专家)
参数量~几十 M~几十-百 M450M~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)


9. 常见新手坑与官方对策(全部有出处)

#坑官方建议/出处
1数据太少学不会起步 ≥50 条、每变体 10 条;25 条被实测判定"不够,效果差"(SmolVLA 文档、il_robots)
2fps 不匹配 / 慢模型卡顿录制统一 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 页)

  1. docs 索引(工作流总览+常见问题)
  2. SO-101 组装/校准 | Cheat Sheet(全部命令)
  3. il_robots 模仿学习教程(录数→训练→评测全流程)
  4. Compute & Hardware Guide(显存/时长选型)
  5. LeRobotDataset v3 | LeLab 浏览器 GUI(免 CLI 工作流)
  6. EnvHub 仿真 | HILSERL 强化学习 | SmolVLA

官方视频/课程

官方博客

论文

中文社区教程

社区


11. 参考来源(全链接汇总)

  1. LeRobot 官方文档索引 — https://huggingface.co/docs/lerobot/index
  2. SO-101 官方教程(组装/电机/校准)— https://huggingface.co/docs/lerobot/so101
  3. 模仿学习官方教程(il_robots)— https://huggingface.co/docs/lerobot/il_robots
  4. CLI Cheat Sheet — https://huggingface.co/docs/lerobot/cheat-sheet
  5. 安装指南 — https://huggingface.co/docs/lerobot/installation
  6. Compute & Hardware Guide — https://huggingface.co/docs/lerobot/hardware_guide
  7. LeRobot GitHub README — https://github.com/huggingface/lerobot
  8. GitHub Releases(v0.6.0/v0.6.1 变更)— https://github.com/huggingface/lerobot/releases
  9. examples 目录 — https://github.com/huggingface/lerobot/tree/main/examples
  10. quickstart notebook — https://github.com/huggingface/lerobot/blob/main/examples/notebooks/quickstart.ipynb
  11. 贡献指南 — https://huggingface.co/docs/lerobot/contributing
  12. TheRobotStudio/SO-ARM100(BOM/打印/SO-100 vs 101)— https://github.com/TheRobotStudio/SO-ARM100
  13. SmolVLA 发布博客 — https://huggingface.co/blog/smolvla
  14. SmolVLA 文档(微调命令)— https://huggingface.co/docs/lerobot/smolvla
  15. pi0 博客 — https://huggingface.co/blog/pi0
  16. LeRobot 数据集质量博客 — https://huggingface.co/blog/lerobot-datasets
  17. HIL-SERL 官方教程 — https://huggingface.co/docs/lerobot/hilserl
  18. EnvHub 文档 — https://huggingface.co/docs/lerobot/envhub
  19. lerobot 组织(Hub 模型/环境)— https://huggingface.co/lerobot
  20. LeRobot 标签数据集页 — https://huggingface.co/datasets?other=LeRobot
  21. svla_so101_pickplace 数据集 — https://huggingface.co/datasets/lerobot/svla_so101_pickplace
  22. Dataset Visualizer — https://huggingface.co/spaces/lerobot/visualize_dataset
  23. 🤗 Robotics Course — https://huggingface.co/learn/robotics-course/en/unit0/1
  24. Robot Learning: A Tutorial 论文 — https://huggingface.co/papers/2510.12403 / 交互版 https://huggingface.co/spaces/lerobot/robot-learning-tutorial
  25. LeRobot Worldwide Hackathon — https://huggingface.co/LeRobot-worldwide-hackathon
  26. Hackathon 获奖报道(Lightning AI)— https://lightning.ai/blog/lerobot-hackathon-winners
  27. ACT 论文 — https://arxiv.org/abs/2304.13705
  28. Diffusion Policy 论文 — https://arxiv.org/abs/2303.04137
  29. SmolVLA 论文 — https://huggingface.co/papers/2506.01844
  30. pi0 论文 — https://huggingface.co/papers/2410.24164
  31. HIL-SERL 论文 — https://arxiv.org/abs/2410.21845
  32. 常见问题 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
  33. 同济子豪兄教程(官方 README 收录)— https://github.com/TommyZihao / B站 https://space.bilibili.com/1900783 / 视频 https://www.bilibili.com/video/BV1jNQnYQEpA
  34. Seeed Studio 中文 Wiki — https://wiki.seeedstudio.com/cn/lerobot_so100m_new
  35. NVIDIA Sim-to-Real SO-101 课程 — https://docs.nvidia.com/learning/physical-ai/sim-to-real-so-101/latest/04-lerobot.html
  36. 社区博客:How I trained ACT on SO-101 — https://huggingface.co/blog/sherryxychen/train-act-on-so-101
  37. gym-pusht — https://github.com/huggingface/gym-pusht | gym-aloha — https://github.com/huggingface/gym-aloha
  38. LeRobot Discord — https://discord.gg/s3KuuzsPFb