اولین مجموعه داده LeRobot خود را با یک SO-100 ضبط کنید

یک SO-100 فالوور، یک بازوی لیدر با طراحی مشابه و دو دوربین USB می‌توانند یک سیاست (policy) را در یک بعدازظهر تنظیم دقیق کنند. همین میز کار می‌تواند به راحتی شصت اپیزود تولید کند که در یک مرورگر فایل سالم به نظر می‌رسند و یک اجرای شش ساعته GPU را هدر دهد. تفاوت به ندرت مدل است؛ بلکه چیزی است که بین سرووها و فایل parquet اتفاق افتاده است.

در اینجا مسیر دستی، سپس مسیر کوتاه‌تر آمده است. هر دستور از lerobot 0.6.1 است که در 3 آگوست 2026 منتشر شده و در PyPI به‌روز است. این به نقاط ورودی کنسول منتقل شده است، بنابراین آموزش‌هایی که اجرا می‌کنند python lerobot/scripts/control_robot.py فایلی را توصیف می‌کنند که دیگر وجود ندارد.

آنچه یک جلسه ضبط ثبت می‌کند

یک مجموعه داده LeRobot یک پوشه از ویدئوها نیست، بلکه یک جدول زمان‌بندی شده با ویدئوی پیوست شده است: هر تیک حلقه کنترل یک ردیف می‌نویسد که شامل عمل فرمان داده شده، حالتی که دنبال‌کننده به آن رسیده، یک فریم برای هر دوربین، یک برچسب زمانی و شاخص‌ها است. سیاست فقط این ستون‌ها را می‌بیند. شمای lerobot/svla_so100_pickplace، از meta/info.json آن خوانده شده است.

مفاصل عبارتند از main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll و main_gripper: شش درجه آزادی SO-100. عمل و حالت شکل یکسانی دارند زیرا تله‌اپریشن رهبر-دنبال‌کننده یک هدف و موقعیت رسیده در یک گام بعد را ثبت می‌کند. این شکاف اطلاعاتی است: جایی که بازو با گرانش یا یک شیء گیر کرده مبارزه کرده است. این رشته‌ها متعلق به آن مجموعه داده هستند. یک جلسه که امروز با 0.6.1 ضبط شده است، shoulder_pan.pos تا gripper.pos را می‌نویسد، شناسه‌های 1 تا 6 روی باس: همان شش مفصل، کلیدهای متفاوت، که در لحظه‌ای که یک پیکربندی یک ویژگی را با نام آدرس‌دهی می‌کند، اهمیت پیدا می‌کند.

آنچه روی میز کار نیاز دارید

اگر بازو هنوز ساخته نشده است، این یک کار جداگانه است: از و شروع کنید. اگر هنوز چیزی نخریده‌اید، ابتدا را بخوانید: SO-101 نسخه جدیدتر با سیم‌کشی بهبود یافته و بدون مرحله حذف چرخ‌دنده است، و گردش کار ضبط یکسان است.

نصب 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

بیشتر اوقات، افزونه‌ها باعث سردرگمی می‌شوند. pip install lerobot فقط وابستگی‌های اصلی ML را نصب می‌کند، نه چیزی که با ربات ارتباط برقرار کند. بازوهای Koch به dynamixel به جای feetech نیاز دارند. اگر پوسته شما هرگز نام lerobot-record را نشنیده است، دلیلش همین است.

پورت‌ها، شناسه‌های موتور و کالیبراسیون

سه مرحله یک‌باره بین قطعات و یک حلقه تله‌اپراتوری فعال قرار دارند. باعث می‌شود یک سیاست (policy) آموزش‌دیده روی بازوی شما، روی بازوی شخص دیگری اجرا شود و شمارش‌های خام انکودر را به یک قرارداد مشترک مفصلی نگاشت کند.

1. 1
   پورت USB هر بازو را پیدا کنید

   آن را با هر دو بازو متصل اجرا کنید، بازویی را که در حال شناسایی آن هستید هنگام درخواست جدا کنید و توجه کنید کدام پورت ناپدید می‌شود. در لینوکس ممکن است به 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
   شناسه‌های موتور و نرخ‌های باود را بنویسید

   شناسه‌ها یک موتور در هر زمان نوشته می‌شوند و مستندات در مورد نحوه انجام آن سخت‌گیرانه هستند: دقیقاً یک موتور را به برد کنترلر وصل کنید، نه به صورت زنجیره‌ای به موتور دیگری. اسکریپت زنجیره را به عقب طی می‌کند، ابتدا برای گریپر درخواست می‌کند و شناسه 6 را به آن می‌دهد، سپس wrist_roll را 5 و تا shoulder_pan را 1. این کار را قبل از مونتاژ انجام دهید.

   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
   هر دو بازو را کالیبره کنید

   هر مفصل را به وسط دامنه حرکتی خود ببرید، Enter را فشار دهید، سپس هر کدام را در کل دامنه حرکتی خود حرکت دهید. id به نام فایل پروفایل تبدیل می‌شود.

   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
   قبل از ضبط هر چیزی، تله‌اپراتوری کنید

   آزمون پذیرش برای تمام موارد بالا. اگر تله‌اپراتوری ناپایدار، آینه‌ای یا یک مفصل از دستور پیروی نمی‌کند، ضبط آن را در 50 اپیزود حفظ می‌کند.

   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

دوربین‌ها تعیین می‌کنند که سیاست چه چیزی را می‌بیند

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

دو نما، و محل قرارگیری آنها مهم است: یک دوربین صحنه ثابت که فضای کاری را پوشش می‌دهد، و یک دوربین مچی نزدیک به ابزار انتهایی که نشان می‌دهد گریپر در آستانه لمس چه چیزی است. چک‌لیست مجموعه داده‌های جامعه LeRobot ترجیحاً دو نما با کیفیت 480x640 / 720p یا بهتر، پس‌زمینه ثابت، نورپردازی خنثی و پایدار، و بازوی رهبر و اندام‌های انسانی خارج از کادر را درخواست می‌کند. راهنمای ضبط این قانون کلی را اضافه می‌کند: شما باید بتوانید خودتان کار را فقط با نگاه کردن به تصاویر دوربین انجام دهید.

دستور record و هر پرچم

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

مقادیر پیش‌فرض زیر از src/lerobot/configs/dataset.py در شاخه اصلی (main) می‌آیند، نه از یک آموزش. برخی از آن‌ها آن چیزی نیستند که مردم تصور می‌کنند.

کنترل با صفحه کلید در طول یک جلسه

• فلش راست یا n: پایان دادن به اپیزود یا بازنشانی فاز زودتر. این کلیدی است که بیشتر از آن استفاده می‌کنید، زیرا یک گرفتن تمیز به ندرت به ۲۵ ثانیه نیاز دارد.
• فلش چپ یا r: اپیزود را دور بیندازید و دوباره انجام دهید. یک برداشت بد اکنون هیچ هزینه‌ای ندارد و بعداً هزینه زیادی خواهد داشت.
• Escape یا q: جلسه را متوقف کنید، رمزگذاری را به پایان برسانید، آپلود کنید.
• اینها روی X11، Wayland و SSH بدون رابط گرافیکی کار می‌کنند: بدون بک‌اند کلید سراسری، lerobot-record همان کلیدها را از ترمینال کنترل‌کننده می‌خواند. حروف در لینک‌های SSH کند، که در آن توالی‌های فلش تقسیم می‌شوند، دوام می‌آورند.
• تله‌اپریشن با صفحه کلید متفاوت است و به یک بک‌اند سراسری نیاز دارد: X11، Windows، یا macOS با Accessibility.

چند اپیزود، و یک اپیزود خوب چگونه به نظر می‌رسد

راهنمای ضبط حداقل ۵۰ اپیزود را برای اولین کار پیشنهاد می‌کند، حدود ۱۰ اپیزود برای هر مکان شیء. صفحات سیاست‌گذاری حداقل تعداد را برای هر مدل فهرست می‌کنند، که کمتر از آن اجرای مدل ارزش زمان GPU را ندارد.

سوال بهتر این است که چه تعداد از چه چیزی. Data Scaling Laws in Imitation Learning for Robotic Manipulation (لین و همکاران، ۲۰۲۴) بیش از ۴۰,۰۰۰ نمایش جمع‌آوری کرده و بیش از ۱۵,۰۰۰ اجرای واقعی را انجام دادند. تعمیم‌پذیری تقریباً از یک رابطه قانون توانی با تعداد محیط‌ها و اشیاء پیروی می‌کرد، و پس از عبور از یک آستانه برای هر محیط یا شیء، نمایش‌های اضافی تأثیر ناچیزی داشتند. در یک سناریو: شیء را حرکت دهید، نور را تغییر دهید، مکعب را جابجا کنید، به جای تکرار یک برداشت.

یک اپیزود خوب خسته‌کننده است: وضعیت اولیه قابل تکرار، یک کار انجام شده، پایان یافته به محض اینکه شیء در سطل قرار گرفت، رشته وظیفه در محدوده ۲۵ تا ۵۰ کاراکتری که چک‌لیست توصیه می‌کند. مکعب قرمز را بردارید و در جعبه بیندازید یک رشته وظیفه است؛ task1 ضد الگویی است که چک‌لیست به صراحت نام می‌برد. توضیحات مبهم در صدر لیست مشکلات آن قرار دارند و برای مدل‌های بینایی-زبان-عمل، جایی که رشته یک ورودی مدل است، نه نام فایل.

نقص‌هایی که بی‌صدا یک مجموعه داده را خراب می‌کنند

هیچ‌کدام استثنایی ایجاد نمی‌کنند. همه تا مرحله آموزش باقی می‌مانند و به صورت یک منحنی زیان که خوب به نظر می‌رسد و یک ربات که کاری انجام نمی‌دهد، ظاهر می‌شوند. هنگام تنظیم صحنه بررسی کنید.

یک نکته: جدول راهنمای رمزگذاری جریانی، مقدار پیش‌فرض را True، در حالی که کلاس داده در main می‌خواند streaming_encoding: bool = False. مستندات و کد با هم اختلاف دارند، بنابراین آن را به صراحت تنظیم کنید؛ lerobot هر زمان که با پرچم خاموش شروع به کار کند، یک راهنمایی برای توصیه آن ثبت می‌کند.

قبل از اجاره GPU، مجموعه داده را بررسی کنید

آزمون پذیرش از مستندات: مدت زمان ویدئو را با مدت زمان اپیزودی که CLI گزارش کرده است مقایسه کنید و تأیید کنید که تعداد ردیف‌ها برابر با fps ضربدر مدت زمان است. برای هر اپیزود، نه در مجموع.

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

سپس به آن نگاه کنید. lerobot-dataset-viz یک اپیزود را فریم به فریم با ردیابی مفاصل در کنار نماهای دوربین، در Rerun یا Foxglove پخش می‌کند. دوربین‌های جابجا شده و فریم‌های ثابت در ده ثانیه ظاهر می‌شوند. افراد این مرحله را نادیده می‌گیرند.

# 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 یا v3.0: قبل از ضبط تصمیم بگیرید

v2.1 برای هر اپیزود یک فایل parquet و یک MP4 می‌نوشت. v3.0 چندین اپیزود را در شارد‌های مشترک به هم متصل می‌کند و مرزها را از فراداده بازسازی می‌کند، بنابراین info.json الگوهای مسیر را به این شکل حمل می‌کند: data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet به جای شماره اپیزود. توجیه اصلی این است که فایل‌های کمتر و بزرگ‌تر: راه‌اندازی سریع‌تر و فشار کمتر بر سیستم فایل در مقیاس بزرگ.

# 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

دو مسیر برای رسیدن به یک مجموعه داده

از مجموعه داده تا مدل رفتاری

پنجاه اپیزود تمیز، هر اجرا شده در اینجا را تغذیه می‌کند. به تنهایی و از ابتدا روی وظیفه شما آموزش می‌بیند، حدود 80 میلیون پارامتر با تقریباً 20 میلی‌ثانیه در هر گام عملیاتی، تنها مدل از پنج مدل که با حرکت سریع راحت است. حدود 450 میلیون پارامتر روی یک کارت 24 گیگابایتی دارد. یک مدل بنیادی تقریباً 3 میلیارد پارامتری است که در آن حدود 40 میلیون پارامتر را درگیر می‌کند، به A100 یا H100 نیاز دارد و آن مجموعه داده v2.1 را می‌خواهد.

در ادامه، راهنمای ترکیب شما: ، یا ؛ برای اولین اجرا، کوتاه‌تر است. وقتی مدل رفتاری روی میز کار می‌کند اما به محض حرکت دادن میز از کار می‌افتد، این یک مشکل داده است: و به عمق تنوع می‌پردازند.