Înregistrează Primul Tău Set de Date LeRobot cu un SO-100

Un SO-100 follower, un braț lider de același design și două camere USB pot ajusta fin o politică într-o după-amiază. Același banc de lucru poate produce la fel de ușor șaizeci de episoade care arată bine într-un explorator de fișiere și poate irosi o rulare GPU de șase ore. Diferența este rar modelul; este ceea ce s-a întâmplat între servomotoare și fișierul parquet.

Iată ruta manuală, apoi cea mai scurtă. Fiecare comandă este din lerobot 0.6.1, lansat pe 3 august 2026 și actual pe PyPI. S-a mutat la puncte de intrare în consolă, așa că tutorialele care rulează python lerobot/scripts/control_robot.py descriu un fișier care nu mai există.

Ce captează o sesiune de înregistrare

Un set de date LeRobot nu este un folder de videoclipuri, ci un tabel indexat temporal cu videoclipuri atașate: fiecare ciclu de control scrie un rând care conține acțiunea comandată, starea atinsă de urmăritor, un cadru per cameră, un marcaj temporal și indici. Politica vede doar aceste coloane. Schema lerobot/svla_so100_pickplace, citită din meta/info.json.

Articulațiile sunt main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll și main_gripper: cele șase grade de libertate ale SO-100. Acțiunea și starea partajează o formă deoarece teleoperarea lider-urmăritor înregistrează o țintă și poziția atinsă un pas mai târziu. Acest decalaj este informație: unde brațul s-a luptat cu gravitația sau cu un obiect blocat. Aceste șiruri de caractere aparțin acelui set de date. O sesiune înregistrată cu 0.6.1 astăzi scrie shoulder_pan.pos până la gripper.pos, ID-uri de la 1 la 6 pe magistrală: aceleași șase articulații, chei diferite, ceea ce contează în momentul în care o configurație adresează o caracteristică după nume.

Ce ai nevoie pe bancul de lucru

Dacă brațul nu este încă construit, aceasta este o sarcină separată: începeți cu și . Dacă nu ați achiziționat nimic, citiți mai întâi : SO-101 este revizia mai nouă, cu cablaj îmbunătățit și fără etapa de îndepărtare a angrenajelor, iar fluxul de lucru de înregistrare este identic.

Instalați 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

Extra-urile îi încurcă cel mai mult pe oameni. pip install lerobot instalează doar dependențele ML de bază, nimic care să comunice cu un robot. Brațele Koch necesită dynamixel în loc de feetech. Dacă shell-ul dumneavoastră nu a auzit niciodată de lerobot-record, acesta este motivul.

Porturi, ID-uri motoare și calibrare

Trei pași unici stau între componente și o buclă de teleoperare funcțională. permite ca o politică antrenată pe brațul tău să ruleze pe brațul altcuiva, mapând citirile brute ale encoderului pe o convenție comună a articulațiilor.

1. 1
   Găsește portul USB al fiecărui braț

   Rulează-l cu ambele brațe conectate, deconectează-l pe cel pe care îl identifici când ți se cere și notează ce port dispare. Pe Linux s-ar putea să ai nevoie de 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
   Scrie ID-urile motoarelor și ratele de transfer

   ID-urile sunt scrise câte un motor pe rând, iar documentația este strictă în privința modului: conectează exact un motor la placa de control, neconectat încă în serie cu altul. Scriptul parcurge lanțul înapoi, cerând mai întâi gripper-ul și dându-i ID-ul 6, apoi wrist_roll ca 5, până la shoulder_pan ca 1. Fă acest lucru înainte de asamblare.

   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
   Calibrează ambele brațe

   Mută fiecare articulație în mijlocul intervalului său, apasă Enter, apoi parcurge fiecare articulație pe întregul său interval. id devine numele fișierului de profil.

   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
   Teleoperează înainte de a înregistra orice

   Testul de acceptanță pentru tot ce este mai sus. Dacă teleoperarea este sacadată, oglindită sau o articulație nu urmează, înregistrarea păstrează acest lucru în 50 de episoade.

   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

Camerele decid ce vede politica

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

Două vizualizări, iar poziția lor contează: o cameră fixă de scenă care acoperă spațiul de lucru și o cameră de încheietură lângă efectorul final care arată ce urmează să atingă gripper-ul. Lista de verificare a seturilor de date ale comunității LeRobot solicită de preferință două vizualizări la 480x640 / 720p sau mai bune, un fundal static, iluminare neutră și stabilă, iar brațul lider și membrele umane să fie în afara cadrului. Ghidul de înregistrare adaugă o regulă generală: ar trebui să puteți îndeplini sarcina singur, doar privind imaginile camerei.

Comanda record și fiecare flag

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

Valorile implicite de mai jos provin din src/lerobot/configs/dataset.py din ramura main, nu dintr-un tutorial. Câteva nu sunt ceea ce presupun oamenii.

Controlul prin tastatură în timpul unei sesiuni

• Săgeată dreapta sau n: încheie episodul sau resetează faza mai devreme. Este tasta pe care o vei folosi cel mai mult, deoarece o prindere curată rareori necesită 25 de secunde.
• Săgeată stânga sau r: renunță la episod și reia-l. O înregistrare proastă nu costă nimic acum, dar poate costa mult mai târziu.
• Escape sau q: oprește sesiunea, finalizează codificarea, încarcă.
• Acestea funcționează pe X11, Wayland și SSH fără interfață grafică: fără un backend global pentru taste, lerobot-record citește aceleași taste de la terminalul de control. Literele rezistă legăturilor SSH lente, unde secvențele de săgeți se pot fragmenta.
• Teleoperarea prin tastatură este diferită și necesită un backend global: X11, Windows sau macOS cu Accesibilitate.

Câte episoade și cum arată un episod bun

Ghidul de înregistrare sugerează cel puțin 50 de episoade pentru o primă sarcină, aproximativ 10 per locație de obiect. Paginile de politici listează un minim per model, sub care o rulare nu merită timpul de GPU.

Întrebarea mai bună este câte din ce. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) au colectat peste 40.000 de demonstrații și au rulat peste 15.000 de execuții în lumea reală. Generalizarea a urmat o relație aproximativ de lege de putere cu numărul de medii și obiecte, iar după un prag per mediu sau obiect, demonstrațiile suplimentare au avut un efect minim. Pe un banc de lucru: mută obiectul, schimbă iluminarea, înlocuiește cubul, mai degrabă decât să repeți o singură înregistrare.

Un episod bun este plictisitor: poziție inițială repetabilă, un singur lucru realizat, încheiat odată ce obiectul este în coș, șirul de sarcini în cele 25 până la 50 de caractere recomandate de listă. Ridică cubul roșu și pune-l în cutie este un șir de sarcini; task1 este anti-modelul pe care lista îl menționează explicit. Anotările vagi se află în capul listei de probleme și sunt cele mai importante pentru modele de viziune-limbaj-acțiune, unde șirul este o intrare a modelului, nu un nume de fișier.

Defecte care ruinează în tăcere un set de date

Niciunul nu generează o excepție. Toate supraviețuiesc în timpul antrenamentului, apărând ca o curbă de pierdere care arată bine și un robot care nu face nimic. Verificați în timp ce scena este configurată.

O precizare: tabelul ghidului de streaming-encoding listează valoarea implicită ca fiind True, în timp ce dataclass-ul din main indică streaming_encoding: bool = False. Documentația și codul nu sunt de acord, așa că setați-o explicit; lerobot înregistrează o sugestie care o recomandă ori de câte ori pornește cu flag-ul dezactivat.

Verificați setul de date înainte de a închiria un GPU

Testul de acceptare din documentație: comparați durata video cu durata episodului raportată de CLI și confirmați că numărul de rânduri este egal cu fps ori durată. Pe episod, nu pe total.

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"])

Apoi, analizează-l. lerobot-dataset-viz redă un episod cadru cu cadru, cu urme ale articulațiilor lângă vizualizările camerei, în Rerun sau Foxglove. Camerele inversate și cadrele înghețate apar în zece secunde. Oamenii sar peste acest pas.

# 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 sau v3.0: decideți înainte de a înregistra

v2.1 a scris un fișier parquet și un fișier MP4 per episod. v3.0 concatenează multe episoade în fragmente partajate și reconstruiește limitele din metadate, astfel încât info.json conține șabloane de cale precum data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet în loc de un număr de episod. Justificarea din amonte este un număr mai mic de fișiere, dar mai mari: inițializare mai rapidă și presiune redusă asupra sistemului de fișiere la scară.

# 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

Două rute către același set de date

De la setul de date la politică

Cincizeci de episoade curate alimentează fiecare rulare aici. se antrenează de la zero doar pe sarcina dvs., cu aproximativ 80 M parametri la aproximativ 20 ms per pas de acțiune, fiind singurul dintre cele cinci confortabil cu mișcarea rapidă. are aproximativ 450 M parametri pe o placă de 24 GB. este un model fundamental cu aproximativ 3 B parametri unde atinge aproximativ 40 M parametri, necesită un A100 sau H100 și dorește acel set de date v2.1.

Apoi, ghidul pentru combinația dvs.: , sau ; pentru o primă rulare, este mai scurt. Când politica funcționează pe bancul de test, dar se prăbușește în momentul în care mutați masa, aceasta este o problemă de date: și aprofundează diversitatea.