Nagraj swój pierwszy zbiór danych LeRobot z SO-100

Podążający za SO-100 podążający, ramię wiodące o tej samej konstrukcji i dwie kamery USB mogą dopracować politykę w jedno popołudnie. To samo stanowisko może równie łatwo wyprodukować sześćdziesiąt epizodów, które wyglądają zdrowo w przeglądarce plików i zmarnować sześciogodzinne uruchomienie GPU. Różnica rzadko tkwi w modelu; to, co wydarzyło się między serwami a plikiem parquet.

Oto ścieżka ręczna, a następnie krótsza. Każde polecenie pochodzi z lerobot 0.6.1, wydanego 3 sierpnia 2026 i aktualnego na PyPI. Przeniesiono je do punktów wejścia konsoli, więc samouczki, które uruchamiają python lerobot/scripts/control_robot.py opisują plik, który już nie istnieje.

Co rejestruje sesja nagrywania

Zbiór danych LeRobot nie jest folderem filmów, lecz tabelą indeksowaną czasowo z dołączonym wideo: każde taktowanie pętli sterowania zapisuje jeden wiersz zawierający zadane działanie, stan osiągnięty przez naśladowcę, jedną klatkę z każdej kamery, znacznik czasu i indeksy. Polityka widzi tylko te kolumny. Schemat lerobot/svla_so100_pickplace, odczytany z jego meta/info.json.

Stawy to main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll i main_gripper: sześć stopni swobody SO-100. Akcja i stan mają ten sam kształt, ponieważ teleoperacja lider-naśladowca rejestruje cel i pozycję osiągniętą jeden krok później. Ta luka to informacja: gdzie ramię walczyło z grawitacją lub zablokowanym obiektem. Te ciągi znaków należą do tego zbioru danych. Sesja nagrana dzisiaj z wersją 0.6.1 zapisuje shoulder_pan.pos przez gripper.pos, identyfikatory od 1 do 6 na magistrali: te same sześć stawów, różne klucze, co ma znaczenie w momencie, gdy konfiguracja odwołuje się do cechy po nazwie.

Co potrzebujesz na stanowisku

Jeśli ramię nie jest jeszcze zbudowane, to jest to osobny wieczór: zacznij od Rozpoczęcie pracy z SO-100 i kompletnego przewodnika konfiguracji SO-100. Jeśli jeszcze nic nie kupiłeś, przeczytaj najpierw porównanie SO-100 z SO-101: SO-101 to nowsza wersja z ulepszonym okablowaniem i bez etapu demontażu przekładni, a proces nagrywania jest identyczny.

Zainstaluj 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

Dodatki najczęściej sprawiają ludziom kłopoty. pip install lerobot instaluje tylko podstawowe zależności ML, nic, co komunikuje się z robotem. Ramiona Koch potrzebują dynamixel zamiast feetech. Jeśli twoja powłoka nigdy nie słyszała o lerobot-record, to dlatego.

Porty, identyfikatory silników i kalibracja

Trzy jednorazowe kroki dzielą części od działającej pętli teleoperacji. sprawia, że polityka wytrenowana na twoim ramieniu działa na ramieniu kogoś innego, mapując surowe odczyty enkodera na wspólną konwencję stawów.

1. 1
   Znajdź port USB każdego ramienia

   Uruchom go z podłączonymi obydwoma ramionami, odłącz to, które identyfikujesz, gdy zostaniesz o to poproszony, i zanotuj, który port znika. W systemie Linux może być konieczne użycie 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
   Zapisz identyfikatory silników i prędkości transmisji

   Identyfikatory są zapisywane dla każdego silnika pojedynczo, a dokumentacja jest rygorystyczna co do sposobu: podłącz dokładnie jeden silnik do płyty kontrolera, jeszcze nie połączony szeregowo z żadnym innym. Skrypt przechodzi łańcuch wstecz, najpierw prosząc o chwytak i nadając mu id 6, następnie wrist_roll jako 5, aż do shoulder_pan jako 1. Zrób to przed montażem.

   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
   Skalibruj oba ramiona

   Przesuń każdy staw do środka jego zakresu, naciśnij Enter, a następnie przesuń każdy przez cały jego zakres. id staje się nazwą pliku 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
   Teleoperuj przed nagraniem czegokolwiek

   Test akceptacyjny dla wszystkiego powyżej. Jeśli teleoperacja jest szarpana, lustrzana lub jeden staw nie podąża, nagrywanie zachowuje to w 50 epizodach.

   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 decydują o tym, co widzi polityka

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

Dwa widoki i ich umiejscowienie ma znaczenie: stała kamera sceniczna obejmująca przestrzeń roboczą oraz kamera nadgarstkowa w pobliżu efektora końcowego pokazująca, czego chwytak ma dotknąć. Lista kontrolna LeRobot dla zestawów danych społeczności wymaga preferencyjnie dwóch widoków w rozdzielczości 480x640 / 720p lub lepszej, statycznego tła, neutralnego stabilnego oświetlenia oraz ramienia lidera i ludzkich kończyn poza kadrem. Przewodnik nagrywania dodaje zasadę kciuka: powinieneś być w stanie wykonać zadanie samodzielnie, patrząc tylko na obrazy z kamery.

Polecenie record i każda flaga

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

Poniższe wartości domyślne pochodzą z src/lerobot/configs/dataset.py w gałęzi main, a nie z samouczka. Kilka z nich nie jest tym, co ludzie zakładają.

Sterowanie klawiaturą podczas sesji

• Prawa strzałka lub n: zakończ epizod lub wcześnie zresetuj fazę. To klawisz, którego używasz najczęściej, ponieważ czyste chwycenie rzadko wymaga 25 sekund.
• Lewa strzałka lub r: odrzuć epizod i powtórz go. Złe ujęcie nic nie kosztuje teraz, a dużo później.
• Escape lub q: zatrzymaj sesję, zakończ kodowanie, prześlij.
• Działają one na X11, Wayland i bezgłowym SSH: bez globalnego zaplecza klawiszy, lerobot-record odczytuje te same klawisze z terminala sterującego. Litery przetrwają opóźnione połączenia SSH, gdzie sekwencje strzałek się rozdzielają.
• Klawiaturowa teleoperacja jest inna i wymaga globalnego zaplecza: X11, Windows lub macOS z ułatwieniami dostępu.

Ile epizodów i jak wygląda dobry

Przewodnik nagrywania sugeruje co najmniej 50 epizodów dla pierwszego zadania, około 10 na lokalizację obiektu. Strony zasad wymieniają minimum dla każdego modelu, poniżej którego uruchomienie nie jest warte czasu GPU.

Lepsze pytanie brzmi: ile czego. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin i in., 2024) zebrali ponad 40 000 demonstracji i przeprowadzili ponad 15 000 rzeczywistych uruchomień. Generalizacja wykazywała w przybliżeniu zależność potęgową z liczbą environments and objects, a po przekroczeniu progu dla środowiska lub obiektu, dodatkowe demonstracje miały minimalny wpływ. Na jednym stanowisku: przesuń obiekt, zmień oświetlenie, zamień kostkę, zamiast powtarzać jedno ujęcie.

Dobry epizod jest nudny: powtarzalna pozycja początkowa, jedna rzecz wykonana, zakończony, gdy obiekt znajdzie się w pojemniku, ciąg zadania w zakresie 25 do 50 znaków zalecanych przez listę kontrolną. Podnieś czerwony sześcian i upuść go do pudełka to ciąg zadania; task1 to antywzorzec, który lista kontrolna wyraźnie wymienia. Nieprecyzyjne adnotacje otwierają listę problemów i są najważniejsze dla modelów wizualno-językowo-akcyjnych, gdzie ciąg jest wejściem modelu, a nie nazwą pliku.

Wady, które po cichu niszczą zbiór danych

Żaden nie zgłasza wyjątku. Wszystkie przechodzą do treningu, objawiając się jako krzywa strat, która wygląda dobrze, i robot, który nic nie robi. Sprawdź, gdy scena jest ustawiona.

Jedna uwaga: tabela w przewodniku po strumieniowym kodowaniu podaje domyślną wartość jako True, podczas gdy klasa danych w głównym kodzie odczytuje streaming_encoding: bool = False. Dokumentacja i kod są niezgodne, więc ustaw to jawnie; lerobot loguje wskazówkę zalecającą to za każdym razem, gdy uruchamia się z wyłączoną flagą.

Sprawdź zbiór danych przed wynajęciem GPU

Test akceptacyjny z dokumentacji: porównaj czas trwania wideo z czasem trwania epizodu zgłoszonym przez CLI i potwierdź, że liczba wierszy jest równa fps razy czas trwania. Na epizod, nie na całość.

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

Następnie przyjrzyj się temu. lerobot-dataset-viz odtwarza epizod klatka po klatce, z widokami z kamer i śladami połączeń, w Rerun lub Foxglove. Zamienione kamery i zamrożone klatki pojawiają się w ciągu dziesięciu sekund. Ludzie pomijają ten krok.

# 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 lub v3.0: zdecyduj przed nagraniem

v2.1 zapisywał jeden plik parquet i jeden MP4 na odcinek. v3.0 łączy wiele odcinków w wspólne fragmenty (shards) i odbudowuje granice z metadanych, więc info.json zawiera szablony ścieżek, takie jak data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet zamiast numeru odcinka. Uzasadnieniem jest mniejsza liczba większych plików: szybsza inicjalizacja i mniejsze obciążenie systemu plików na dużą skalę.

# 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

Dwie drogi do tego samego zbioru danych

Od zbioru danych do polityki

Pięćdziesiąt czystych epizodów zasila każde uruchomienie tutaj. trenuje od zera na samym Twoim zadaniu, około 80 milionów parametrów przy około 20 ms na krok akcji, jedyny z pięciu radzący sobie z szybkim ruchem. ma około 450 milionów parametrów na karcie 24 GB. to model bazowy o około 3 miliardach parametrów, gdzie dotyka około 40 milionów parametrów, wymaga A100 lub H100 i potrzebuje tego zbioru danych v2.1.

Następnie, przewodnik dla Twojej kombinacji: , lub ; dla pierwszego uruchomienia, jest krótszy. Kiedy polityka działa na stole laboratoryjnym, ale załamuje się w momencie, gdy przesuniesz stół, to jest problem z danymi: i zagłębiają się w kwestię różnorodności.