Ghi lại tập dữ liệu LeRobot đầu tiên của bạn với SO-100

Một SO-100 robot đi theo, một cánh tay dẫn dắt có cùng thiết kế và hai camera USB có thể tinh chỉnh một chính sách (policy) trong một buổi chiều. Cùng một hệ thống đó cũng có thể dễ dàng tạo ra sáu mươi tập (episode) trông có vẻ ổn trong trình duyệt tệp và lãng phí một lần chạy GPU kéo dài sáu giờ. Sự khác biệt hiếm khi nằm ở mô hình; mà là những gì đã xảy ra giữa các động cơ servo và tệp parquet.

Đây là lộ trình thủ công, sau đó là lộ trình ngắn hơn. Mọi lệnh đều từ lerobot 0.6.1, phát hành ngày 3 tháng 8 năm 2026 và hiện có trên PyPI. Nó đã chuyển sang các điểm vào bảng điều khiển, vì vậy các hướng dẫn chạy python lerobot/scripts/control_robot.py mô tả một tệp không còn tồn tại.

Những gì một phiên ghi lại thu được

Một tập dữ liệu LeRobot không phải là một thư mục chứa video mà là một bảng được lập chỉ mục theo thời gian có đính kèm video: mỗi nhịp vòng điều khiển ghi một hàng chứa hành động được ra lệnh, trạng thái mà bộ phận theo dõi đạt được, một khung hình cho mỗi camera, một dấu thời gian và các chỉ mục. Chính sách chỉ xem các cột đó. Lược đồ của lerobot/svla_so100_pickplace, được đọc từ meta/info.json của nó.

Các khớp là main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll và main_gripper: sáu bậc tự do của SO-100. Hành động và trạng thái có cùng hình dạng vì điều khiển từ xa theo kiểu chủ-tớ ghi lại một mục tiêu và vị trí đạt được một bước sau đó. Khoảng cách đó là thông tin: nơi cánh tay đã chống lại trọng lực hoặc một vật bị kẹt. Các chuỗi đó thuộc về tập dữ liệu đó. Một phiên được ghi lại với 0.6.1 hôm nay ghi shoulder_pan.pos đến gripper.pos, id từ 1 đến 6 trên bus: cùng sáu khớp, các khóa khác nhau, điều này quan trọng khi một cấu hình gọi một tính năng theo tên.

Những gì bạn cần trên bàn làm việc

Nếu cánh tay robot chưa được lắp ráp, đó sẽ là một buổi tối riêng biệt: hãy bắt đầu tại bắt đầu với SO-100 và hướng dẫn thiết lập SO-100 đầy đủ. Nếu bạn chưa mua bất cứ thứ gì, hãy đọc so sánh SO-100 với SO-101 trước: SO-101 là phiên bản mới hơn với hệ thống dây điện được cải thiện và không cần bước tháo bánh răng, quy trình ghi hình cũng giống hệt nhau.

Cài đặt 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

Các phần bổ trợ thường gây khó khăn nhất cho mọi người. pip install lerobot chỉ cài đặt các phụ thuộc ML cốt lõi, không có gì để giao tiếp với robot. Các cánh tay Koch cần dynamixel thay vì feetech. Nếu shell của bạn chưa từng nghe nói về lerobot-record, đây là lý do.

Cổng, ID động cơ và hiệu chuẩn

Ba bước thực hiện một lần là cần thiết để chuyển từ các bộ phận riêng lẻ sang một vòng lặp điều khiển từ xa hoạt động. giúp một chính sách được huấn luyện trên cánh tay của bạn có thể chạy trên cánh tay của người khác, ánh xạ các giá trị bộ mã hóa thô sang một quy ước khớp chung.

1. 1
   Tìm cổng USB của từng cánh tay

   Chạy lệnh này khi cả hai cánh tay đều được cắm vào, rút phích cắm của cánh tay bạn đang xác định khi được nhắc, và ghi lại cổng nào biến mất. Trên Linux, bạn có thể cần 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
   Ghi ID động cơ và tốc độ baud

   ID được ghi cho từng động cơ một, và tài liệu hướng dẫn rất nghiêm ngặt về cách thực hiện: chỉ kết nối chính xác một động cơ với bảng điều khiển, chưa nối chuỗi với bất kỳ động cơ nào khác. Script sẽ đi ngược chuỗi, nhắc nhậpm cho bộ kẹp trước và gán ID 6, sau đó là khớp cổ tay (wrist_roll) là 5, xuống đến khớp vai (shoulder_pan) là 1. Hãy thực hiện trước khi lắp ráp.

   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
   Hiệu chuẩn cả hai cánh tay

   Di chuyển từng khớp đến giữa phạm vi của nó, nhấn Enter, sau đó quét từng khớp qua toàn bộ phạm vi của nó. id sẽ trở thành tên tệp hồ sơ.

   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
   Điều khiển từ xa trước khi ghi bất cứ điều gì

   Bài kiểm tra chấp nhận cho tất cả các bước trên. Nếu điều khiển từ xa bị giật, bị phản chiếu, hoặc một khớp không tuân theo, việc ghi lại sẽ lưu giữ điều đó trong 50 tập.

   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

Máy ảnh quyết định những gì chính sách nhìn thấy

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

Hai góc nhìn, và vị trí của chúng rất quan trọng: một camera cảnh cố định bao phủ không gian làm việc, và một camera cổ tay gần bộ phận chấp hành cuối hiển thị những gì bộ kẹp sắp chạm vào. Danh sách kiểm tra bộ dữ liệu cộng đồng LeRobot yêu cầu ưu tiên hai góc nhìn ở độ phân giải 480x640 / 720p trở lên, nền tĩnh, ánh sáng ổn định trung tính, và cánh tay dẫn hướng cùng các chi của con người nằm ngoài khung hình. Hướng dẫn ghi hình bổ sung quy tắc chung: bạn phải có khả năng tự thực hiện nhiệm vụ chỉ bằng cách nhìn vào hình ảnh từ camera.

Lệnh record và mọi cờ

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

Các giá trị mặc định dưới đây đến từ src/lerobot/configs/dataset.py, trên nhánh chính, không phải từ hướng dẫn. Một số không như mọi người vẫn nghĩ.

Điều khiển bàn phím trong một phiên

• Mũi tên phải hoặc n: kết thúc tập hoặc đặt lại giai đoạn sớm. Đây là phím bạn sử dụng nhiều nhất, vì một lần nắm sạch hiếm khi cần 25 giây.
• Mũi tên trái hoặc r: loại bỏ tập và làm lại. Một lần thực hiện không tốt không tốn gì bây giờ nhưng sẽ tốn rất nhiều sau này.
• Escape hoặc q: dừng phiên, hoàn tất mã hóa, tải lên.
• Những phím này hoạt động trên X11, Wayland và SSH không đầu (headless): không có backend phím toàn cục, lerobot-record đọc các phím tương tự từ terminal điều khiển. Các chữ cái vẫn hoạt động trên các liên kết SSH bị lag, nơi các chuỗi mũi tên bị tách.
• Điều khiển từ xa bằng bàn phím thì khác và cần một backend toàn cục: X11, Windows hoặc macOS với Trợ năng (Accessibility).

Bao nhiêu tập, và một tập tốt trông như thế nào

Hướng dẫn ghi hình đề xuất ít nhất 50 tập cho nhiệm vụ đầu tiên, khoảng 10 tập cho mỗi vị trí đối tượng. Các trang chính sách liệt kê mức tối thiểu cho mỗi mô hình, dưới mức đó một lần chạy không đáng thời gian GPU.

Câu hỏi hay hơn là bao nhiêu của cái gì. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) đã thu thập hơn 40.000 bản trình diễn và thực hiện hơn 15.000 lần triển khai trong thế giới thực. Khả năng tổng quát hóa tuân theo mối quan hệ luật lũy thừa xấp xỉ với số lượng môi trường và đối tượng, và vượt quá ngưỡng cho mỗi môi trường hoặc đối tượng, các bản trình diễn bổ sung có tác dụng tối thiểu. Trên một băng ghế thử nghiệm: di chuyển đối tượng, thay đổi ánh sáng, hoán đổi khối lập phương, thay vì lặp lại một lần quay.

Một tập tốt là một tập nhàm chán: tư thế ban đầu có thể lặp lại, một việc được hoàn thành, kết thúc khi vật thể đã vào thùng, chuỗi tác vụ trong khoảng 25 đến 50 ký tự mà danh sách kiểm tra khuyến nghị. Nhặt khối lập phương màu đỏ và thả vào hộp là một chuỗi tác vụ; task1 là một phản mẫu mà danh sách kiểm tra nêu rõ. Các chú thích mơ hồ đứng đầu danh sách các vấn đề của nó, và chúng quan trọng nhất đối với , nơi chuỗi là đầu vào của mô hình, không phải tên tệp.

Các lỗi âm thầm phá hỏng một tập dữ liệu

Không có lỗi nào gây ra ngoại lệ. Tất cả đều tồn tại trong quá trình huấn luyện, xuất hiện dưới dạng đường cong mất mát trông ổn và một robot không làm gì cả. Kiểm tra khi cảnh đang được thiết lập.

Một lưu ý: bảng hướng dẫn mã hóa-truyền phát liệt kê giá trị mặc định là True, trong khi dataclass trên main đọc là streaming_encoding: bool = False. Tài liệu và mã không khớp, vì vậy hãy đặt nó một cách rõ ràng; lerobot sẽ ghi lại một gợi ý khuyến nghị điều này bất cứ khi nào nó khởi động mà không bật cờ.

Kiểm tra tập dữ liệu trước khi thuê GPU

Kiểm tra chấp nhận từ tài liệu: so sánh thời lượng video với thời lượng tập mà CLI đã báo cáo, và xác nhận số hàng bằng fps nhân với thời lượng. Theo từng tập, không phải tổng cộng.

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

Sau đó hãy xem xét nó. lerobot-dataset-viz phát lại một tập từng khung hình với các dấu vết khớp bên cạnh chế độ xem camera, trong Rerun hoặc Foxglove. Các camera bị hoán đổi và khung hình bị đóng băng sẽ hiển thị trong mười giây. Mọi người thường bỏ qua bước này.

# 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 hoặc v3.0: quyết định trước khi bạn ghi lại

v2.1 ghi một tệp parquet và một tệp MP4 cho mỗi tập. v3.0 nối nhiều tập thành các phân đoạn dùng chung và xây dựng lại ranh giới từ siêu dữ liệu, do đó info.json mang các mẫu đường dẫn như data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet thay vì số tập. Lý do từ phía nhà phát triển là ít tệp hơn, kích thước lớn hơn: khởi tạo nhanh hơn và giảm áp lực lên hệ thống tệp ở quy mô lớn.

# 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

Hai cách để có cùng bộ dữ liệu

Từ tập dữ liệu đến chính sách

Năm mươi tập sạch cung cấp cho mọi học bắt chước chạy ở đây. ACT huấn luyện từ đầu chỉ trên tác vụ của bạn, khoảng 80 triệu tham số với khoảng 20 ms mỗi bước hành động, là một trong năm mô hình duy nhất thoải mái với chuyển động nhanh. SmolVLA có khoảng 450 triệu tham số trên một card 24 GB. GR00T N1.7 là một mô hình nền tảng khoảng 3 tỷ tham số, nơi tinh chỉnh chạm khoảng 40 triệu tham số, cần một A100 hoặc H100, và yêu cầu tập dữ liệu v2.1 đó.

Tiếp theo, hướng dẫn cho sự kết hợp của bạn: ACT trên SO-100, SmolVLA trên SO-100 hoặc GR00T N1.7 trên SO-100; đối với lần chạy đầu tiên, huấn luyện chính sách đầu tiên của bạn ngắn hơn. Khi chính sách hoạt động trên bàn thử nghiệm nhưng sụp đổ ngay khi bạn di chuyển bàn, đó là một vấn đề về dữ liệu: chính sách chỉ hoạt động trong một thiết lập và thu thập dữ liệu huấn luyện VLA chất lượng cao đi sâu hơn về sự đa dạng.