使用 SO-100 录制您的第一个 LeRobot 数据集

一个SO-100从动机器人，一个相同设计的引导臂和两个USB摄像头可以在一个下午内微调一个策略。同样的测试台也可以轻松生成六十个在文件浏览器中看起来正常的片段，并浪费六小时的GPU运行时间。差异很少在于模型；而在于伺服系统和parquet文件之间发生的事情。

这是手动路线，然后是更短的路线。每个命令都来自lerobot 0.6.1，该版本于2026年8月3日发布，目前在PyPI上。它已移至控制台入口点，因此运行python lerobot/scripts/control_robot.py的教程描述了一个不再存在的文件。

录制会话捕获了什么

一个 LeRobot 数据集 不是视频文件夹，而是带有视频的时间索引表：每个控制循环周期写入一行，其中包含指令动作、跟随器达到的状态、每个摄像头的一帧、时间戳和索引。策略只查看这些列。lerobot/svla_so100_pickplace 的模式，从其 meta/info.json 中读取。

关节包括 main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll 和 main_gripper：SO-100 的六个自由度。动作和状态共享一个形状，因为主从遥操作记录了一个目标以及一步之后达到的位置。这个差距是信息：手臂在哪里对抗重力或卡住的物体。这些字符串是该数据集的。今天用 0.6.1 记录的会话会写入 shoulder_pan.pos 到 gripper.pos，总线上的 ID 为 1 到 6：相同的六个关节，不同的键，这在配置按名称寻址特征时很重要。

工作台所需物品

如果机械臂尚未组装，那将是另一项任务：请从和开始。如果您尚未购买任何部件，请先阅读：SO-101 是更新的版本，改进了布线，无需拆卸齿轮，并且录制工作流程是相同的。

安装 lerobot 0.6.1

conda create -y -n lerobot python=3.12
conda activate lerobot

# TorchCodec is the default video decoder and needs ffmpeg
conda install ffmpeg -c conda-forge

# core_scripts = dataset + hardware + viz extras (record, replay, calibrate)
# feetech     = SDK for the STS3215 bus servos in the SO-100
pip install 'lerobot[core_scripts,feetech]'

lerobot-info

附加组件最容易让人困惑。pip install lerobot仅安装核心机器学习依赖项，不包括与机器人通信的组件。Koch 机械臂需要dynamixel而不是feetech。如果您的 shell 从未听说过 lerobot-record，这就是原因。

端口、电机ID和校准

在零件和正常工作的遥操作循环之间，有三个一次性步骤。 使得在您的机械臂上训练的策略可以在其他机械臂上运行，将原始编码器计数映射到共享的关节约定。

1. 1
   查找每个机械臂的USB端口

   在两个机械臂都插入的情况下运行它，当提示时拔下您正在识别的那个，并记下哪个端口消失了。在Linux上，您可能需要sudo chmod 666 /dev/ttyACM0。

   bash

   lerobot-find-port
   # Finding all available ports for the MotorsBus.
   # Ports before disconnecting: ['/dev/ttyACM0', '/dev/ttyACM1']
   # Remove the USB cable from your MotorsBus and press Enter when done.
   # The port of this MotorsBus is '/dev/ttyACM1'
   # Reconnect the USB cable.

2. 2
   写入电机ID和波特率

   ID是逐个电机写入的，文档对操作方式有严格规定：只连接一个电机到控制器板，不要与其他电机串联。脚本会向后遍历链条，首先提示夹爪并为其分配ID 6，然后是腕部旋转（wrist_roll）ID 5，一直到肩部平移（shoulder_pan）ID 1。请在组装前完成此操作。

   bash

   lerobot-setup-motors \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0
   
   lerobot-setup-motors \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1

3. 3
   校准两个机械臂

   将每个关节移动到其范围的中间，按回车键，然后将每个关节扫过其完整范围。id将成为配置文件名。

   bash

   lerobot-calibrate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower
   
   lerobot-calibrate \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader

4. 4
   在录制任何内容之前进行遥操作

   这是对上述所有步骤的验收测试。如果遥操作出现卡顿、镜像或某个关节不跟随，录制会在50个片段中保留这些问题。

   bash

   lerobot-teleoperate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader \
       --display_data=true

摄像头决定策略看到什么

lerobot-find-cameras opencv   # or: lerobot-find-cameras realsense

# --- Detected Cameras ---
# Camera #0:
#   Name: OpenCV Camera @ 0
#   Type: OpenCV
#   Id: 0
#   Backend api: AVFOUNDATION
#   Default stream profile:
#     Format: 16.0
#     Width: 1920
#     Height: 1080
#     Fps: 15.0

两个视角，它们的位置很重要：一个覆盖工作空间的固定场景摄像头，以及一个靠近末端执行器的腕部摄像头，显示夹持器即将接触的物体。LeRobot 社区数据集清单要求最好有两个 480x640 / 720p 或更高分辨率的视角，一个静态背景，中性稳定的照明，并且主导臂和人体肢体不在画面中。录制指南补充了一条经验法则：您应该能够仅通过查看摄像头图像来完成任务。

record 命令和所有标志

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

lerobot-record \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_so100_follower \
    --robot.cameras="{ top: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30}}" \
    --teleop.type=so100_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_so100_leader \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/so100_pick_cube \
    --dataset.single_task="Pick the red cube and drop it in the box" \
    --dataset.num_episodes=50 \
    --dataset.fps=30 \
    --dataset.episode_time_s=25 \
    --dataset.reset_time_s=10 \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2

下面的默认值来自 src/lerobot/configs/dataset.py 的 main 分支，而非教程。其中一些并非人们所预期的。

会话期间的键盘控制

• 右箭头或 n：提前结束 episode 或重置阶段。这是你最常用的键，因为一次干净的抓取很少需要 25 秒。
• 左箭头或 r：丢弃当前 episode 并重做。一次糟糕的尝试现在不花任何成本，但以后会付出很多。
• Escape 或 q：停止会话，完成编码，上传。
• 这些在 X11、Wayland 和无头 SSH 上都有效：在没有全局键盘后端的情况下，lerobot-record 会从控制终端读取相同的按键。这些字母键在延迟高的 SSH 链接中也能正常工作，而箭头序列可能会被拆分。
• 键盘遥操作则不同，它确实需要一个全局后端：X11、Windows 或带有辅助功能的 macOS。

多少个 episode，以及一个好的 episode 是什么样子

录制指南建议第一个任务至少录制50个片段，每个物体位置大约10个。 策略页面 列出了每个模型的最低要求，低于此要求运行不值得花费GPU时间。

更好的问题是“多少”和“什么”。 机器人操作模仿学习中的数据扩展定律 （Lin 等人，2024）收集了超过 40,000 个演示，并进行了超过 15,000 次真实世界部署。泛化能力与 环境和物体 的数量大致呈幂律关系，并且在每个环境或物体达到阈值后，额外的演示效果甚微。在一个测试台上：移动物体、改变光照、更换方块，而不是重复一次拍摄。

一个好的片段是无聊的：可重复的起始姿态，只完成一件事，一旦物体进入垃圾箱就结束，任务字符串在清单推荐的25到50个字符之间。 拿起红色方块并将其放入盒子中 是一个任务字符串；task1 是清单明确指出的反模式。模糊的注释是其问题列表的首要项，它们对于 最为重要，因为字符串是模型输入，而不是文件名。

悄然破坏数据集的缺陷

没有一个会抛出异常。所有缺陷都会在训练中幸存下来，表现为看起来正常的损失曲线和什么都不做的机器人。在场景设置时进行检查。

一个注意事项：流式编码指南的表格将默认值列为True，而主分支上的数据类显示为streaming_encoding: bool = False。文档和代码不一致，因此请明确设置它；lerobot在每次以该标志关闭启动时都会记录一条提示，建议进行设置。

在租用GPU之前检查数据集

文档中的验收测试：将视频时长与CLI报告的剧集时长进行比较，并确认行数等于帧率乘以时长。按剧集计算，而不是总计。

from lerobot.datasets import LeRobotDataset

ds = LeRobotDataset("your-user/so100_pick_cube_20260823_141530")
print("fps:", ds.fps, "frames:", ds.num_frames)

# In v3.0 the per-episode records live in meta/episodes/ as chunked parquet:
# lengths, tasks and offsets into the shared parquet and mp4 shards.
# They load through the datasets stack, so this is a datasets.Dataset --
# use .column_names and integer indexing, not pandas .columns / .head().
eps = ds.meta.episodes
print(eps.column_names)
print(eps[0])

# Global feature statistics, including per-joint min and max.
# A joint whose min equals its max never moved. A joint sitting at a
# hard limit for most of the run is the one that will stall the policy.
print(ds.meta.stats["observation.state"])

然后查看它。 lerobot-dataset-viz 在Rerun或Foxglove中，逐帧回放一个片段，并在摄像机视图旁边显示关节轨迹。交换的摄像机和冻结的帧会在十秒内显示出来。人们通常会跳过这一步。

# Replay one episode with camera views and joint traces
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0

# Foxglove instead, for a seekable, scrubbable timeline
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0 \
    --display-mode foxglove

# Drop the episodes that did not survive review
lerobot-edit-dataset \
    --repo_id your-user/so100_pick_cube_20260823_141530 \
    --new_repo_id your-user/so100_pick_cube_clean \
    --operation.type delete_episodes \
    --operation.episode_indices "[3, 17, 41]"

v2.1 或 v3.0：录制前决定

v2.1 为每个剧集写入一个 parquet 文件和一个 MP4 文件。v3.0 将多个剧集连接到共享分片中，并从元数据重建边界，因此 info.json 包含路径模板，例如 data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet 而不是剧集编号。上游的理由是文件更少、更大：更快的初始化和在规模化时更小的文件系统压力。

# Upgrade an older v2.1 dataset to v3.0
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube

# By default it pushes the converted dataset back to the hub and tags it v3.0.
# To convert a local copy and keep it off the hub:
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube \
    --root=/path/to/dataset/directory \
    --push-to-hub=false

通往同一数据集的两种途径

从数据集到策略

五十个干净的片段为每次运行提供数据。仅针对您的任务从头开始训练，大约80 M参数，每个动作步骤大约20毫秒，是五种策略中唯一能适应快速运动的。在大约24 GB的显卡上拥有约450 M参数。是一个大约3 B参数的基础模型，其中涉及大约40 M参数，需要A100或H100显卡，并且需要v2.1数据集。

接下来，您的组合指南：，或；对于首次运行，更简短。当策略在测试台上工作正常，但移动桌子时立即崩溃，这是一个数据问题：和更深入地探讨多样性。