Microduck Robot●microduck-robot.com

Microduck Robot / LEROBOT

LeRobot SO-101 教程:组装、校准、录制、训练与运行

本指南依据 Hugging Face 官方 LeRobot 文档编写,涵盖 SO-101 主臂和从臂,补充了搭建者最容易漏掉的检查项,最后以 LeKiwi 移动底盘和一份故障排查清单收尾。文中的命令对应 LeRobot v0.7.0(2026 年 11 月 5 日发布)。LeRobot 更新很快,请对照你所安装版本的文档核对各项参数。

你将搭建什么,以及需要准备什么

LeRobot 是 Hugging Face 的开源机器人库。用同一套命令就能驱动机器人、录制示范、训练策略并运行策略。SO-101 是它的旗舰机械臂:你用手移动主臂,从臂随之复制动作,录下的动作和摄像头图像会教神经网络自己重复完成任务。

整个过程分为七个阶段:备齐零件并安装软件,为每个电机设置 ID,组装两条机械臂,校准,带摄像头遥操作,录制数据集,最后训练并运行策略。最后一个搭建章节加入 LeKiwi 移动底盘,之后是一份故障排查清单。

左右滑动可查看完整图示。

搭建的七个阶段,以及每个阶段使用的命令从上到下的七个编号阶段。1 零件与软件:pip install lerobot。2 端口与电机 ID:lerobot-find-port 和 lerobot-setup-motors。3 手工组装两条机械臂,没有命令。4 校准:lerobot-calibrate。5 带摄像头遥操作:lerobot-find-cameras 和 lerobot-teleoperate。6 录制数据集:lerobot-record,并用 lerobot-replay 检查。7 训练并运行策略:先 lerobot-train,再 lerobot-rollout。1零件与软件备齐零件,安装 LeRobotpip install lerobot2端口与电机 ID一次只接一个舵机lerobot-find-portlerobot-setup-motors3组装两条机械臂逐个关节,两条臂都要没有命令:手工组装4校准两条臂读数一致lerobot-calibrate5带摄像头遥操作主臂带动从臂lerobot-find-cameraslerobot-teleoperate6录制数据集关节位置与视频lerobot-recordlerobot-replay7训练并运行策略在从臂上运行 ACT 策略lerobot-trainlerobot-rollout
搭建的七个阶段,以及每个阶段使用的命令

你需要两条机械臂(零件见下一节)、每条机械臂各一块 USB 总线舵机控制板和一个电源、一台安装了 Python 3.12 或更高版本的电脑、两个 USB 摄像头(本指南中的命令用到两个)、一个用于存放数据集和检查点的免费 Hugging Face 账号,以及用于训练的 GPU。本文使用的 ACT 策略,笔记本级别的 GPU 就够用,租用 GPU 也可以。

本指南根据官方文档和社区搭建报告整理而成,我们没有在每一个硬件版本上对每一步都做过台架测试。调用 control_robot.py 的旧教程不适用于 0.7.0,该版本使用的是 lerobot-* 命令。

零件、打印与供电

SO-101 项目公布了物料清单和打印文件,Hugging Face 的 SO-101 页面链接了这两项内容。一套完整的主臂和从臂需要 12 个 Feetech STS3215 舵机、两块控制板、两个电源、两根 USB-C 线、桌面夹具。组装使用 M2×6 和 M3×6 螺丝;项目的物料清单没有列出它们,所以请查看舵机或套件随附了什么。也有已打印好的零件和完整套件出售。

从臂的六个舵机减速比均为 1/345。主臂使用三种不同的减速比,这样它既能撑住自身重量,又只需很小的力就能移动。

电源要与舵机匹配。7.4 V 的 STS3215 在 6 V 时堵转扭矩为 16.5 kg·cm(使用 5 V 电源时略小),通常使用 5 V 电源供电。从臂可以改用 12 V 舵机(30 kg·cm)获得更大动力,但这时需要额定 5 A 或以上的 12 V 电源;主臂始终使用 7.4 V 舵机。切勿把 12 V 电源接到装有 7.4 V 舵机的控制板上;请在每个电源上标明它的电压以及它所属的机械臂。

左右滑动可查看完整图示。

主臂和从臂的供电与 USB 连接顶部的电脑通过 USB-C 线连接到主臂的控制板和从臂的控制板。每块控制板有各自的电源。每块板上用 3 针线缆串联六个舵机,从舵机 1 开始。主臂始终使用 5 V 电源供电的 7.4 V 舵机。从臂使用 5 V 电源供电的 7.4 V 舵机,或使用额定 5 A 或以上的 12 V 电源供电的 12 V 舵机。Waveshare 控制板上,两个跳线帽都设在通道 B,即 USB 通道。电脑主臂5 V 电源控制板Waveshare 板:两个跳线帽都放在通道 B(USB)。1234566 个 7.4 V 舵机,由 5 V 电源供电。从臂电源:5 V,或 12 V 5 A+控制板Waveshare 板:两个跳线帽都放在通道 B(USB)。1234567.4 V 舵机接 5 V,12 V 舵机接 12 V。电源USB-C 线3 针舵机线缆切勿把 12 V 电源接到装有 7.4 V 舵机的控制板上。
主臂和从臂的供电与 USB 连接

使用 PLA+ 打印,0.4 mm 喷嘴配 0.2 mm 层高(或 0.6 mm 喷嘴配 0.4 mm 层高),填充率 15%。每条机械臂的零件各自是一个文件,摆放方向已设计成只需少量支撑;不要在水平的螺丝孔里留支撑。先打印 Gauge Zero 和 Gauge Tight 这两个测试件,并拿舵机对照检查;如果 Gauge Zero 不能像项目视频中所示那样装配,请先调整打印机设置并重新打印,然后再打印机械臂。

备好 0 号和 1 号十字螺丝刀,测试前先把每个底座夹在桌面上。我们为这套搭建提供的零件链接在下方。

横向滚动以比较全部栏目。

关节电机 ID主臂减速比从臂减速比
肩部平转11/1911/345
肩部抬升21/3451/345
肘部弯曲31/1911/345
腕部弯曲41/1471/345
腕部滚转51/1471/345
夹爪61/1471/345

安装 LeRobot 和电机支持

LeRobot 0.7.0 需要 Python 3.12 或更高版本。用 conda(来自 miniforge)或 uv 创建独立环境,并在每个新终端中激活它。在大多数平台上,视频处理需要 ffmpeg(在 macOS Intel 和 32 位 ARM Linux 上,LeRobot 会改用 PyAV,可以跳过它);conda 版的 ffmpeg 适用于所有 PyTorch 版本。

创建环境
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge

从 PyPI 安装 LeRobot,并带上你需要的扩展。core_scripts 提供录制、回放和校准所用的内容,feetech 增加对 STS3215 舵机的支持,training 增加训练工具。

安装 LeRobot 及所需扩展
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'

平台说明:在 Apple silicon 上,PyTorch 需要 macOS 14 或更高版本,要使用 GPU(MPS)加速则需要 macOS 15 或更高版本。在 Linux 上使用 NVIDIA GPU 时,默认的 PyTorch 构建需要 580.65 或更高版本的驱动;驱动较旧时,请先安装与之匹配的 CUDA 版 PyTorch,并从 CPU 索引安装 torchcodec(见 Hugging Face 安装页面)。在 WSL 中还要安装 evdev(conda install evdev -c conda-forge;使用 uv 时先 sudo apt install libevdev-dev,再 uv pip install evdev)。使用 PyTorch 2.10 或更高版本时,可以用系统自带的 ffmpeg 代替 conda 版。

查找端口并设置电机 ID

新的 STS3215 舵机出厂时 ID 通常是 1,而且控制器和每个舵机必须使用同一波特率。LeRobot 会把这两项一次性写入每个舵机的内存,所以请在组装前完成,并且一次只连接一个舵机。从其他机器人上拆下来重复使用的舵机很可能同样需要这样做。

左右滑动可查看完整图示。

SO-101 机械臂的六个关节及各自的电机 ID机械臂侧视图。关节 1(肩部平转)绕底座处的竖直轴转动整条机械臂。关节 2、3、4(肩部抬升、肘部弯曲、腕部弯曲)使机械臂在同一平面内弯曲。关节 5(腕部滚转)使夹爪绕前臂的轴线转动。关节 6 是夹爪。每个关节的电机 ID 就是它的编号。连杆长度和轴线与官方 SO-101 模型一致。1234561肩部平转2肩部抬升3肘部弯曲4腕部弯曲5腕部滚转6夹爪电机 ID = 关节编号。设置顺序:从 6 到 1。从臂侧视图,比例取自官方 SO-101 模型。主臂上,关节 6 是扳机。
SO-101 机械臂的六个关节及各自的电机 ID

用 USB 把一块控制板连接到电脑并通电,然后运行端口查找工具。按提示只拔掉这块控制板的 USB 线并按 Enter 键;脚本会打印出端口,例如 Linux 上的 /dev/ttyACM0、macOS 上的 /dev/tty.usbmodem… 或 Windows 上的 COM3。把线插回去,再对第二块控制板重复此步骤。在 Linux 上,你可能需要对每个端口用 sudo chmod 666 授予访问权限(例如 /dev/ttyACM0 和 /dev/ttyACM1)。

查找控制板端口
lerobot-find-port

先为从臂运行设置脚本,再为主臂运行,两者各用各自的端口。脚本每次只点名一个电机,所以运行之前请先读完下面的步骤。

设置从臂电机 ID
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0

主臂使用遥操作器选项,而不是机器人选项。在每次提示时,请取零件一节表格中该关节所列减速比的那个电机(主臂上:肩部平转和肘部弯曲为 1/191,肩部抬升为 1/345,腕部弯曲、腕部滚转和夹爪为 1/147),并在脚本报告某个电机已设置好之后,立刻在该电机上标出它的 ID。

设置主臂电机 ID
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1
  1. 脚本每次只点名一个电机,从夹爪(ID 6)开始,到肩部平转(ID 1)结束。只把该电机连接到控制板,它不能与任何其他电机串联。
  2. 按 Enter 键。脚本提示 ID 已设置后,从控制板上拔下该电机的线缆,连接它点名的下一个电机,然后再次按 Enter 键。
  3. 每次按 Enter 键之前,先检查电源线、USB 线和 3 针线缆。如果脚本报错,先检查这些线缆;使用 Waveshare 控制板时,两个跳线帽都必须放在通道 B(USB)上。
  4. 脚本结束后,按顺序把各电机串联起来,并把肩部平转电机(ID 1)连接到控制板。

    左右滑动可查看完整图示。

    一次设置一个舵机的 ID,再按顺序把舵机串联起来上方面板:设置 ID 时,控制板上只连接一个舵机。设置脚本按 6、5、4、3、2、1 的顺序点名各个舵机。下方面板:设置完成后,舵机按顺序串联。舵机 1 连接控制板,之后每个舵机连接到前一个舵机,直到舵机 6。设置 ID 时只连接正在设置的那个舵机。把它拔下,再连接脚本点名的下一个。控制板?脚本点名的顺序654321设置完成后按顺序串联舵机。舵机 1 连接控制板。控制板123456
    一次设置一个舵机的 ID,再按顺序把舵机串联起来

组装主臂和从臂

两条机械臂共用大部分打印件,并按同样的顺序组装(腕部滚转的零件不同;从臂装有活动爪的位置,主臂装的是手柄和扳机):底座和肩部、上臂、前臂、腕部,然后是从臂的夹爪,或主臂的手柄和扳机。Hugging Face 在其 SO-101 页面上为每个关节发布了一段简短视频;请对照视频和这些说明操作。先清除打印件上的全部支撑材料,并在把每个舵机封入结构之前,先给它插好 3 针线缆。

  1. 关节 1,肩部平转:把两个舵盘装到电机上,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝)。用四颗 M2×6 螺丝把电机装进底座,套上第一个电机支架并用两颗 M2×6 固定,然后在上方用四颗 M3×6、下方再用四颗,装上肩部,最后加上肩部电机支架。
  2. 关节 2,肩部抬升:装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),从上方滑入电机,用四颗 M2×6 固定,然后在两侧各用四颗 M3×6 装上上臂。
  3. 关节 3,肘部:装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),用四颗 M2×6 装入电机 3,并在两侧各用四颗 M3×6 把前臂与它连接。
  4. 关节 4,腕部弯曲:装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),套入电机支架 4,再滑入电机 4,并用四颗 M2×6 固定。
  5. 关节 5,腕部滚转:把电机 5 放入腕部支架,在前侧用两颗 M2×6 固定,装上一个舵盘并用一颗 M3×6 螺丝固定,然后按官方关节 5 视频所示,用 M3×6 螺丝把腕部固定到电机 4 上(文字指南写的是两侧各四颗)。
  6. 从臂夹爪:用四颗 M3×6 把夹爪装到腕部电机的舵盘上,在两侧各用两颗 M2×6 装入夹爪电机,装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),再按官方夹爪视频所示,用 M3×6 螺丝固定爪子(文字指南写的是两侧各四颗)。
  7. 主臂手柄:用四颗 M3×6 把主臂支架装到腕部,用一颗 M2×6 把手柄固定到支架上,在两侧各用两颗 M2×6 装入电机 6(即扳机电机,官方指南称之为夹爪电机),并装一个舵盘,用一颗 M3×6 螺丝固定,然后用四颗 M3×6 装上扳机。
  8. 通电之前,用手慢慢让每个关节走完整个活动范围,切勿强行越过限位;关节应转动顺畅,没有刮擦。在把每个电机封入结构之前,先标出它的 ID,并把两个底座夹在桌面上。

校准两条机械臂

校准会记录每个关节的活动范围,使主臂和从臂在同一个物理姿态下报告相同的数值。它还能让在一台机器人上训练出的策略运行在另一台上。每条机械臂校准一次;硬件有改动,或 LeRobot 提示缺少校准时,要再校准一次。重新校准之前录制的数据和训练出的策略,用的是旧的校准。

先校准从臂。脚本会要求你把每个关节移到其活动范围的中间位置并按 Enter 键,然后让每个关节走完全部活动范围,等每个关节都走完之后再按一次 Enter 键。给每条机械臂设置一个唯一的 id;这个名字用来标记它的校准文件。本指南中的命令以 /dev/ttyACM0 作为从臂的端口、/dev/ttyACM1 作为主臂的端口,仅作示例:请换成你自己找到的端口,并且不要把两条机械臂弄反。

左右滑动可查看完整图示。

校准:先让每个关节居中,再走完各关节的全部活动范围左右并排两个面板。第 1 步:六个关节各自停在活动范围的中间位置,用横条中心的圆点表示,然后按 Enter 键。第 2 步:六个关节各自走完整个活动范围,用从横条最小端到最大端的双向箭头表示。下方:同一个物理姿态,主臂和从臂给出相同的位置数值。第 1 步:中间位置把每个关节移到其活动范围的中间位置,然后按 Enter 键。123456中间第 2 步:全部活动范围让每个关节走完整个活动范围,然后再按一次 Enter 键。123456最小最大同一个物理姿态,主臂和从臂给出相同的位置数值。
校准:先让每个关节居中,再走完各关节的全部活动范围
校准从臂
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

之后的每条命令都要使用同一个 id;LeRobot 靠它找到默认存放在 ~/.cache/huggingface/lerobot/calibration 下的校准文件。请备份该文件,并且不要把它放在临时文件夹里:一位社区搭建者在一次断电重启中丢失了校准文件,重新校准时没有让每个关节都处于活动范围的中间位置,结果有些关节的归零偏移是错的。

用主臂遥操作从臂

遥操作把两条机械臂连接起来:从臂复制主臂的动作。如果缺少校准,命令会先启动校准流程。从缓慢、幅度小的动作开始,远离从臂的关节,并让电源保持在伸手可及的位置。

遥操作
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

接着添加摄像头。用摄像头查找工具列出摄像头,它会打印每个摄像头的标识符,并把每个摄像头的一帧测试画面保存到 outputs/captured_images;打开这些画面,看哪个索引对应哪个摄像头。重启或重新插拔摄像头后,索引可能改变。

列出摄像头
lerobot-find-cameras opencv

带着摄像头再次遥操作,并在 Rerun 中实时查看画面。你在这里为摄像头起的名字(例如 top 和 wrist)之后会成为数据集的键,所以从现在起请使用相同的名称和设置。

带摄像头和实时画面的遥操作
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

摆放摄像头,让策略学得会

策略只能看到摄像头图像和关节位置,所以摄像头的设置比高分辨率更重要。对大多数任务来说,640×480、30 fps 就足够,而且录制和训练都更快。

左右滑动可查看完整图示。

摄像头摆放:固定的任务视角、均匀的光照,以及成为数据集键的名称工作区侧视图。从臂伸向目标容器旁的一个物体。桌面上方支架上的俯视摄像头向下看整个工作区,视野用一片阴影区域表示,覆盖机械臂、物体和目标。夹爪上的腕部摄像头沿着爪口方向看。左上角的柔光灯板均匀照亮场景。摄像头在录制和运行之间保持固定。摄像头名称会成为数据集的键:observation.images.top 和 observation.images.wrist。漫射光物体目标俯视摄像头腕部摄像头牢固固定:录制和运行之间不要移动摄像头。摄像头名称就是数据集的键:observation.images.topobservation.images.wrist
摄像头摆放:固定的任务视角、均匀的光照,以及成为数据集键的名称
  1. 用漫射光均匀照亮场景。避免阳光直射、强反光和移动的阴影:录制和运行时光照不一致,可能导致策略失败。
  2. 牢固固定摄像头,在录制和运行之间不要移动它们。一位社区搭建者的第一个策略只会往桌面上啄,原因有好几个,其中之一是摄像头在录制和测试之间发生了轻微位移。
  3. 给任务取景:物体、夹爪和目标至少应在一个摄像头的画面中可见。一个好的检验办法是:只看摄像头图像,你自己能否完成这项任务。同一位社区搭建者示范时只看摄像头画面;如果你想这样试,请让电源保持在伸手可及的位置。
  4. 同一位搭建者把侧面摄像头(抓取时对夹爪尖端的视野不佳)换成了装在正面摄像头旁边的俯视摄像头,遮挡因此减少;腕部摄像头在那篇帖子里只是作为下一步出现。如果你全天录制,请在网络摄像头自带的设置里固定曝光和白平衡;LeRobot 的 RealSense 摄像头配置也接受 exposure、gain 和 white_balance。
  5. 在 Ubuntu 上使用两个相同的网络摄像头时,USB 地址可能互换,录制可能因摄像头错误而中断。同一位搭建者用 udev 规则解决了这个问题,规则按物理 USB 口来识别每个摄像头,所以请让每个摄像头始终插在同一个接口上;否则每次重启后都要重新运行摄像头查找工具。

录制数据集

数据集使用 LeRobotDataset 格式,并上传到 Hugging Face Hub。创建一个免费账号,在 Hugging Face 设置里生成具有写入权限的令牌,然后登录,并把你的用户名存入一个变量。请先把 HUGGINGFACE_TOKEN 设为你的令牌,或者单独运行 hf auth login,并在提示时粘贴令牌。

登录 Hugging Face
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

先录制五个回合来测试环境。使用与遥操作时相同的机器人 id、端口和摄像头设置,并用简单的话描述任务。

录制数据集
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 \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/record-test \
    --dataset.num_episodes=5 \
    --dataset.single_task="Grab the black cube" \
    --dataset.streaming_encoding=true

LeRobot 会把日期和时间追加到数据集名称后面,所以 ${HF_USER}/record-test 会保存为 ${HF_USER}/record-test_YYYYMMDD_HHMMSS。后续命令中请使用这个完整名称;可以用 ls ~/.cache/huggingface/lerobot/${HF_USER} 查到它,也可以加上 --dataset.no_stamp=true 保留你传入的名称。数据集存放在 ~/.cache/huggingface/lerobot,录制结束时推送到 Hub。从个人账号推送的数据集可能是公开的,所以请在 Hub 上检查它的可见性,如需私有就加上 --dataset.private=true;加上 --dataset.push_to_hub=False 可只保存在本地。要接着做一次中断的录制,请用同样的命令重新运行,并带上 --resume=true、带时间戳的完整 --dataset.repo_id、设为数据集本地文件夹的 --dataset.root,以及 --dataset.num_episodes;后者要设为额外还要录的回合数,而不是总数。

回合时长和复位时长默认都是 60 秒(--dataset.episode_time_s 和 --dataset.reset_time_s),默认回合数是 50。录制过程中由键盘控制流程,见下表。

第一个有用的数据集,请选一个简单的任务,例如从几个不同位置拾取物体并放入收纳盒。至少录制 50 个回合,每个位置约 10 个,保持摄像头和你的抓取方式一致,再慢慢增加变化。失败的回合要重新录制。固定位置的 50 个回合只是一个起点;预期策略主要在你录制过的位置附近有效。LeRobot 会在每个保留下来的回合之后打印一行采集频率,并在录制结束时打印汇总。如果频率远低于 30 Hz 的目标,数据集仍然声称是 30 Hz,所以动作看起来会比实际更快。请找出拖慢循环的原因(在文档的示例中是读取摄像头),并重新录制受影响的回合,而不要直接拿它们去训练。

训练之前先检查数据。在 Hugging Face 上的 LeRobot 数据集可视化工具中打开数据集,并在机器人上回放一个回合,测试动作能否重复。回放会在没有你操作的情况下移动机械臂,所以请清空工作区,让机械臂从接近该回合第一个姿态的位置开始,并让电源保持在伸手可及的位置。

回放一个回合
lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --dataset.episode=0

横向滚动以比较全部栏目。

按键操作
右方向键或 n提前结束当前回合或复位阶段,并继续下一步
左方向键或 r丢弃当前回合并重新录制
Esc 或 q停止本次录制:正在进行的回合会被保存,然后编码视频并上传数据集(若要丢弃该回合,请先按左方向键或 r)

训练 ACT 策略

ACT(Action Chunking Transformer)是 LeRobot 教程中使用的策略:它会适应数据集中保存的电机和摄像头配置。硬件指南给出的轻量策略(ACT、VQ-BeT、TD-MPC)在批大小为 8 时约需 2 到 6 GB 的 GPU 显存,仅作参考。可以在 NVIDIA GPU(cuda)上训练;在 Apple silicon 上,把命令改为 --policy.device=mps,这需要 macOS 15 或更高版本(在 macOS 14 上,LeRobot 会回退到 CPU,不适合用于训练)。

用完整的数据集名称开始训练。

训练 ACT 策略
lerobot-train \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --policy.type=act \
    --output_dir=outputs/train/act_so101_test \
    --job_name=act_so101_test \
    --policy.device=cuda \
    --trackio.enable=true \
    --policy.repo_id=${HF_USER}/my_policy \
    --steps=20000

不加 --steps 时,训练会跑 100,000 步,对小数据集来说通常过多:模仿学习一般在对数据过 5 到 10 遍之内就能收敛。一个包含 50 个回合、每个回合 30 秒、30 fps 的数据集约有 45,000 帧,在批大小为 8 时每遍约 5,600 步,所以 5 到 10 遍大约是 28,000 到 56,000 步。上面的命令使用 --steps=20000,约三遍半,作为一次简短的初跑;如果策略训练不足就调高它,如果把它调得低很多,还要把 --policy.scheduler_decay_steps 设为接近 --steps 的值。硬件指南估计,在 RTX 3090 或 4090 上以批大小 8 训练 ACT 五遍大约需要 30 到 60 分钟,在 L4 或 A10G 上需要 1 到 2 小时,在 M1、M2 或 M3 Max 上以批大小 4 训练则需要 6 到 14 小时;它称这些数字仅供参考,实际运行可能相差约 50%。

没有合适的 GPU 时,可以用 ACT 笔记本在 Google Colab 中训练,也可以先运行 hf auth login,再在同一条命令上加一个 Hugging Face Jobs 规格,例如 --job.target=a10g-small。由于该命令启用了 Trackio,作业还需要 --trackio.space_id=<user>/<space>(加上 --trackio.private=true 可让该 Space 保持私有),或者去掉 --trackio.enable=true。Jobs 按秒计费,除非设置 --job.timeout,否则上限为 48 小时;它会替你把仅存于本地的数据集上传到私有仓库,并在结束时推送训练好的模型;hf jobs hardware 会列出可用规格。

检查点写入 outputs/train/act_so101_test/checkpoints。可以从最后一个检查点恢复被中断的训练。由于训练命令设置了 --policy.repo_id=${HF_USER}/my_policy,训练好的模型会在结束时推送到该仓库(--policy.push_to_hub=false 可关闭此行为,--policy.private=true 可让它私有);如果要自己上传检查点,请使用同样的仓库名,这样 --policy.path=${HF_USER}/my_policy 才能找到它。

恢复训练并上传模型
lerobot-train \
    --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
    --resume=true

hf upload ${HF_USER}/my_policy \
    outputs/train/act_so101_test/checkpoints/last/pretrained_model

LeRobot 的训练脚本不会评估真实机器人上的策略,所以请留出一些回合不参与训练,包括你没有录制过的起始位置,并用它们测试策略。一位社区搭建者用 50 个回合训练(五个起始位置区域,每个区域 10 个),在这些区域的新回合上成功率为 60%,而在训练时留出的一个区域的回合上只有 10%。把数据增加到每个区域 25 个回合后,同一位搭建者的结果分别达到 90% 和 75%。这些都是小样本,用搭建者自己的脚本打分。

在从臂上运行策略

用 lerobot-rollout 部署训练好的策略。使用与录制时相同的机器人 id、摄像头名称、摄像头设置和任务文本;如果此后重启或重新插拔过设备,请重新运行端口查找工具。--duration 的单位是秒;不加它,策略会一直运行到你停止为止。

在机器人上运行策略
lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USER}/my_policy \
    --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} }" \
    --task="Grab the black cube" \
    --duration=60

运行模式(strategy)决定运行期间会发生什么,见下表。会录制数据集的模式,其仓库名在你的用户名之后必须以 rollout_ 开头,例如 --dataset.repo_id=${HF_USER}/rollout_so101_test;系统会给它加上时间戳。sentry 等录制模式使用 --dataset.single_task 而不是 --task;各模式的参数请见 LeRobot 文档。

在 LeRobot v0.5.x 及更早版本中没有 lerobot-rollout;请按 v0.5.1 文档所述使用 lerobot-record。本指南中的训练参数针对当前版本。

第一次运行请使用较短的时长(例如 15 秒),保持工作区畅通,并想好怎样让机械臂停下来;断电会让电机失去力矩,所以没有靠在什么东西上的机械臂可能会掉下来。如果机械臂啄向桌面或伸得过远,先检查设置,不要急着怪模型:校准 id 相同、摄像头位置相同且名称和分辨率相同、光照相同,物体处于数据集覆盖到的位置。

横向滚动以比较全部栏目。

运行模式作用
base自主运行,不录制,用于快速测试
sentry持续录制并自动上传
highlight保留一个环形缓冲区,按键时将其保存下来
dagger人在回路中的数据采集
episodic逐回合录制,回合之间有复位阶段

用 LeKiwi 扩展你的搭建

LeKiwi 是一个三轮移动底盘,载着一条 SO-101 从臂。由 Raspberry Pi(或另一台 5 V 电脑,USB 接口要够接摄像头和电机控制板,LeKiwi 页面写的是两个或更多)运行机器人,你在笔记本上用一条主臂和键盘来驾驶它。有线版本的所有程序都在笔记本上运行,可以跳过 Pi 的步骤。零件清单、打印文件和底盘组装说明来自 Hugging Face LeKiwi 页面所链接的 LeKiwi 项目。

左右滑动可查看完整图示。

LeKiwi:笔记本通过网络驱动机器人,Raspberry Pi 驱动电机左侧是笔记本,带有主臂、键盘和脚本 teleoperate.py。右侧是 LeKiwi 机器人:一台运行 lekiwi_host 的 Raspberry Pi,通过 USB 连接电机控制板和摄像头。控制板驱动机械臂电机(ID 6 到 1)和车轮电机(ID 9、8 和 7)。笔记本与 Pi 在同一网络中通过 ZeroMQ 通信,5555 端口传输命令,5556 端口传输观测数据。有线版本中,所有程序都在笔记本上运行。笔记本主臂(USB)键盘teleoperate.py运行示例脚本,把 Pi 的地址设为remote_ip。同一网络ZeroMQ5555, 5556LeKiwi 机器人Raspberry Pi(主机)lekiwi_host控制板摄像头机械臂电机ID 6 – 1车轮电机ID 9, 8, 7有线版本:没有 Pi,所有程序都在笔记本上运行。
LeKiwi:笔记本通过网络驱动机器人,Raspberry Pi 驱动电机

用键盘驾驶底盘需要全局按键后端,所以它可以在 X11、Windows 桌面,或已给终端授予“输入监控”权限的 macOS 上工作,但不能在 Wayland 或无图形界面的机器上工作。

  1. 按上面各节搭建两条 SO-101 机械臂:一条装在底盘上,另一条作为主臂。然后组装底盘。
  2. 安装 Raspberry Pi OS,启用 SSH,并确认可以用 ssh <user>@<pi-ip> 登录。按安装一节在 Pi 和笔记本上都安装 LeRobot,然后加上 LeKiwi 扩展,它会带来舵机驱动和 ZeroMQ。
    安装 LeKiwi 扩展
    pip install 'lerobot[lekiwi]'
  3. 用一条命令设置所有电机。它会给机械臂电机分配 ID 6 到 1,给车轮分配 9、8 和 7;车轮 ID 必须与 LeKiwi 文档中所示的安装位置一致。LeKiwi 只使用一块控制板。
    设置 LeKiwi 电机 ID
    lerobot-setup-motors \
        --robot.type=lekiwi \
        --robot.port=/dev/ttyACM0
  4. 在 Pi 上校准从臂,在笔记本上校准主臂。LeKiwi 页面给主臂用的是 --teleop.type=so100_leader;请查看 examples/lekiwi/teleoperate.py 创建的是哪个主臂类,并用同样的类型和 --teleop.id 来校准。车轮电机不需要校准。
    校准 LeKiwi 机械臂
    lerobot-calibrate \
        --robot.type=lekiwi \
        --robot.id=my_awesome_kiwi
  5. 在 Pi 上激活 LeRobot 环境并启动主机。除非调高 --host.connection_time_s(例如调到 600),否则它会在 30 秒后停止;录制等较长的会话需要调高。
    在 Pi 上启动 LeKiwi 主机
    python -m lerobot.robots.lekiwi.lekiwi_host \
        --robot.id=my_awesome_kiwi \
        --host.connection_time_s=600
  6. 在笔记本上编辑 LeRobot 源码仓库中的 examples/lekiwi/teleoperate.py:把 remote_ip 设为 Pi 的地址,把主臂的 port 和 id 设为你自己的值,然后运行它。在 record.py 中还要设置 HF_REPO_ID 和 TASK_DESCRIPTION;在 replay.py 中要设置 remote_ip、port、数据集 id 和回合索引。要运行训练好的策略,LeKiwi 页面使用 examples/lekiwi/evaluate.py(设置 remote_ip、port 和模型);上一节的 lerobot-rollout 命令是为独立的 SO-101 编写的。速度有三档,用 R 和 F 切换:快速 0.3 m/s 和 90°/s,中速 0.2 m/s 和 60°/s,慢速 0.1 m/s 和 30°/s。

横向滚动以比较全部栏目。

按键操作
W向前移动
A向左移动
S向后移动
D向右移动
Z向左转
X向右转
R提高速度
F降低速度

故障排查清单

许多问题出在电源、线缆、端口,或录制与运行之间改变了的设置。修改任何代码之前,先对照下表逐项排查。

关于 LeRobot 本身的问题,Hugging Face 文档链接了它的 Discord 社区。关于我们商店出售的零件,请使用 WhatsApp 按钮或支持表单。

横向滚动以比较全部栏目。

现象检查什么
找不到串口,或访问被拒绝在控制板已通电、USB 线已插好的情况下重新运行端口查找工具。在 Linux 上,对该端口使用 sudo chmod 666 授予访问权限。重启或重新插拔后端口可能会变,请重新运行端口查找工具。
ID 脚本找不到电机检查电源、USB 线和 3 针线缆。只能连接正在设置的那个电机。使用 Waveshare 控制板时,两个跳线帽都必须在通道 B(USB)上。
重复使用的舵机找不到或没有响应它们的 ID 和波特率很可能与新机器人不匹配,SO-101 指南中也有这样的提示。重新运行电机设置,一次只设置一个舵机。
校准失败,或校准后机械臂动作不对重新校准:先让每个关节处于活动范围的中间位置并按 Enter 键,再让每个关节走完全部活动范围。一位没有让每个关节居中的社区搭建者,最终得到了错误的归零偏移。之后请使用相同的机器人 id。
摄像头断开或索引改变每次重启或重新插拔后重新运行摄像头查找工具。两个相同的网络摄像头在 Linux 上可能互换 USB 地址;一位社区搭建者用基于物理 USB 口的 udev 规则解决了这个问题。
录制按键没有反应从交互式终端启动命令,并保持该终端处于焦点;字母键 n、r 和 q 与方向键和 Esc 键同样有效。只有像 LeKiwi 那样用键盘驾驶机器人,才需要 X11、Windows 桌面或 macOS 权限。
训练找不到数据集使用完整的数据集名称,包括日期和时间后缀。
采集频率远低于 30 Hz阅读录制时打印的采集频率行。如果读取摄像头占了大头,就降低分辨率或减少摄像头数量,然后重新录制:策略期望运行时的摄像头配置与录制时相同,而远低于 30 Hz 录制的回合,会被当作 30 Hz 存储。
策略啄向桌面或伸得过远把校准 id、摄像头位置、名称和光照与录制时对比,并确认物体起始位置在数据集有示例的地方。
LeKiwi 连接不上,或主机在 30 秒后停止用 hostname -I 查出 Pi 的地址,在笔记本上 ping 它,并测试 ssh <user>@<pi-ip>;如有需要,在 sudo raspi-config 中启用 SSH。除非设置 --host.connection_time_s,否则主机会在 30 秒后停止。

项目资料来源

联系我们