Registra il tuo primo dataset LeRobot con un SO-100

Un SO-100 follower, un braccio leader dello stesso design e due telecamere USB possono mettere a punto una policy in un pomeriggio. Lo stesso banco può altrettanto facilmente produrre sessanta episodi che sembrano sani in un browser di file e sprecare un'esecuzione GPU di sei ore. La differenza è raramente il modello; è ciò che è successo tra i servi e il file parquet.

Ecco il percorso manuale, poi quello più breve. Ogni comando proviene da lerobot 0.6.1, rilasciato il 3 agosto 2026 e attuale su PyPI. Si è spostato ai punti di ingresso della console, quindi i tutorial che eseguono python lerobot/scripts/control_robot.py descrivono un file che non esiste più.

Cosa cattura una sessione di registrazione

Un dataset LeRobot non è una cartella di video ma una tabella indicizzata nel tempo con video allegati: ogni tick del ciclo di controllo scrive una riga contenente l'azione comandata, lo stato raggiunto dal follower, un frame per telecamera, un timestamp e gli indici. La policy vede solo quelle colonne. Lo schema di lerobot/svla_so100_pickplace, letto dal suo meta/info.json.

Le giunture sono main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll e main_gripper: i sei gradi di libertà del SO-100. Azione e stato condividono una forma perché la teleoperazione leader-follower registra un target e la posizione raggiunta un passo dopo. Quel divario è informazione: dove il braccio ha combattuto la gravità o un oggetto bloccato. Quelle stringhe sono del dataset. Una sessione registrata con 0.6.1 oggi scrive shoulder_pan.pos fino a gripper.pos, ID da 1 a 6 sul bus: le stesse sei giunture, chiavi diverse, il che è importante nel momento in cui una configurazione si riferisce a una caratteristica per nome.

Cosa serve sul banco

Se il braccio non è ancora stato costruito, quella è una serata a parte: inizia da Introduzione a SO-100 e la guida completa all'installazione di SO-100. Se non hai ancora acquistato nulla, leggi prima il confronto tra SO-100 e SO-101 per primo: l'SO-101 è la revisione più recente con cablaggio migliorato e senza il passaggio di rimozione degli ingranaggi, e il flusso di lavoro di registrazione è identico.

Installa 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

Gli extra sono ciò che confonde di più le persone. pip install lerobot installa solo le dipendenze ML principali, nulla che comunichi con un robot. I bracci Koch necessitano di dynamixel invece di feetech. Se la tua shell non ha mai sentito parlare di lerobot-record, questo è il motivo.

Porte, ID motore e calibrazione

Tre passaggi unici si frappongono tra i componenti e un ciclo di teleoperazione funzionante. permette a una policy addestrata sul tuo braccio di funzionare su quello di qualcun altro, mappando i conteggi grezzi dell'encoder su una convenzione di giunto condivisa.

1. 1
   Trova la porta USB di ciascun braccio

   Eseguilo con entrambi i bracci collegati, scollega quello che stai identificando quando richiesto e annota quale porta scompare. Su Linux potrebbe essere necessario 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
   Scrivi gli ID motore e i baudrate

   Gli ID vengono scritti un motore alla volta, e la documentazione è rigorosa su come: collega esattamente un motore alla scheda controller, non ancora collegato in cascata ad altri. Lo script percorre la catena all'indietro, chiedendo prima la pinza e assegnandole l'ID 6, poi il polso (wrist_roll) come 5, fino alla spalla (shoulder_pan) come 1. Eseguilo prima dell'assemblaggio.

   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
   Calibra entrambi i bracci

   Sposta ogni giunto al centro del suo intervallo, premi Invio, quindi muovi ciascuno lungo il suo intero intervallo. L'id diventa il nome del file del profilo.

   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
   Teleopera prima di registrare qualsiasi cosa

   Il test di accettazione per tutto quanto sopra. Se la teleoperazione è a scatti, specchiata, o un giunto non segue, la registrazione lo conserva in 50 episodi.

   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

Le telecamere decidono cosa vede la policy

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

Due viste, e la loro posizione è importante: una telecamera fissa sulla scena che copre l'area di lavoro, e una telecamera da polso vicino all'effettore finale che mostra ciò che la pinza sta per toccare. La checklist dei dataset della comunità LeRobot richiede preferibilmente due viste a 480x640 / 720p o superiori, uno sfondo statico, un'illuminazione neutra e stabile, e il braccio del leader e gli arti umani fuori dall'inquadratura. La guida alla registrazione aggiunge la regola pratica: dovresti essere in grado di svolgere il compito tu stesso guardando solo le immagini della telecamera.

Il comando record e ogni 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

I valori predefiniti di seguito provengono da src/lerobot/configs/dataset.py su main, non da un tutorial. Molti non sono ciò che le persone presumono.

Controllo da tastiera durante una sessione

• Freccia destra o n: termina l'episodio o la fase di reset in anticipo. Il tasto che userai di più, perché una presa pulita raramente richiede 25 secondi.
• Freccia sinistra o r: scarta l'episodio e rifallo. Una cattiva ripresa non costa nulla ora e molto più tardi.
• Escape o q: ferma la sessione, termina la codifica, carica.
• Questi funzionano su X11, Wayland e SSH headless: senza un backend di tasti globale, lerobot-record legge gli stessi tasti dal terminale di controllo. Le lettere sopravvivono a collegamenti SSH lenti, dove le sequenze di frecce si dividono.
• La teleoperazione da tastiera è diversa e richiede un backend globale: X11, Windows o macOS con Accessibilità.

Quanti episodi, e come si presenta uno buono

La guida alla registrazione suggerisce almeno 50 episodi per un primo compito, circa 10 per posizione dell'oggetto. Le pagine delle policy elencano un minimo per modello, al di sotto del quale un'esecuzione non vale il tempo della GPU.

La domanda migliore è quanti di cosa. Leggi di Scala dei Dati nell'Apprendimento per Imitazione per la Manipolazione Robotica (Lin et al., 2024) hanno raccolto oltre 40.000 dimostrazioni e eseguito più di 15.000 rollouts nel mondo reale. La generalizzazione ha seguito una relazione approssimativamente di legge di potenza con il numero di ambienti e oggetti, e superata una soglia per ambiente o oggetto, dimostrazioni aggiuntive hanno avuto un effetto minimo. Su un banco: sposta l'oggetto, cambia l'illuminazione, scambia il cubo, piuttosto che ripetere una singola ripresa.

Un buon episodio è noioso: posa iniziale ripetibile, una cosa fatta, terminato una volta che l'oggetto è nel contenitore, stringa del compito tra i 25 e i 50 caratteri raccomandati dalla checklist. Prendi il cubo rosso e lascialo cadere nella scatola è una stringa di compito; task1 è l'anti-pattern che la checklist nomina esplicitamente. Le annotazioni vaghe sono in cima alla sua lista di problemi, e sono più importanti per , dove la stringa è un input del modello, non un nome di file.

Difetti che rovinano silenziosamente un dataset

Nessuno genera un'eccezione. Tutti sopravvivono all'addestramento, emergendo come una curva di perdita che sembra a posto e un robot che non fa nulla. Controllare mentre la scena è allestita.

Un'avvertenza: la tabella della guida alla codifica in streaming elenca il valore predefinito come True, mentre la dataclass su main legge streaming_encoding: bool = False. Documentazione e codice non concordano, quindi impostalo esplicitamente; lerobot registra un suggerimento che lo raccomanda ogni volta che si avvia con il flag disattivato.

Controlla il dataset prima di noleggiare una GPU

Il test di accettazione dalla documentazione: confronta la durata del video con la durata dell'episodio riportata dalla CLI e conferma che il numero di righe è uguale a fps per durata. Per episodio, non sul totale.

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

Poi guardalo. lerobot-dataset-viz riproduce un episodio fotogramma per fotogramma con tracce articolari accanto alle viste della telecamera, in Rerun o Foxglove. Telecamere scambiate e fotogrammi congelati appaiono in dieci secondi. Le persone saltano questo passaggio.

# 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 o v3.0: decidi prima di registrare

v2.1 scriveva un file parquet e un MP4 per episodio. v3.0 concatena molti episodi in shard condivisi e ricostruisce i confini dai metadati, quindi info.json contiene modelli di percorso come data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet invece di un numero di episodio. La giustificazione a monte è un numero inferiore di file più grandi: inizializzazione più rapida e minore pressione sul file system su larga scala.

# 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

Due percorsi allo stesso dataset

Dal dataset alla policy

Cinquanta episodi puliti alimentano ogni esecuzione di apprendimento per imitazione qui. ACT si addestra da zero solo sul vostro compito, circa 80 M parametri a circa 20 ms per passo d'azione, l'unico dei cinque a suo agio con il movimento rapido. SmolVLA è di circa 450 M parametri su una scheda da 24 GB. GR00T N1.7 è un modello di base di circa 3 B parametri dove il fine-tuning tocca circa 40 M parametri, necessita di una A100 o H100 e richiede quel dataset v2.1.

Successivamente, la guida per la vostra combinazione: ACT su SO-100, SmolVLA su SO-100 o GR00T N1.7 su SO-100; per una prima esecuzione, addestrare la vostra prima policy è più breve. Quando la policy funziona sul banco ma collassa nel momento in cui si sposta il tavolo, si tratta di un problema di dati: la policy funziona solo in una configurazione e la raccolta di dati di addestramento VLA di alta qualità approfondiscono la diversità.