Nahrajte svoj prvý dataset LeRobot s SO-100

Sledovač SO-100, vedúce rameno rovnakého dizajnu a dve USB kamery dokážu doladiť politiku za jedno popoludnie. Rovnaká testovacia stolica dokáže rovnako ľahko vyprodukovať šesťdesiat epizód, ktoré vyzerajú zdravo v prehliadači súborov a premárniť šesťhodinový beh GPU. Rozdiel je zriedka v modeli; je to to, čo sa stalo medzi servami a súborom parquet.

Tu je manuálna cesta, potom tá kratšia. Každý príkaz je z lerobot 0.6.1, vydaného 3. augusta 2026 a aktuálneho na PyPI. Presunul sa na vstupné body konzoly, takže tutoriály, ktoré spúšťajú python lerobot/scripts/control_robot.py popisujú súbor, ktorý už neexistuje.

Čo zachytáva nahrávacia relácia

Dátový súbor LeRobot dataset nie je priečinok videí, ale časovo indexovaná tabuľka s priloženým videom: každý takt riadiacej slučky zapíše jeden riadok obsahujúci príkazovú akciu, stav, ktorý dosiahol sledovač, jeden snímok z každej kamery, časovú značku a indexy. Politika vidí iba tieto stĺpce. Schéma lerobot/svla_so100_pickplace, načítaná z jeho meta/info.json.

Kĺby sú main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll a main_gripper: šesť stupňov voľnosti SO-100. Akcia a stav zdieľajú rovnaký tvar, pretože teleoperácia líder-sledovač zaznamenáva cieľ a polohu dosiahnutú o jeden krok neskôr. Táto medzera je informácia: kde rameno bojovalo s gravitáciou alebo zaseknutým objektom. Tieto reťazce patria k danému dátovému súboru. Relácia zaznamenaná dnes s verziou 0.6.1 zapisuje shoulder_pan.pos až po gripper.pos, ID 1 až 6 na zbernici: rovnakých šesť kĺbov, rôzne kľúče, čo je dôležité v momente, keď konfigurácia odkazuje na funkciu podľa názvu.

Čo potrebujete na stole

Ak rameno ešte nie je zostavené, to je samostatný večer: začnite na a . Ak ste si ešte nič nekúpili, prečítajte si najprv : SO-101 je novšia revízia s vylepšenou kabelážou a bez kroku odstraňovania prevodov, a pracovný postup nahrávania je identický.

Nainštalujte 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

Doplnky najčastejšie spôsobujú problémy. pip install lerobot inštaluje iba základné ML závislosti, nič, čo komunikuje s robotom. Ramená Koch potrebujú dynamixel namiesto feetech. Ak váš shell nikdy nepočul o lerobot-record, toto je dôvod.

Porty, ID motorov a kalibrácia

Tri jednorazové kroky stoja medzi dielmi a funkčnou teleoperačnou slučkou. umožňuje, aby politika trénovaná na vašom ramene bežala na ramene niekoho iného, mapujúc surové počty enkodérov na zdieľanú konvenciu kĺbov.

1. 1
   Nájdite USB port každého ramena

   Spustite ho s oboma ramenami zapojenými, odpojte to, ktoré identifikujete, keď budete vyzvaní, a poznačte si, ktorý port zmizne. Na Linuxe možno budete potrebovať 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
   Zapíšte ID motorov a prenosové rýchlosti

   ID sa zapisujú pre každý motor zvlášť a dokumentácia je prísna ohľadom postupu: pripojte presne jeden motor k riadiacej doske, ešte nie zapojený do reťazca s inými. Skript prechádza reťazec dozadu, najprv vyzve na uchopovač a pridelí mu ID 6, potom zápästie (wrist_roll) ako 5, až po ramenný kĺb (shoulder_pan) ako 1. Urobte to pred montážou.

   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
   Kalibrujte obe ramená

   Posuňte každý kĺb do stredu jeho rozsahu, stlačte Enter a potom prejdite každý kĺb celým jeho rozsahom. id sa stane názvom súboru profilu.

   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
   Teleoperujte pred nahrávaním čohokoľvek

   Akceptačný test pre všetko vyššie uvedené. Ak je teleoperácia trhavá, zrkadlová alebo jeden kĺb nebude nasledovať, nahrávanie to zachová v 50 epizódach.

   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

Kamery rozhodujú o tom, čo vidí politika

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

Dva pohľady a ich umiestnenie sú dôležité: pevná scéna kamera pokrývajúca pracovný priestor a zápästná kamera blízko koncového efektora ukazujúca, čo sa chystá uchopovač dotknúť. Kontrolný zoznam komunitných dátových sád LeRobot vyžaduje prednostne dva pohľady s rozlíšením 480x640 / 720p alebo lepším, statické pozadie, neutrálne stabilné osvetlenie a rameno lídra a ľudské končatiny mimo záberu. Sprievodca nahrávaním dodáva pravidlo: mali by ste byť schopní vykonať úlohu sami len pohľadom na obrázky z kamery.

Príkaz record a všetky príznaky

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

Predvolené hodnoty nižšie pochádzajú z src/lerobot/configs/dataset.py, z hlavnej vetvy, nie z tutoriálu. Niektoré nie sú také, aké si ľudia myslia.

Ovládanie klávesnicou počas relácie

• Pravá šípka alebo n: ukončenie epizódy alebo predčasné resetovanie fázy. Kláves, ktorý používate najčastejšie, pretože čisté uchopenie zriedka potrebuje 25 sekúnd.
• Ľavá šípka alebo r: zahodenie epizódy a jej opakovanie. Zlý záber nestojí teraz nič a neskôr veľa.
• Escape alebo q: zastavenie relácie, dokončenie kódovania, nahranie.
• Tieto fungujú na X11, Wayland a bezhlavom SSH: bez globálneho backendu klávesov lerobot-record číta rovnaké klávesy z riadiaceho terminálu. Písmená prežijú pomalé SSH spojenia, kde sa sekvencie šípok rozdelia.
• Klávesnicová teleoperácia je iná a vyžaduje globálny backend: X11, Windows alebo macOS s funkciami prístupnosti.

Koľko epizód a ako vyzerá dobrá epizóda

Sprievodca nahrávaním odporúča aspoň 50 epizód pre prvú úlohu, približne 10 na umiestnenie objektu. stránky s politikami uvádzajú minimum pre každý model, pod ktorým sa spustenie neoplatí z hľadiska času GPU.

Lepšia otázka je, koľko čoho. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) zhromaždili viac ako 40 000 demonštrácií a vykonali viac ako 15 000 reálnych spustení. Generalizácia sledovala približne mocninový vzťah s počtom prostredí a objektov, a po prekročení prahu pre každé prostredie alebo objekt mali dodatočné demonštrácie minimálny účinok. Na jednom testovacom stole: presuňte objekt, zmeňte osvetlenie, vymeňte kocku, namiesto opakovania jedného záberu.

Dobrá epizóda je nudná: opakovateľná domáca pozícia, jedna vec hotová, ukončená, keď je objekt v koši, reťazec úlohy v rozsahu 25 až 50 znakov, ktoré odporúča kontrolný zoznam. Zoberte červenú kocku a vložte ju do krabice je reťazec úlohy; task1 je anti-vzor, ktorý kontrolný zoznam výslovne uvádza. Nejasné anotácie vedú zoznam problémov a sú najdôležitejšie pre , kde je reťazec vstupom modelu, nie názvom súboru.

Defekty, ktoré potichu ničia dátový súbor

Žiadny nevyvolá výnimku. Všetky prežijú do tréningu, objavia sa ako krivka straty, ktorá vyzerá dobre, a robot, ktorý nič nerobí. Skontrolujte, kým je scéna nastavená.

Jedna výhrada: tabuľka sprievodcu streamovaním a kódovaním uvádza predvolenú hodnotu ako True, zatiaľ čo dátová trieda na main číta streaming_encoding: bool = False. Dokumentácia a kód sa nezhodujú, takže to nastavte explicitne; lerobot zaznamená nápovedu odporúčajúcu to vždy, keď sa spustí s vypnutým príznakom.

Skontrolujte dataset pred prenájmom GPU

Akceptačný test z dokumentácie: porovnajte dĺžku videa s dĺžkou epizódy, ktorú nahlásilo CLI, a potvrďte, že počet riadkov sa rovná fps krát dĺžka. Na epizódu, nie na celok.

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

Potom sa na to pozrite. lerobot-dataset-viz prehráva epizódu snímku po snímke so stopami kĺbov vedľa pohľadov kamery, v Rerun alebo Foxglove. Vymenené kamery a zamrznuté snímky sa objavia do desiatich sekúnd. Ľudia tento krok preskakujú.

# 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 alebo v3.0: rozhodnite sa pred nahrávaním

v2.1 zapisoval jeden parquet a jeden MP4 na epizódu. v3.0 spája mnoho epizód do zdieľaných shardov a obnovuje hranice z metadát, takže info.json obsahuje šablóny ciest ako data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet namiesto čísla epizódy. Zdôvodnením je menej, väčších súborov: rýchlejšia inicializácia a menší tlak na súborový systém vo veľkom meradle.

# 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

Dve cesty k rovnakému datasetu

Od datasetu k politike

Päťdesiat čistých epizód napája každý beh tu. trénuje od nuly len na vašej úlohe, približne 80 M parametrov pri zhruba 20 ms na akčný krok, jediný z piatich, ktorému vyhovuje rýchly pohyb. má približne 450 M parametrov na 24 GB karte. je základný model s približne 3 B parametrami, kde ovplyvňuje asi 40 M parametrov, potrebuje A100 alebo H100 a vyžaduje dataset v2.1.

Ďalej, sprievodca pre vašu kombináciu: , alebo ; pre prvý beh je kratšie. Keď politika funguje na stole, ale zlyhá vo chvíli, keď pohnete stolom, je to problém s dátami: a idú hlbšie do rozmanitosti.