سجل أول مجموعة بيانات LeRobot خاصة بك باستخدام SO-100

يمكن لـSO-100 تابع، وذراع قائد بنفس التصميم، وكاميرتين USB ضبط سياسة بدقة في فترة ما بعد الظهر. يمكن لنفس المنصة أن تنتج بسهولة ستين حلقة تبدو سليمة في متصفح الملفات وتهدر تشغيل GPU لمدة ست ساعات. نادرًا ما يكون الفرق في النموذج؛ بل هو ما حدث بين المحركات المؤازرة وملف الباركيه.

هنا المسار اليدوي، ثم المسار الأقصر. كل أمر هو من 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 لكل ذراع

   شغّله مع توصيل كلا الذراعين، افصل الذراع الذي تحدده عند المطالبة، ولاحظ أي منفذ يختفي. على نظام Linux قد تحتاج إلى 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 على الفرع الرئيسي، وليست من دليل تعليمي. العديد منها ليس ما يفترضه الناس.

التحكم بلوحة المفاتيح أثناء الجلسة

• السهم الأيمن أو n: إنهاء الحلقة أو إعادة ضبط المرحلة مبكرًا. هذا هو المفتاح الذي تستخدمه غالبًا، لأن الإمساك النظيف نادرًا ما يحتاج إلى 25 ثانية.
• السهم الأيسر أو r: تجاهل الحلقة وإعادة تنفيذها. اللقطة السيئة لا تكلف شيئًا الآن والكثير لاحقًا.
• Escape أو q: إيقاف الجلسة، إنهاء الترميز، الرفع.
• هذه تعمل على X11 و Wayland و SSH بدون واجهة رسومية: بدون واجهة خلفية للمفاتيح العامة، يقرأ lerobot-record نفس المفاتيح من الطرفية المتحكمة. الحروف تبقى صالحة عبر روابط SSH البطيئة، حيث تنقسم تسلسلات الأسهم.
• التحكم عن بعد بلوحة المفاتيح مختلف ويحتاج إلى واجهة خلفية عامة: X11، Windows، أو macOS مع إمكانية الوصول.

كم عدد الحلقات، وكيف تبدو الحلقة الجيدة

يوصي دليل التسجيل بما لا يقل عن 50 حلقة للمهمة الأولى، حوالي 10 لكل موقع كائن. صفحات السياسة تسرد حدًا أدنى لكل نموذج، والذي يقل عنه لا يستحق التشغيل وقت وحدة معالجة الرسوميات.

السؤال الأفضل هو كمية ماذا. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) جمعت أكثر من 40,000 عرض توضيحي وأجرت أكثر من 15,000 عملية تنفيذ في العالم الحقيقي. تبع التعميم علاقة تقريبية بقانون القوة مع عدد البيئات والكائنات، وبعد تجاوز عتبة معينة لكل بيئة أو كائن، كان للعروض التوضيحية الإضافية تأثير ضئيل. على مقعد واحد: حرك الكائن، غير الإضاءة، استبدل المكعب، بدلاً من تكرار لقطة واحدة.

الحلقة الجيدة مملة: وضع البداية قابل للتكرار، شيء واحد تم إنجازه، انتهت بمجرد وضع الكائن في الصندوق، سلسلة المهام ضمن 25 إلى 50 حرفًا التي توصي بها قائمة التحقق. التقط المكعب الأحمر وأسقطه في الصندوق هي سلسلة مهام؛ task1 هو النمط المضاد الذي تسميه قائمة التحقق صراحةً. تتصدر التعليقات التوضيحية الغامضة قائمة المشاكل، وهي الأكثر أهمية لـ ، حيث تكون السلسلة مدخلًا للنموذج، وليست اسم ملف.

عيوب تدمر مجموعة البيانات بصمت

لا شيء يرمي استثناءً. كلها تبقى حتى التدريب، وتظهر كمنحنى خسارة يبدو جيدًا وروبوت لا يفعل شيئًا. تحقق بينما المشهد معد.

تحذير واحد: جدول دليل الترميز بالبث المباشر يسرد القيمة الافتراضية على أنها True، بينما تقرأ فئة البيانات الرئيسية streaming_encoding: bool = False. تتعارض الوثائق مع الكود، لذا قم بتعيينها بشكل صريح؛ يسجل lerobot تلميحًا يوصي بذلك كلما بدأ التشغيل مع إيقاف العلامة.

تحقق من مجموعة البيانات قبل استئجار وحدة معالجة رسوميات

اختبار القبول من الوثائق: قارن مدة الفيديو بمدة الحلقة التي أبلغ عنها سطر الأوامر، وتأكد من أن عدد الصفوف يساوي عدد الإطارات في الثانية مضروبًا في المدة. لكل حلقة، وليس على الإجمالي.

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 تلك.

بعد ذلك، الدليل الخاص بمجموعتك: ، أو ؛ لأول تشغيل، أقصر. عندما تعمل السياسة على مقعد الاختبار ولكنها تنهار لحظة تحريك الطاولة، فهذه مشكلة بيانات: و تتعمق في التنوع.