Rekam Dataset LeRobot Pertama Anda Dengan SO-100

Sebuah SO-100 pengikut, lengan pemimpin dengan desain yang sama, dan dua kamera USB dapat menyempurnakan kebijakan dalam satu sore. Bangku yang sama dapat dengan mudah menghasilkan enam puluh episode yang terlihat sehat di penjelajah file dan menyia-nyiakan enam jam waktu GPU. Perbedaannya jarang pada model; melainkan apa yang terjadi antara servo dan file parquet.

Berikut adalah rute manual, lalu yang lebih pendek. Setiap perintah berasal dari lerobot 0.6.1, dirilis 3 Agustus 2026 dan terkini di PyPI. Ini beralih ke titik masuk konsol, jadi tutorial yang menjalankan python lerobot/scripts/control_robot.py menjelaskan file yang tidak lagi ada.

Apa yang ditangkap sesi perekaman

Sebuah dataset LeRobot bukanlah folder video melainkan tabel berindeks waktu dengan video terlampir: setiap detak loop kontrol menulis satu baris yang berisi tindakan yang diperintahkan, status yang dicapai pengikut, satu bingkai per kamera, stempel waktu, dan indeks. Kebijakan hanya melihat kolom-kolom tersebut. Skema lerobot/svla_so100_pickplace, dibaca dari meta/info.json-nya.

Sendi-sendinya adalah main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll, dan main_gripper: enam derajat kebebasan SO-100. Aksi dan status memiliki bentuk yang sama karena teleoperasi pemimpin-pengikut merekam target dan posisi yang dicapai satu langkah kemudian. Kesenjangan itu adalah informasi: di mana lengan melawan gravitasi atau objek yang macet. String-string tersebut adalah milik dataset itu. Sesi yang direkam dengan 0.6.1 hari ini menulis shoulder_pan.pos hingga gripper.pos, id 1 hingga 6 pada bus: enam sendi yang sama, kunci yang berbeda, yang penting saat konfigurasi mengatasi fitur berdasarkan nama.

Apa yang Anda butuhkan di meja kerja

Jika lengan belum dirakit, itu adalah pekerjaan terpisah untuk malam hari: mulailah dari memulai SO-100 dan panduan pengaturan SO-100 lengkap. Jika Anda belum membeli apa pun, baca perbandingan SO-100 dengan SO-101 terlebih dahulu: SO-101 adalah revisi yang lebih baru dengan pengkabelan yang ditingkatkan dan tanpa langkah pelepasan roda gigi, serta alur kerja perekaman yang identik.

Instal 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

Ekstra paling sering membingungkan orang. pip install lerobot hanya menginstal dependensi ML inti, tidak ada yang berkomunikasi dengan robot. Lengan Koch membutuhkan dynamixel alih-alih feetech. Jika shell Anda belum pernah mendengar tentang lerobot-record, inilah alasannya.

Port, ID motor, dan kalibrasi

Tiga langkah sekali jalan memisahkan komponen dari loop teleoperasi yang berfungsi. memungkinkan kebijakan yang dilatih pada lengan Anda berjalan pada lengan orang lain, memetakan hitungan encoder mentah ke konvensi sambungan bersama.

1. 1
   Temukan port USB setiap lengan

   Jalankan dengan kedua lengan terpasang, cabut lengan yang sedang Anda identifikasi saat diminta, dan catat port mana yang menghilang. Di Linux, Anda mungkin memerlukan 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
   Tulis ID motor dan baudrate

   ID ditulis satu motor pada satu waktu, dan dokumentasi sangat ketat tentang caranya: sambungkan tepat satu motor ke papan kontroler, belum dirangkai ke motor lain. Skrip akan menelusuri rantai secara terbalik, meminta gripper terlebih dahulu dan memberinya ID 6, lalu wrist_roll sebagai 5, hingga shoulder_pan sebagai 1. Lakukan ini sebelum perakitan.

   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
   Kalibrasi kedua lengan

   Gerakkan setiap sambungan ke tengah jangkauannya, tekan Enter, lalu sapukan setiap sambungan melalui jangkauan penuhnya. id akan menjadi nama file 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
   Teleoperasi sebelum merekam apa pun

   Uji penerimaan untuk semua hal di atas. Jika teleoperasi tersentak-sentak, tercermin, atau satu sambungan tidak mengikuti, perekaman akan mempertahankan hal tersebut dalam 50 episode.

   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

Kamera menentukan apa yang dilihat oleh kebijakan

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

Dua tampilan, dan posisinya penting: kamera pemandangan tetap yang mencakup ruang kerja, dan kamera pergelangan tangan di dekat ujung efektor menunjukkan apa yang akan disentuh oleh penjepit. Daftar periksa dataset komunitas LeRobot meminta sebaiknya dua tampilan pada 480x640 / 720p atau lebih baik, latar belakang statis, pencahayaan stabil netral, serta lengan pemimpin dan anggota tubuh manusia di luar bingkai. Panduan perekaman menambahkan aturan praktis: Anda harus dapat melakukan tugas itu sendiri hanya dengan melihat gambar kamera.

Perintah record dan setiap 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

Default di bawah berasal dari src/lerobot/configs/dataset.py, di main, bukan tutorial. Beberapa tidak seperti yang diasumsikan orang.

Kontrol keyboard selama sesi

• Panah kanan atau n: mengakhiri episode atau mengatur ulang fase lebih awal. Tombol yang paling sering Anda gunakan, karena genggaman yang bersih jarang membutuhkan 25 detik.
• Panah kiri atau r: membuang episode dan mengulanginya. Pengambilan yang buruk tidak merugikan sekarang dan banyak merugikan nanti.
• Escape atau q: menghentikan sesi, menyelesaikan encoding, mengunggah.
• Ini berfungsi di X11, Wayland, dan SSH tanpa kepala: tanpa backend kunci global, lerobot-record membaca kunci yang sama dari terminal pengendali. Huruf-huruf ini bertahan pada tautan SSH yang lambat, di mana urutan panah terpisah.
• Teleoperasi keyboard berbeda dan memang membutuhkan backend global: X11, Windows, atau macOS dengan Aksesibilitas.

Berapa banyak episode, dan seperti apa episode yang baik

Panduan perekaman menyarankan setidaknya 50 episode untuk tugas pertama, sekitar 10 per lokasi objek. Halaman kebijakan mencantumkan jumlah minimum per model, di bawah itu sebuah eksekusi tidak sepadan dengan waktu GPU.

Pertanyaan yang lebih baik adalah berapa banyak dari apa. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin dkk., 2024) mengumpulkan lebih dari 40.000 demonstrasi dan menjalankan lebih dari 15.000 rollout dunia nyata. Generalisasi mengikuti hubungan hukum pangkat secara kasar dengan jumlah lingkungan dan objek, dan melewati ambang batas per lingkungan atau objek, demonstrasi tambahan memiliki efek minimal. Pada satu bangku: pindahkan objek, ubah pencahayaan, tukar kubus, daripada mengulang satu pengambilan.

Episode yang baik itu membosankan: posisi awal yang dapat diulang, satu hal selesai, berakhir setelah objek berada di tempat sampah, string tugas dalam 25 hingga 50 karakter yang direkomendasikan daftar periksa. Ambil kubus merah dan jatuhkan ke dalam kotak adalah string tugas; task1 adalah anti-pola yang secara eksplisit disebutkan dalam daftar periksa. Anotasi yang tidak jelas menduduki daftar masalahnya, dan itu paling penting untuk model visi-bahasa-aksi, di mana string adalah masukan model, bukan nama file.

Cacat yang diam-diam merusak dataset

Tidak ada yang memicu pengecualian. Semua bertahan hingga pelatihan, muncul sebagai kurva kerugian yang terlihat baik dan robot yang tidak melakukan apa-apa. Periksa saat adegan sedang disiapkan.

Satu peringatan: tabel panduan streaming-encoding mencantumkan default sebagai True, sementara dataclass di main membaca streaming_encoding: bool = False. Dokumen dan kode tidak setuju, jadi atur secara eksplisit; lerobot mencatat petunjuk yang merekomendasikannya setiap kali dimulai dengan flag mati.

Periksa dataset sebelum menyewa GPU

Uji penerimaan dari dokumen: bandingkan durasi video dengan durasi episode yang dilaporkan CLI, dan konfirmasikan jumlah baris sama dengan fps dikalikan durasi. Per episode, bukan pada 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"])

Lalu lihatlah. lerobot-dataset-viz memutar ulang sebuah episode bingkai demi bingkai dengan jejak sendi di samping tampilan kamera, di Rerun atau Foxglove. Kamera yang tertukar dan bingkai yang beku akan terlihat dalam sepuluh detik. Orang-orang melewatkan langkah ini.

# 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 atau v3.0: putuskan sebelum merekam

v2.1 menulis satu parquet dan satu MP4 per episode. v3.0 menggabungkan banyak episode ke dalam shard bersama dan membangun kembali batas dari metadata, sehingga info.json membawa template jalur seperti data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet alih-alih nomor episode. Justifikasi hulu adalah file yang lebih sedikit dan lebih besar: inisialisasi lebih cepat dan tekanan sistem file lebih rendah pada skala.

# 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

Dua rute ke dataset yang sama

Dari dataset ke kebijakan

Lima puluh episode bersih menjadi masukan setiap yang dijalankan di sini. dilatih dari awal hanya untuk tugas Anda, sekitar 80 juta parameter dengan kira-kira 20 ms per langkah tindakan, satu-satunya dari lima yang nyaman dengan gerakan cepat. memiliki sekitar 450 juta parameter pada kartu 24 GB. adalah model dasar dengan sekitar 3 miliar parameter di mana menyentuh sekitar 40 juta parameter, membutuhkan A100 atau H100, dan menginginkan dataset v2.1 tersebut.

Selanjutnya, panduan untuk kombinasi Anda: , atau ; untuk percobaan pertama, lebih singkat. Ketika kebijakan berfungsi di bangku uji tetapi gagal saat Anda menggerakkan meja, itu adalah masalah data: dan membahas lebih dalam tentang keragaman.