SO-100으로 첫 LeRobot 데이터셋 기록하기

하나의 SO-100 팔로워, 동일한 디자인의 리더 암, 그리고 두 대의 USB 카메라로 오후에 정책을 미세 조정할 수 있습니다. 동일한 벤치에서 파일 브라우저에서 정상적으로 보이는 60개의 에피소드를 쉽게 생성하고 6시간의 GPU 실행을 낭비할 수도 있습니다. 차이는 모델에 있는 경우가 드뭅니다. 서보와 Parquet 파일 사이에서 발생한 일에 있습니다.

수동 경로와 더 짧은 경로가 있습니다. 모든 명령어는 2026년 8월 3일에 출시되어 PyPI에 현재 등록된 lerobot 0.6.1에서 가져온 것입니다. 콘솔 진입점으로 이동했으므로, python lerobot/scripts/control_robot.py를 실행하는 튜토리얼은 더 이상 존재하지 않는 파일을 설명합니다.

기록 세션이 캡처하는 내용

A 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의 6 자유도입니다. 액션과 상태는 형태를 공유합니다. 왜냐하면 리더-팔로워 원격 조작은 목표와 한 단계 후에 도달한 위치를 기록하기 때문입니다. 그 간격은 정보입니다: 팔이 중력이나 걸린 물체와 싸운 곳을 나타냅니다. 이 문자열들은 해당 데이터셋의 것입니다. 오늘 0.6.1로 기록된 세션은 버스에서 ID 1부터 6까지의 shoulder_pan.pos부터 gripper.pos까지를 기록합니다. 동일한 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

추가 기능(Extras)이 대부분의 사람들을 혼란스럽게 합니다. pip install lerobot은 핵심 ML 종속성만 설치하며, 로봇과 통신하는 기능은 없습니다. Koch 암은 dynamixel 대신 feetech을 필요로 합니다. 쉘이 lerobot-record를 알지 못한다면, 이것이 그 이유입니다.

포트, 모터 ID 및 캘리브레이션

부품과 작동하는 텔레옵 루프 사이에는 세 가지 일회성 단계가 있습니다. 은(는) 사용자의 팔에서 훈련된 정책을 다른 사람의 팔에서 실행하여, 원시 인코더 카운트를 공유된 조인트 규칙에 매핑합니다.

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는 한 번에 하나의 모터에 기록되며, 문서에는 엄격한 방법이 명시되어 있습니다: 컨트롤러 보드에 정확히 하나의 모터만 연결하고, 아직 다른 모터와 데이지 체인으로 연결하지 마십시오. 스크립트는 체인을 역방향으로 탐색하여 그리퍼에 먼저 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 및 헤드리스 SSH에서 작동합니다. 전역 키 백엔드가 없으면 lerobot-record는 제어 터미널에서 동일한 키를 읽습니다. 화살표 시퀀스가 분리되는 지연된 SSH 링크에서도 문자가 유지됩니다.
• 키보드 원격 조작은 다르며 전역 백엔드가 필요합니다: X11, Windows 또는 접근성 기능이 있는 macOS.

에피소드 수와 좋은 에피소드의 모습

녹화 가이드는 첫 번째 작업에 대해 최소 50개의 에피소드, 객체 위치당 약 10개를 제안합니다. 정책 페이지에는 모델별 최소값이 나열되어 있으며, 이 값 미만에서는 GPU 시간을 들일 가치가 없습니다.

더 나은 질문은 무엇을 얼마나 많이 할 것인가입니다. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024)은 40,000개 이상의 시연을 수집하고 15,000개 이상의 실제 롤아웃을 실행했습니다. 일반화는 환경 및 객체 수와 대략적인 멱법칙 관계를 따랐으며, 환경 또는 객체당 임계값을 넘어서면 추가 시연은 최소한의 효과를 보였습니다. 한 벤치에서: 한 번의 촬영을 반복하기보다는 객체를 이동하고, 조명을 변경하고, 큐브를 교체하십시오.

좋은 에피소드는 지루합니다: 반복 가능한 홈 포즈, 한 가지 작업 완료, 물체가 통에 들어간 후 종료, 체크리스트에서 권장하는 25~50자 길이의 작업 문자열. 빨간색 큐브를 집어 상자에 넣으세요는 작업 문자열입니다; 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에서 카메라 뷰 옆에 조인트 트레이스와 함께 에피소드를 프레임별로 재생합니다. 카메라가 바뀌거나 프레임이 멈춘 현상은 10초 안에 나타납니다. 사람들은 이 단계를 건너뜁니다.

# 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

동일한 데이터셋에 도달하는 두 가지 경로

데이터셋에서 정책으로

50개의 깨끗한 에피소드가 모든 실행에 공급됩니다. 는 약 20ms의 액션 스텝당 약 80M 매개변수로, 사용자의 작업에 대해서만 처음부터 훈련하며, 빠른 움직임에 편안한 다섯 가지 중 유일한 것입니다. 는 24GB 카드에서 약 450M 매개변수를 가집니다. 는 약 3B 매개변수의 파운데이션 모델이며, 여기서 은 약 40M 매개변수를 사용하고, A100 또는 H100이 필요하며, v2.1 데이터셋을 요구합니다.

다음은 조합에 대한 가이드입니다: , 또는 ; 첫 실행의 경우, 가 더 짧습니다. 정책이 벤치에서는 작동하지만 테이블을 움직이는 순간 실패한다면, 그것은 데이터 문제입니다: 및 에서 다양성에 대해 더 깊이 다룹니다.