Rakam Dataset LeRobot Pertama Anda Dengan SO-100

Pengikut SO-100, lengan pemimpin dengan reka bentuk yang sama dan dua kamera USB boleh memperhalusi polisi dalam masa sehari. Meja kerja yang sama boleh dengan mudah menghasilkan enam puluh episod yang kelihatan sihat dalam pelayar fail dan membazirkan larian GPU enam jam. Perbezaannya jarang sekali model; ia adalah apa yang berlaku antara servo dan fail parquet.

Berikut adalah laluan manual, kemudian yang lebih pendek. Setiap arahan adalah daripada lerobot 0.6.1, dikeluarkan pada 3 Ogos 2026 dan terkini di PyPI. Ia telah beralih ke titik masuk konsol, jadi tutorial yang menjalankan python lerobot/scripts/control_robot.py menerangkan fail yang tidak lagi wujud.

Apa yang dirakam oleh sesi rakaman

Set data LeRobot bukan folder video tetapi jadual berindeks masa dengan video dilampirkan: setiap denyutan gelung kawalan menulis satu baris yang mengandungi tindakan yang diperintahkan, keadaan yang dicapai oleh pengikut, satu bingkai bagi setiap kamera, cap masa dan indeks. Polisi hanya melihat lajur-lajur tersebut. Skema lerobot/svla_so100_pickplace, dibaca dari meta/info.jsonnya.

Sendi-sendi tersebut ialah main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll dan main_gripper: enam darjah kebebasan SO-100. Tindakan dan keadaan berkongsi bentuk kerana teleoperasi pemimpin-pengikut merekodkan sasaran dan kedudukan yang dicapai satu langkah kemudian. Jurang itu adalah maklumat: di mana lengan melawan graviti atau objek yang tersekat. Rentetan-rentetan itu adalah milik set data tersebut. Sesi yang direkodkan dengan 0.6.1 hari ini menulis shoulder_pan.pos hingga gripper.pos, id 1 hingga 6 pada bas: enam sendi yang sama, kunci yang berbeza, yang penting apabila konfigurasi merujuk ciri mengikut nama.

Apa yang anda perlukan di meja kerja

Jika lengan belum dibina, itu adalah kerja malam yang berasingan: mulakan dengan Memulakan SO-100 dan panduan persediaan SO-100 yang lengkap. Jika anda belum membeli apa-apa, baca perbandingan SO-100 dengan SO-101 dahulu: SO-101 adalah semakan yang lebih baru dengan pendawaian yang diperbaiki dan tiada langkah penyingkiran gear, dan aliran kerja rakaman adalah sama.

Pasang 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 mengelirukan orang. pip install lerobot memasang kebergantungan ML teras sahaja, tiada apa-apa yang berkomunikasi dengan robot. Lengan Koch memerlukan dynamixel dan bukannya feetech. Jika shell anda tidak pernah mendengar tentang lerobot-record, inilah sebabnya.

Port, ID motor dan penentukuran

Tiga langkah sekali sahaja memisahkan komponen daripada gelung teleop yang berfungsi. membolehkan polisi yang dilatih pada lengan anda berjalan pada lengan orang lain, memetakan kiraan pengekod mentah kepada konvensyen sendi yang dikongsi.

1. 1
   Cari port USB setiap lengan

   Jalankannya dengan kedua-dua lengan dipasang, cabut palam lengan yang anda kenal pasti apabila diminta, dan perhatikan port mana yang hilang. Pada 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 kadar baud

   ID ditulis satu motor pada satu masa, dan dokumentasi adalah ketat tentang caranya: sambungkan tepat satu motor ke papan pengawal, belum lagi disambung secara bersiri kepada yang lain. Skrip berjalan ke belakang dalam rantaian, meminta untuk gripper dahulu dan memberikannya id 6, kemudian wrist_roll sebagai 5, sehingga shoulder_pan sebagai 1. Lakukan ini sebelum pemasangan.

   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
   Tentukur kedua-dua lengan

   Gerakkan setiap sendi ke tengah julatnya, tekan Enter, kemudian sapu setiap satu melalui julat penuhnya. id menjadi nama fail 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 merakam apa-apa

   Ujian penerimaan untuk semua perkara di atas. Jika teleoperasi tersentak-sentak, bercermin, atau satu sendi tidak akan mengikut, rakaman akan mengekalkannya dalam 50 episod.

   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 polisi

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 pandangan, dan kedudukannya penting: kamera pemandangan tetap yang meliputi ruang kerja, dan kamera pergelangan tangan berhampiran penggerak akhir menunjukkan apa yang akan disentuh oleh pengepit. Senarai semak set data komuniti LeRobot meminta sebaik-baiknya dua pandangan pada 480x640 / 720p atau lebih baik, latar belakang statik, pencahayaan stabil yang neutral, dan lengan utama serta anggota badan manusia di luar bingkai. Panduan rakaman menambah peraturan umum: anda sepatutnya dapat melakukan tugas itu sendiri hanya dengan melihat imej kamera.

Perintah rekod dan setiap bendera

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

Nilai lalai di bawah datang dari src/lerobot/configs/dataset.py pada main, bukan tutorial. Beberapa daripadanya bukan seperti yang orang ramai sangka.

Kawalan papan kekunci semasa sesi

• Anak panah kanan atau n: tamatkan episod atau fasa set semula lebih awal. Kekunci yang paling kerap anda gunakan, kerana genggaman yang bersih jarang memerlukan 25 saat.
• Anak panah kiri atau r: buang episod dan ulangi. Pengambilan yang buruk tidak merugikan apa-apa sekarang dan banyak kemudian.
• Escape atau q: hentikan sesi, selesaikan pengekodan, muat naik.
• Ini berfungsi pada X11, Wayland dan SSH tanpa kepala: tanpa backend kekunci global, lerobot-record membaca kekunci yang sama dari terminal kawalan. Huruf-huruf ini bertahan pada pautan SSH yang lambat, di mana urutan anak panah terpisah.
• Teleoperasi papan kekunci adalah berbeza dan memerlukan backend global: X11, Windows, atau macOS dengan Kebolehcapaian.

Berapa banyak episod, dan bagaimana rupa episod yang baik

Panduan rakaman mencadangkan sekurang-kurangnya 50 episod untuk tugas pertama, kira-kira 10 bagi setiap lokasi objek. Halaman dasar menyenaraikan minimum bagi setiap model, di bawahnya larian tidak berbaloi dengan masa GPU.

Persoalan yang lebih baik ialah berapa banyak daripada apa. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) mengumpul lebih 40,000 demonstrasi dan menjalankan lebih 15,000 larian dunia nyata. Generalisasi mengikuti hubungan hukum kuasa secara kasar dengan bilangan persekitaran dan objek, dan melepasi ambang bagi setiap persekitaran atau objek, demonstrasi tambahan mempunyai kesan yang minimum. Pada satu bangku: gerakkan objek, tukar pencahayaan, tukar kiub, daripada mengulang satu pengambilan.

Episod yang baik adalah membosankan: posisi rumah yang boleh diulang, satu perkara selesai, berakhir sebaik sahaja objek berada di dalam tong, rentetan tugas dalam 25 hingga 50 aksara yang disyorkan oleh senarai semak. Ambil kiub merah dan jatuhkan ke dalam kotak adalah rentetan tugas; task1 adalah anti-corak yang dinamakan secara eksplisit oleh senarai semak. Anotasi yang samar-samar mendahului senarai masalahnya, dan ia paling penting untuk model tindakan bahasa-penglihatan, di mana rentetan itu adalah input model, bukan nama fail.

Kecacatan yang secara senyap merosakkan set data

Tiada satu pun yang menimbulkan pengecualian. Semuanya bertahan sehingga latihan, muncul sebagai lengkung kerugian yang kelihatan baik dan robot yang tidak melakukan apa-apa. Semak semasa adegan sedang disediakan.

Satu peringatan: jadual panduan pengekodan penstriman menyenaraikan nilai lalai sebagai True, manakala dataclass pada main membaca streaming_encoding: bool = False. Dokumen dan kod tidak bersetuju, jadi tetapkan secara eksplisit; lerobot mencatat petunjuk yang mengesyorkannya setiap kali ia bermula dengan bendera dimatikan.

Semak set data sebelum menyewa GPU

Ujian penerimaan daripada dokumen: bandingkan tempoh video dengan tempoh episod yang dilaporkan oleh CLI, dan sahkan kiraan baris sama dengan fps darab tempoh. Setiap episod, bukan pada jumlah keseluruhan.

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

Kemudian lihatlah. lerobot-dataset-viz memainkan semula episod bingkai demi bingkai dengan jejak sendi di sebelah paparan kamera, dalam Rerun atau Foxglove. Kamera yang tertukar dan bingkai beku muncul dalam ten seconds. Orang ramai melangkau 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 anda merakam

v2.1 menulis satu parquet dan satu MP4 bagi setiap episod. v3.0 menggabungkan banyak episod ke dalam serpihan kongsi dan membina semula sempadan daripada metadata, jadi info.json membawa templat laluan seperti data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet dan bukannya nombor episod. Justifikasi huluan adalah fail yang lebih sedikit dan lebih besar: permulaan yang lebih pantas dan kurang tekanan sistem fail 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 laluan ke set data yang sama

Daripada set data kepada polisi

Lima puluh episod bersih menyalurkan setiap yang dijalankan di sini. dilatih dari awal untuk tugas anda sahaja, kira-kira 80 J parameter pada kira-kira 20 ms setiap langkah tindakan, satu-satunya daripada lima yang selesa dengan gerakan pantas. adalah kira-kira 450 J parameter pada kad 24 GB. adalah model asas kira-kira 3 B parameter di mana menyentuh kira-kira 40 J parameter, memerlukan A100 atau H100, dan memerlukan set data v2.1 itu.

Seterusnya, panduan untuk kombinasi anda: , atau ; untuk larian pertama, adalah lebih pendek. Apabila polisi berfungsi di bangku ujian tetapi runtuh sebaik sahaja anda menggerakkan meja, itu adalah masalah data: dan mendalami kepelbagaian.