הקלט את מערך הנתונים הראשון שלך ב-LeRobot עם SO-100

עוקב SO-100, זרוע מובילה באותו עיצוב ושתי מצלמות USB יכולים לכוונן מדיניות אחר הצהריים. אותו ספסל יכול באותה קלות לייצר שישים פרקים שנראים תקינים בדפדפן קבצים ולבזבז ריצת GPU של שש שעות. ההבדל הוא לעיתים רחוקות המודל; זה מה שקרה בין הסרוו לקובץ ה-parquet.

הנה המסלול הידני, ואז הקצר יותר. כל פקודה היא מ-lerobot 0.6.1, שוחררה ב-3 באוגוסט 2026 ועדכנית ב-PyPI. היא עברה לנקודות כניסה של קונסולה, כך שמדריכים שמריצים python lerobot/scripts/control_robot.py מתארים קובץ שכבר לא קיים.

מה סשן הקלטה לוכד

מערך נתונים של LeRobot dataset אינו תיקיית סרטונים אלא טבלה עם אינדקס זמן וסרטון מצורף: כל פעימת לולאת בקרה כותבת שורה אחת המכילה את הפעולה המבוקשת, את המצב שאליו הגיע העוקב, פריים אחד לכל מצלמה, חותמת זמן ואינדקסים. המדיניות רואה רק עמודות אלו. הסכימה של 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-100 וב-מדריך ההתקנה המלא של SO-100. אם עדיין לא קניתם כלום, קראו תחילה את השוואת SO-100 מול SO-101 תחילה: ה-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 מתקין רק תלויות ליבה של למידת מכונה, שום דבר שלא מתקשר עם רובוט. זרועות Koch זקוקות ל-dynamixel במקום feetech. אם ה-shell שלכם מעולם לא שמע על lerobot-record, זו הסיבה.

פורטים, מזהי מנועים וכיול

שלושה שלבים חד-פעמיים מפרידים בין החלקים ללולאת טל-אופ תקינה. מאפשר למדיניות שאומנה על הזרוע שלך לרוץ על זרוע של מישהו אחר, על ידי מיפוי ספירות מקודד גולמיות למוסכמת מפרקים משותפת.

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 או טוב יותר, רקע סטטי, תאורה ניטרלית ויציבה, והזרוע המובילה וגפיים אנושיות מחוץ לפריים. מדריך ההקלטה מוסיף כלל אצבע: עליך להיות מסוגל לבצע את המשימה בעצמך רק על ידי התבוננות בתמונות המצלמה.

פקודת ההקלטה וכל הדגלים

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: סיים את הפרק או את שלב האיפוס מוקדם. המקש שבו תשתמש הכי הרבה, מכיוון שאחיזה נקייה כמעט אף פעם לא דורשת 25 שניות.
• חץ שמאלה או r: זרוק את הפרק ובצע אותו מחדש. צילום גרוע לא עולה כלום עכשיו והרבה אחר כך.
• Escape או q: עצור את הסשן, סיים קידוד, העלה.
• אלה עובדים ב-X11, Wayland ו-SSH ללא ממשק גרפי: ללא קצה אחורי גלובלי למקשים, lerobot-record קורא את אותם מקשים מהטרמינל השולט. האותיות שורדות קישורי SSH איטיים, שבהם רצפי חצים מתפצלים.
• טלפרופרציה באמצעות מקלדת שונה וכן דורשת קצה אחורי גלובלי: X11, Windows, או macOS עם נגישות.

כמה פרקים, ואיך נראה פרק טוב

מדריך ההקלטה מציע לפחות 50 אפיזודות למשימה ראשונה, כ-10 לכל מיקום אובייקט. דפי המדיניות מפרטים מינימום לכל מודל, שמתחתיו הרצה אינה שווה את זמן ה-GPU.

השאלה הטובה יותר היא כמה ממה. חוקי קנה מידה של נתונים בלמידת חיקוי למניפולציה רובוטית (לין ואח', 2024) אספו למעלה מ-40,000 הדגמות והריצו יותר מ-15,000 הרצות בעולם האמיתי. הכללה עקבה אחר יחס של חוק חזקה בקירוב עם מספר ה-סביבות ואובייקטים, ולאחר סף מסוים לכל סביבה או אובייקט, להדגמות נוספות הייתה השפעה מינימלית. על ספסל אחד: הזיזו את האובייקט, שנו את התאורה, החליפו את הקובייה, במקום לחזור על אותה פעולה.

פרק טוב הוא משעמם: תנוחת בית ניתנת לחזרה, דבר אחד שבוצע, הסתיים ברגע שהאובייקט נמצא בפח, מחרוזת משימה באורך 25 עד 50 תווים כפי שהרשימה ממליצה. הרם את הקובייה האדומה ושחרר אותה בקופסה היא מחרוזת משימה; task1 היא האנטי-תבנית שהרשימה מציינת במפורש. הערות מעורפלות עומדות בראש רשימת הבעיות שלה, והן חשובות ביותר עבור , כאשר המחרוזת היא קלט מודל, לא שם קובץ.

פגמים שהורסים בשקט מערך נתונים

אף אחד מהם לא זורק חריגה. כולם שורדים לאימון, ומופיעים כעקומת הפסד שנראית בסדר ורובוט שלא עושה כלום. בדוק בזמן שהסצנה מוגדרת.

הערה אחת: הטבלה במדריך הקידוד-סטרימינג מפרטת את ברירת המחדל כ-True, בעוד ש-dataclass ב-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

שני מסלולים לאותו מערך נתונים

ממערך נתונים למדיניות

חמישים אפיזודות נקיות מזינות כל למידת חיקוי הרצה כאן. ACT מתאמן מאפס על המשימה שלך בלבד, כ-80 מיליון פרמטרים בכ-20 אלפיות השנייה לצעד פעולה, היחיד מבין החמישה שנוח לו עם תנועה מהירה. SmolVLA הוא כ-450 מיליון פרמטרים על כרטיס 24 GB. GR00T N1.7 הוא מודל יסוד של כ-3 מיליארד פרמטרים שבו כוונון עדין נוגע בכ-40 מיליון פרמטרים, דורש A100 או H100, ורוצה את מערך הנתונים v2.1 הזה.

הבא, המדריך לשילוב שלך: ACT על SO-100, SmolVLA על SO-100 או GR00T N1.7 על SO-100; להרצה ראשונה, אמן את המדיניות הראשונה שלך קצר יותר. כאשר המדיניות עובדת על השולחן אך קורסת ברגע שאתה מזיז את השולחן, זו בעיית נתונים: מדיניות עובדת רק בהגדרה אחת ו-איסוף נתוני אימון VLA באיכות גבוהה מעמיקים יותר בנושא הגיוון.