Запишете първия си 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 като 5, до shoulder_pan като 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, докато класът за данни в main чете streaming_encoding: bool = False. Документацията и кодът не съвпадат, затова го задайте изрично; lerobot записва подсказка, препоръчваща това, когато стартира с изключен флаг.

Проверете набора от данни, преди да наемете GPU

Приемственият тест от документацията: сравнете продължителността на видеото с продължителността на епизода, докладвана от CLI, и потвърдете, че броят на редовете е равен на fps по продължителността. За всеки епизод, не за общата сума.

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 милиона параметъра при приблизително 20 ms на стъпка на действие, единственият от петте, който е удобен за бързо движение. е около 450 милиона параметъра на 24 GB карта. е приблизително 3 милиарда параметъра базов модел, където засяга около 40 милиона параметъра, изисква A100 или H100 и иска този набор от данни v2.1.

Следва ръководството за вашата комбинация: , или ; за първо изпълнение, е по-кратко. Когато политиката работи на стенда, но се срива в момента, в който преместите масата, това е проблем с данните: и навлизат по-дълбоко в разнообразието.