Запишите свой первый набор данных LeRobot с SO-100

Последователь SO-100, ведущая рука той же конструкции и две USB-камеры могут тонко настроить политику за один день. Тот же стенд может с такой же легкостью произвести шестьдесят эпизодов, которые выглядят здоровыми в файловом браузере, и потратить шестичасовой запуск GPU впустую. Разница редко заключается в модели; она в том, что произошло между сервоприводами и файлом parquet.

Вот ручной маршрут, затем более короткий. Каждая команда взята из lerobot 0.6.1, выпущенного 3 августа 2026 года и актуального на 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, идентификаторы от 1 до 6 на шине: те же шесть суставов, разные ключи, что имеет значение в тот момент, когда конфигурация обращается к признаку по имени.

Что вам понадобится на стенде

Если манипулятор еще не собран, это отдельная задача: начните с начало работы с SO-100 и полного руководства по настройке SO-100. Если вы еще ничего не приобрели, сначала прочитайте сравнение SO-100 и SO-101: 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 устанавливает только основные зависимости ML, ничего, что взаимодействует с роботом. Манипуляторам Koch требуется dynamixel вместо feetech. Если ваша оболочка никогда не слышала о lerobot-record, то это причина.

Порты, идентификаторы моторов и калибровка

Три одноразовых шага отделяют компоненты от работающего цикла телеуправления. позволяет политике, обученной на вашей руке, работать на чужой, сопоставляя необработанные показания энкодеров с общим соглашением о суставах.

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 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
   Откалибруйте обе руки

   Переместите каждый сустав в середину его диапазона, нажмите Enter, затем проведите каждый через весь его диапазон. 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: завершить эпизод или фазу сброса раньше. Это клавиша, которую вы используете чаще всего, потому что для чистого захвата редко требуется 25 секунд.
• Стрелка влево или r: отменить эпизод и повторить его. Плохой дубль ничего не стоит сейчас и много позже.
• Escape или q: остановить сессию, завершить кодирование, загрузить.
• Они работают в X11, Wayland и безголовом SSH: без глобального бэкенда для клавиш lerobot-record считывает те же клавиши с управляющего терминала. Буквы выдерживают медленные SSH-соединения, где последовательности стрелок разделяются.
• Клавиатурная телеоперация отличается и требует глобального бэкенда: X11, Windows или macOS с Accessibility.

Сколько эпизодов и как выглядит хороший

Руководство по записи предлагает не менее 50 эпизодов для первой задачи, около 10 на каждое местоположение объекта. страницы политик перечисляют минимум для каждой модели, ниже которого запуск не стоит времени GPU.

Лучший вопрос — сколько чего. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 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

Два пути к одному и тому же набору данных

От набора данных к политике

Пятьдесят чистых эпизодов питают каждый обучение с имитацией запуск здесь. ACT обучается с нуля только на вашей задаче, около 80 млн параметров при примерно 20 мс на шаг действия, единственный из пяти, комфортно работающий с быстрым движением. SmolVLA имеет около 450 млн параметров на карте 24 ГБ. GR00T N1.7 — это базовая модель с примерно 3 млрд параметров, где дообучение затрагивает около 40 млн параметров, требует A100 или H100 и нуждается в наборе данных v2.1.

Далее, руководство для вашей комбинации: ACT на SO-100, SmolVLA на SO-100 или GR00T N1.7 на SO-100; для первого запуска обучите свою первую политику короче. Если политика работает на стенде, но рушится в тот момент, когда вы двигаете стол, это проблема с данными: политика работает только в одной конфигурации и сбор высококачественных обучающих данных VLA углубляются в вопросы разнообразия.