บันทึกชุดข้อมูล LeRobot ชุดแรกของคุณด้วย SO-100

หุ่นยนต์ SO-100 follower, แขนนำที่มีการออกแบบเดียวกัน และกล้อง 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, ID 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 ติดตั้งเฉพาะส่วนประกอบหลักของ ML เท่านั้น ไม่ใช่ส่วนที่สื่อสารกับหุ่นยนต์ แขนกล Koch ต้องการ dynamixel แทน feetech. หากเชลล์ของคุณไม่รู้จัก lerobot-record นี่คือเหตุผล

พอร์ต, ID มอเตอร์ และการปรับเทียบ

มีสามขั้นตอนที่ต้องทำเพียงครั้งเดียวเพื่อเชื่อมต่อชิ้นส่วนต่างๆ เข้ากับวงจร teleop ที่ใช้งานได้ ช่วยให้ policy ที่ฝึกบนแขนของคุณสามารถทำงานบนแขนของคนอื่นได้ โดยจะแมปค่า encoder ดิบเข้ากับข้อกำหนดร่วมของข้อต่อ

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
   เขียน ID มอเตอร์และอัตราบอด

   ID จะถูกเขียนทีละมอเตอร์ และเอกสารระบุไว้อย่างเคร่งครัดว่า: ให้เชื่อมต่อมอเตอร์เพียงตัวเดียวเข้ากับบอร์ดควบคุม โดยยังไม่ต้องต่อแบบ daisy-chain กับตัวอื่น สคริปต์จะเดินย้อนกลับไปตามสายโซ่ โดยจะแจ้งให้ระบุ gripper ก่อนและกำหนด ID เป็น 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: จบตอนหรือรีเซ็ตเฟสก่อนกำหนด เป็นปุ่มที่คุณใช้บ่อยที่สุด เพราะการจับที่สะอาดแทบไม่เคยต้องใช้เวลาถึง 25 วินาที
• ลูกศรซ้าย หรือ r: ทิ้งตอนนั้นแล้วทำใหม่ การบันทึกที่ไม่ดีไม่มีค่าใช้จ่ายตอนนี้ แต่จะมีค่าใช้จ่ายมากในภายหลัง
• Escape หรือ q: หยุดเซสชัน, สิ้นสุดการเข้ารหัส, อัปโหลด
• สิ่งเหล่านี้ใช้งานได้บน X11, Wayland และ headless SSH: โดยไม่มีแบ็กเอนด์คีย์สากล lerobot-record จะอ่านคีย์เดียวกันจากเทอร์มินัลควบคุม ตัวอักษรจะยังคงใช้งานได้แม้ในลิงก์ SSH ที่มีความหน่วง ซึ่งลำดับลูกศรอาจแยกออกจากกัน
• การควบคุมระยะไกลด้วยคีย์บอร์ดนั้นแตกต่างกันและจำเป็นต้องมีแบ็กเอนด์สากล: X11, Windows หรือ macOS ที่มี Accessibility

จำนวนตอน และลักษณะของตอนที่ดี

คู่มือการบันทึกแนะนำอย่างน้อย 50 ตอนสำหรับงานแรก โดยประมาณ 10 ตอนต่อตำแหน่งวัตถุ หน้าข้อมูลนโยบาย ระบุจำนวนขั้นต่ำต่อโมเดล ซึ่งหากต่ำกว่านั้น การรันจะไม่คุ้มค่ากับเวลา GPU

คำถามที่ดีกว่าคือ ควรมีจำนวนเท่าไรและของอะไร Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin และคณะ, 2024) ได้รวบรวมการสาธิตกว่า 40,000 ครั้ง และดำเนินการทดสอบในโลกจริงมากกว่า 15,000 ครั้ง การสรุปผลเป็นไปตามความสัมพันธ์แบบกฎกำลังโดยประมาณกับจำนวนสภาพแวดล้อมและวัตถุ และเมื่อเกินเกณฑ์ที่กำหนดต่อสภาพแวดล้อมหรือวัตถุ การสาธิตเพิ่มเติมจะมีผลน้อยมาก สำหรับการทดสอบหนึ่งครั้ง: ให้ย้ายวัตถุ เปลี่ยนแสง สลับลูกบาศก์ แทนที่จะทำซ้ำการสาธิตเดิม

ตอนที่ดีคือตอนที่น่าเบื่อ: ท่าเริ่มต้นที่ทำซ้ำได้, ทำสิ่งเดียวเสร็จ, จบลงเมื่อวัตถุอยู่ในถัง, สตริงงานมีความยาว 25 ถึง 50 ตัวอักษรตามที่รายการตรวจสอบแนะนำ Pick the red cube and drop it in the box เป็นสตริงงาน; 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 จะรวมหลายตอนเข้าด้วยกันใน shard ที่ใช้ร่วมกัน และสร้างขอบเขตใหม่จากเมตาดาต้า ดังนั้น 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 ms ต่อขั้นตอนการกระทำ เป็นเพียงหนึ่งในห้าที่รองรับการเคลื่อนไหวที่รวดเร็วได้ดี มีพารามิเตอร์ประมาณ 450 ล้านตัวบนการ์ด 24 GB เป็นโมเดลพื้นฐานที่มีพารามิเตอร์ประมาณ 3 พันล้านตัว ซึ่ง ใช้พารามิเตอร์ประมาณ 40 ล้านตัว ต้องการ A100 หรือ H100 และต้องการชุดข้อมูล v2.1 นั้น

ถัดไป คู่มือสำหรับชุดค่าผสมของคุณ: , หรือ ; สำหรับการรันครั้งแรก จะสั้นกว่า เมื่อโมเดลนโยบายทำงานได้บนโต๊ะทดสอบ แต่ล้มเหลวทันทีที่คุณขยับโต๊ะ นั่นคือปัญหาข้อมูล: และ จะเจาะลึกเรื่องความหลากหลายมากขึ้น