LeRobot SO-101 实操指南：从装机、校准到采集数据与训练策略的完整工作流

2026-09-10 12:52:45作者：滕妙奇

本文是一份基于 LeRobot 官方《AGENT_GUIDE.md》整理并对照仓库源码深度验证的实战手册，面向所有想在真实机械臂上跑通"遥操作采集 → 训练策略 → 真机评估"闭环的开发者与 AI Agent。你将掌握 SO-101 双臂从找端口、设电机 ID、校准到采集数据集、选择策略、规划训练时长、评估结果的一整套可复制命令，并理解每一步背后的源码级原理。

1. 先问清楚需求：Agent 与用户的强制前置沟通

《AGENT_GUIDE.md》开篇明确了一条对 AI Agent 的强制约定：在给出任何命令之前，必须先向用户确认以下信息，并等待回答：

目标是什么——例如"教会 SO-101 叠衣服""在现有 HF 数据集上训练策略""贡献一个 PR""理解代码库"；
有什么硬件——机械臂（无 / SO-100 / SO-101 / Koch / LeKiwi / Reachy 等）、遥操作方式（leader 臂 / 手机 / 键盘 / 手柄 / 无）、相机数量、分辨率、固定还是移动；
在什么机器上训练——GPU 型号与显存（如 "laptop 3060 6 GB"、"RTX 4090 24 GB"、"A100 80 GB"、"仅 CPU"）、操作系统（macOS / Linux / Windows）；
技能水平与时间预算——首次接触 / 有一定 ML 基础 / 经验丰富；几小时、几天还是一个周末；
是否已有数据集——有（HF repo id？）/ 没有 / 想自己录制；
当前最需要帮助的具体一步。

只有在拿到这些答案后，才能给出具体路径；遇到含糊之处应再次提问而非猜测，并始终偏向用户硬件与目标下"最简单可行"的方案。从仓库看，这条约定的精神与 AGENTS.md 的分工一致：AGENTS.md 面向开发者/贡献者，而 AGENT_GUIDE.md 面向终端用户提供可复制的用户侧指引。

2. LeRobot 60 秒速览：统一抽象下的完整栈

LeRobot = 数据集 + 策略 + 环境 + 机械臂控制，由一组精简但强大的抽象统一起来：

LeRobotDataset —— 按 episode 组织的数据集（视频或图像 + 动作 + 状态），可从 Hugging Face Hub 或本地磁盘加载；
策略（ACT、Diffusion、SmolVLA、π0、π0.5、Wall-X、X-VLA、VQ-BeT、TD-MPC 等）—— 全部继承自 PreTrainedPolicy，可在 Hub 上推送/拉取；
Processors —— 数据集 → 策略 → 机械臂之间的小型可组合变换；
Envs（仿真）与 Robots（真实） —— 遵循相同的动作/观测契约，代码可以无缝互换；
CLI —— lerobot-record、lerobot-train、lerobot-eval、lerobot-teleoperate、lerobot-calibrate、lerobot-find-port、lerobot-setup-motors、lerobot-replay。

在源码层面，这些 CLI 入口位于 src/lerobot/scripts/，并在 pyproject.toml 的 [project.scripts] 中映射；策略全部落在 src/lerobot/policies/，每个策略一个子目录，统一继承 pretrained.py 中的 PreTrainedPolicy。更完整的仓库架构见 AGENTS.md。

3. 三条快速上手路径（按场景选择）

路径 A——"我有 SO-101，想要第一个训练好的策略"：按第 4 节（SO-101 全流程）→ 第 5 节（数据采集技巧）→ 第 6 节（选策略，通常用 ACT）→ 第 7 节（训练时长）→ 第 8 节（评估）的顺序推进。
路径 B——"没有硬件，想用现成数据集训练"：跳过第 4 节，在第 6 节选策略、第 7 节定时长，然后按 4.9 用 Hub 的 --dataset.repo_id 加 --env.type（用于评估）运行 lerobot-train，最后按第 8 节评估。
路径 C——"只想理解代码库"：读第 2 节，再看 AGENTS.md 的 Architecture 章节，然后打开 src/lerobot/policies/act/ 与 src/lerobot/datasets/lerobot_dataset.py 作为典型范例。

4. SO-101 端到端速查表

完整硬件细节见 docs/source/so101.mdx 与 docs/source/il_robots.mdx。以下按顺序给出最小命令集，执行前务必确认双臂已装配完成并已上电。

4.1 安装

# uv（推荐，参见 AGENTS.md 和 CLAUDE.md）
uv sync --locked --extra feetech          # SO-100/SO-101 电机栈
# uv sync --locked --extra all            # 全部依赖
# uv sync --locked --extra smolvla        # 增加 SmolVLA 依赖

# pip（备选，例如不从源码安装时）
# pip install 'lerobot[feetech]'
# pip install 'lerobot[all]'
# pip install 'lerobot[smolvla]'

git lfs install && git lfs pull
hf auth login                             # 推送数据集/策略到 Hub 时必需

feetech extra 对应 SO-100/SO-101 使用的 Feetech STS3215 电机总线栈；SO-101 的硬件支持代码位于 src/lerobot/robots/so_follower/（跟随臂）与 src/lerobot/teleoperators/so_leader/（主控臂）。

4.2 查找 USB 端口（每只臂执行一次，按提示拔线）

lerobot-find-port

macOS 输出形如 /dev/tty.usbmodem...；Linux 输出形如 /dev/ttyACM0（可能需要 sudo chmod 666 /dev/ttyACM0 授权访问）。

从 docs/source/so101.mdx 可以看到该命令会依次提示你断开各条 MotorBus 连线，从而把端口与具体的 leader/follower 臂对应起来；这是后续所有命令中 --robot.port / --teleop.port 的来源。

4.3 设置电机 ID 与波特率（一次性，每只臂执行）

lerobot-setup-motors --robot.type=so101_follower --robot.port=<FOLLOWER_PORT>
lerobot-setup-motors --teleop.type=so101_leader  --teleop.port=<LEADER_PORT>

新电机默认 ID 都是 1，同一总线上必须为每个电机分配唯一 ID，且控制器与所有电机必须使用相同波特率才能通信；这些参数写入电机 EEPROM 非易失区，只需执行一次。如果电机是从其他机器人上拆来的，ID 与波特率很可能不匹配，也需要重做这一步。

源码层面，so_follower.py 中的 setup_motors() 会逆序遍历总线上的电机，逐个提示"只把控制板连接到某电机再按回车"，并为每个电机调用 setup_motor，完成后打印 'gripper' motor id set to 6 之类的信息。SO-101 跟随臂的 6 个电机 ID 分配为：shoulder_pan=1、shoulder_lift=2、elbow_flex=3、wrist_flex=4、wrist_roll=5、gripper=6（见 so_follower.py）。

4.4 校准（标定）

将全部关节置于行程中间位置，按回车，然后依次把每个关节扫过完整行程。--robot.id（或 --teleop.id）是校准记录的键，之后所有命令都要复用同一个 id。

lerobot-calibrate --robot.type=so101_follower --robot.port=<FOLLOWER_PORT> --robot.id=my_follower
lerobot-calibrate --teleop.type=so101_leader  --teleop.port=<LEADER_PORT>   --teleop.id=my_leader

校准的意义在于让 leader 与 follower 臂在相同物理姿态下具有相同的关节位置读数，这样在一个机器人上训练的网络才能迁移到另一台机器人上。源码中 calibrate()（so_follower.py）会先禁用扭矩、设置位置模式，然后读取半程归零偏移（set_half_turn_homings）、记录除 wrist_roll 外各关节的运动范围（wrist_roll 直接取 0~4095），把标定结果写入电机并保存为校准文件；若已存在同 id 的校准文件，会询问你是直接复用还是重新校准。

4.5 遥操作自检（不录制）

lerobot-teleoperate \
  --robot.type=so101_follower --robot.port=<FOLLOWER_PORT> --robot.id=my_follower \
  --teleop.type=so101_leader  --teleop.port=<LEADER_PORT>  --teleop.id=my_leader \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --display_data=true

相机参数以 TOML 风格的嵌套字典字符串传入；opencv 类型的相机使用索引或路径、宽高与帧率配置（对应 src/lerobot/cameras/opencv/ 的 OpenCV 相机后端）。

Feetech 超时 / 通信错误的排查要点（SO-100 / SO-101）：先检查菊花链上电机的红色 LED，不要先怀疑软件。

全部稳定亮红灯（夹爪 → 底座链路） → 接线正常。

有电机不亮 / 链路中途断开 → 接线问题：重新插紧 3-pin 线、检查控制板供电、确保每个电机完全卡到位。

LED 闪烁 → 电机处于报错状态：通常是过载（关节被强制越过限位）或供电电压错误。SO-100 / SO-101 有 5 V / 7.4 V 与 12 V 两种构建版本，二者不可互换；用 12 V 电源给 5 V / 7.4 V 的臂供电（或反之）就会触发此错误。上电前务必确认电机型号版本。

大多数"超时"错误本质是物理层面的，而非代码问题。

4.6 录制数据集

快捷键：→ 下一个 episode、← 重做当前 episode、ESC 结束并上传。

HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')

lerobot-record \
  --robot.type=so101_follower --robot.port=<FOLLOWER_PORT> --robot.id=my_follower \
  --teleop.type=so101_leader  --teleop.port=<LEADER_PORT>  --teleop.id=my_leader \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --dataset.repo_id=${HF_USER}/my_task \
  --dataset.single_task="<用一句话描述任务>" \
  --dataset.num_episodes=50 \
  --dataset.episode_time_s=30 \
  --dataset.reset_time_s=10 \
  --display_data=true

HF_USER 通过 hf auth whoami 自动提取，用于把数据集上传到你自己的 Hub 命名空间；--dataset.single_task 是对任务的单句自然语言描述，会被写入数据集元数据，训练时作为语言条件使用。数据集侧的实现细节见 src/lerobot/datasets/lerobot_dataset.py。

4.7 可视化检查（训练前必做）

检查缺失帧、相机模糊、不可达的目标、物体位置不一致等问题。上传后访问 Hugging Face 的 lerobot/visualize_dataset Space，粘贴 ${HF_USER}/my_task 即可查看。该可视化器适用于任何 LeRobot 格式的 Hub 数据集——既可用于挑选其他数据集，也可在重训前检查自己数据的质量。

4.8 回放一个 episode（自检）

lerobot-replay --robot.type=so101_follower --robot.port=<FOLLOWER_PORT> --robot.id=my_follower \
  --dataset.repo_id=${HF_USER}/my_task --dataset.episode=0

4.9 训练（默认 ACT——最快、内存占用最低）

Apple 芯片加 --policy.device=mps；没有本地 GPU 时，加 --job.target=<flavor>（如 a10g-small，可用 hf jobs hardware 查看列表）改为在 Hugging Face Jobs 上运行。策略与时长选择见第 6、7 节。

lerobot-train \
  --dataset.repo_id=${HF_USER}/my_task \
  --policy.type=act \
  --policy.device=cuda \
  --output_dir=outputs/train/act_my_task \
  --job_name=act_my_task \
  --batch_size=8 \
  --wandb.enable=true \
  --policy.repo_id=${HF_USER}/act_my_task

从 src/lerobot/configs/train.py 可以看到这些顶层参数的定义与默认值：output_dir 缺省为 outputs/train/<日期>/<时间戳>_<job_name>，job_name 缺省由策略/环境类型推导，batch_size 默认为 8，steps 默认为 100_000，save_freq 默认为 20_000；--policy.repo_id 会在训练结束后把策略权重推送到 Hub（依赖第 4.1 步的 hf auth login）。WandB 开关由 wandb.enable 控制（默认配置见 src/lerobot/configs/train.py 中的 WandBConfig）。

4.10 在真机上评估

对比成功率与遥操作基线：

lerobot-record \
  --robot.type=so101_follower --robot.port=<FOLLOWER_PORT> --robot.id=my_follower \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --dataset.repo_id=${HF_USER}/eval_my_task \
  --dataset.single_task="<与训练时相同的任务描述>" \
  --dataset.num_episodes=10 \
  --policy.path=${HF_USER}/act_my_task

评估本质上就是复用 lerobot-record，通过传入 --policy.path 让训练好的策略在线驱动机械臂，并把运行结果保存为带 eval_ 前缀的数据集。

5. 数据采集技巧（新手 → 可靠策略）

好的数据胜过聪明的模型。 请默认采纳以下建议，除非有明确证据才偏离。

5.1 布置与人体工学

接触软件之前先把装置和相机固定好。如果装置晃动或操作者感到别扭，先解决这个问题——更多劣质数据不会有用。
光照比分辨率更重要。 使用漫反射、稳定的光线，避免移动的阴影。
自问"仅凭相机画面能否完成任务？" 如果不能，说明相机位姿不对，先调整再录制。
在 rollout 时尽可能启用动作插值以获得更平滑的轨迹（动作插值器实现在 src/lerobot/utils/action_interpolator.py）。

5.2 录制前先练习

先做 5–10 次不录制的演示，形成有意识、可复现的操作策略。
犹豫不决、前后不一致的演示会教会模型犹豫。

5.3 质量优先于速度

刻意、高质量的演示胜过快速粗糙的演示。只有在策略稳定后才追求速度——永远不要用质量换速度。

5.4 episode 内与跨 episode 的一致性

保持相同的抓取方式、接近向量与节奏。一致的操作策略远比动作剧烈变化的数据更容易学习。

5.5 从小做起，再逐步扩展（黄金法则）

最初的 50 个 episode 用受限版本：单一物体、固定位置、固定相机、单一操作者。
先训练一个快速 ACT 模型，看看哪里失败。
然后每次沿一个维度增加多样性：更多位置 → 更多光照 → 更多物体 → 更多操作者。
不要试图第一天就收集"完美数据集"，要迭代。

5.6 新手策略选择

笔记本 / 首次 / 想快速出结果 → ACT。 效果出奇地好，即使在笔记本 GPU 上也训练很快。
更大 GPU / 语言条件 / 多任务 → SmolVLA。 解锁视觉编码器（见 7.6）收益很大。
π0 / π0.5 / Wall-X / X-VLA 建议在有了可靠的 ACT 基线且 GPU ≥ 20 GB 之后再尝试。

5.7 首个任务推荐默认值

设置	值
Episodes	50 起步，第一次训练后扩展到 100–300
Episode 长度	20–45 s（抓取/放置类任务可以更短）
Reset 时间	10 s
FPS	30
相机	推荐 2 台：1 台固定前置 + 1 台腕部。多视角通常优于单视角；单台固定相机也可以，保持简单
任务描述	简短、具体、以动作措辞的单句

5.8 故障信号

策略在某个特定阶段失败 → 额外录制 10–20 个专门针对该阶段的 episode。
策略抖动 / 振荡 → 多半是演示不一致，或需要更多训练；重录最差的 episode（用 ← 重做）。
策略忽略物体 → 是相机取景或光照问题，不是模型问题。

6. 该训练哪个策略？

把策略选择与用户的 GPU 内存和时间预算匹配。下表数据来自一次内部 profiling 运行（每个策略一个训练 update），仅供参考，务必阅读后面的注意事项。

6.1 Profiling 快照（指示性数据）

所有策略通常训练 5–10 个 epoch（见第 7 节）。

面向人类读者的版本： docs/source/hardware_guide.mdx 复用了下表，并增加了云 GPU 分级指南和 Hugging Face Jobs 入口。

策略	Batch	Update (ms)	峰值 GPU 内存 (GB)	最适合
`act`	4	83.9	0.94	首次用户、笔记本、单任务。快速可靠。
`diffusion`	4	168.6	4.94	多模态动作分布；需要中端 GPU。
`smolvla`	1	357.8	3.93	语言条件、多任务、小型 VLA。解锁视觉编码器收益巨大（见 7.6）。
`xvla`	1	731.6	15.52	大型 VLA、多任务。
`wall_x`	1	716.5	15.95	带世界模型目标的大型 VLA。
`pi0`	1	940.3	15.50	强大的大型 VLA 基线（Physical Intelligence）。
`pi05`	1	1055.8	16.35	更新的 π 系列策略；与 `pi0` 占用相近。

关键注意事项：

优化器： 上表用 SGD 测得。LeRobot 默认是 AdamW，会保留额外优化器状态 → 使用默认配置时峰值内存会明显更高，尤其是 pi0、pi05、wall_x、xvla。
Batch 大小： 大型策略按 batch=1 profiling。实际训练建议用更大的 batch 以获得稳定训练（见 7.4）。内存随 batch 大致线性增长。

6.2 决策规则

显存 < 8 GB（笔记本、3060、M 系列 Mac） → act。若剩 6–8 GB 空闲可考虑 diffusion。
显存 12–16 GB（4070/4080、A4000） → smolvla 默认配置，或 act/diffusion 用更大 batch。pi0/pi05/wall_x/xvla 仅在小 batch + 梯度累积下可行。
显存 24+ GB（3090/4090/A5000） → 任意策略。多任务优先 smolvla（解锁视觉编码器）；单任务抓放仍推荐 act（往往 ROI 最高）。可尝试 pi0、pi05 或 xvla。
显存 80 GB（A100/H100） → 任意策略且可用健康 batch。pi05、xvla、wall_x 变得从容。
仅 CPU → 不要在本机训练。改用 Google Colab（见 docs/source/notebooks.mdx）或租用 GPU。

7. 该训练多久？

机器人模仿学习通常只需在数据集上训练几个 epoch 即可收敛，而非数十万原始 step。先想 epoch，再换算成 step。

7.1 经验法则

典型总量：5–10 个 epoch。 从 5 开始，评估后再决定是否增加。
极小数据集（< 30 个 episode）可能需要稍多 epoch——但首先去采集更多数据。
带预训练视觉骨干的 VLA 通常比从零训练需要更少 epoch。

7.2 Steps ↔ Epochs 换算

total_frames     = 所有 episode 的帧数之和      # 例如 50 eps × 30 fps × 30 s ≈ 45,000
steps_per_epoch  = ceil(total_frames / batch_size)
total_steps      = epochs × steps_per_epoch

以 --batch_size=8 为例：

数据集规模	帧数	Steps / epoch	5 epochs	10 epochs
50 eps × 30 s @ 30 fps	45,000	~5,625	28k	56k
100 eps × 30 s @ 30 fps	90,000	~11,250	56k	113k
300 eps × 30 s @ 30 fps	270,000	~33,750	169k	338k

把得到的总步数通过 --steps=<N> 传入；评估时可在中间检查点（outputs/train/.../checkpoints/）查看效果。

7.3 各策略起步建议（单任务，约 50 个 episode）

策略	Batch	Steps（首次运行）	备注
`act`	8–16	30k–80k	单任务通常 50k 内收敛。
`diffusion`	8–16	80k–150k	比 ACT 需要更长时间训练。
`smolvla`	4–8	30k–80k	预训练 VLM → 收敛快。
`pi0` / `pi05`	1–4	30k–80k	受内存限制；用梯度累积让有效 batch ≥ 16！

7.4 Batch 大小建议

遥操作数据上，更大的 batch 更有利于梯度稳定。
若 GPU 内存是瓶颈，用梯度累积提高_有效_ batch 而不增加峰值内存。
学习率随 batch 温和放大；LeRobot 默认值在 2–4× batch 变化范围内大多工作良好。

7.5 用 `--steps` 同步缩放 LR 调度与检查点

LeRobot 的默认调度器（如 SmolVLA 的余弦退火）使用 scheduler_decay_steps=30_000，是为长时间训练设计的。当你缩短训练（例如小数据集上 5k–10k 步）时，要把调度器同步缩小——否则学习率会一直停留在峰值附近而不衰减。检查点频率同理：

lerobot-train ... \
  --steps=5000 \
  --policy.scheduler_decay_steps=5000 \
  --save_freq=5000

经验法则：令 scheduler_decay_steps ≈ steps，save_freq 按评估粒度设置（如每 1k–5k 步）；超短运行时按比例匹配 scheduler_warmup_steps。

7.6 SmolVLA：解锁视觉编码器换取实质收益

SmolVLA 默认 freeze_vision_encoder=True。在专用任务上解锁通常能大幅提升性能，代价是更多显存和更慢的 step：

lerobot-train ... --policy.type=smolvla \
  --policy.freeze_vision_encoder=false \
  --policy.train_expert_only=false

7.7 停止 / 继续的信号

训练损失趋于平稳 → 停止，保存 Hub 检查点。
训练损失仍在下降且未满 10 个 epoch → 继续训练。

8. 评估与基准测试

评估有两种形式：

8.1 真机评估（SO-101 等）

复用 lerobot-record 加 --policy.path 让训练好的策略在真机上运行，并把运行保存为评估数据集。惯例：数据集以 eval_ 前缀命名。

lerobot-record \
  --robot.type=so101_follower --robot.port=<FOLLOWER_PORT> --robot.id=my_follower \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --dataset.repo_id=${HF_USER}/eval_my_task \
  --dataset.single_task="<与训练时相同的任务描述>" \
  --dataset.num_episodes=10 \
  --policy.path=${HF_USER}/act_my_task

统计各 episode 的成功率，并与遥操作基线、早期检查点对比以捕捉回归。

8.2 仿真基准评估

对在仿真数据集（PushT、Aloha、LIBERO、MetaWorld、RoboCasa 等）上训练的策略，用 lerobot-eval 配合对应的 env.type：

lerobot-eval \
  --policy.path=${HF_USER}/diffusion_pusht \
  --env.type=pusht \
  --eval.n_episodes=50 \
  --eval.batch_size=10 \
  --policy.device=cuda

本地检查点用 --policy.path=outputs/train/.../checkpoints/<step>/pretrained_model。
--eval.n_episodes 建议 ≥ 50 以获得稳定的成功率估计。
可用环境位于 src/lerobot/envs/。具体基准见 docs/source/libero.mdx、docs/source/metaworld.mdx、docs/source/robocasa.mdx、docs/source/vlabench.mdx。
新增基准见 docs/source/adding_benchmarks.mdx 与 docs/source/envhub.mdx。

8.2b 基准评估用的 Dockerfile

基准环境有本地安装很痛苦的原生依赖。仓库为每个受支持的基准预置了 Dockerfile，可在可复现的环境中运行 lerobot-eval：

基准	Dockerfile
LIBERO	docker/Dockerfile.benchmark.libero
LIBERO+	docker/Dockerfile.benchmark.libero_plus
MetaWorld	docker/Dockerfile.benchmark.metaworld
RoboCasa	docker/Dockerfile.benchmark.robocasa
RoboCerebra	docker/Dockerfile.benchmark.robocerebra
RoboMME	docker/Dockerfile.benchmark.robomme
RoboTwin	docker/Dockerfile.benchmark.robotwin
VLABench	docker/Dockerfile.benchmark.vlabench

构建并运行（按你的基准调整）：

docker build -f docker/Dockerfile.benchmark.robomme -t lerobot-bench-robomme .
docker run --gpus all --rm -it \
  -v $HOME/.cache/huggingface:/root/.cache/huggingface \
  lerobot-bench-robomme \
  lerobot-eval --policy.path=<your_policy> --env.type=<env> --eval.n_episodes=50

基础镜像细节见 docker/README.md。

8.3 目标成功率

50 个干净 episode 的单任务抓取-放置：ACT 在训练配置上应达到 > 70% 成功率。达不到 → 是数据问题（见第 5 节），而非模型问题。泛化到新位置时预期会有下降——通过增加 episode 或多样性来恢复。

9. 延伸阅读

入门： docs/source/installation.mdx · docs/source/il_robots.mdx
各策略文档： 浏览 docs/source/ 下的 *.mdx（策略、硬件、基准、进阶训练）。
机器人侧文档： SO-101 的装机、电机配置、校准与 API 示例见 docs/source/so101.mdx，仓库内的策略侧对应文档见 src/lerobot/robots/so_follower/so101.md；跟随臂与主控臂的可配置项（端口、PID 系数、use_degrees、num_read_retries 等）见 src/lerobot/robots/so_follower/config_so_follower.py 与 src/lerobot/teleoperators/so_leader/config_so_leader.py。