진짜 로봇 학습을 위한 '허즈페이스 레로봇'을 시작
레로봇 <unk> 설치, 데이터 수집, ACT 또는 전파 정책 훈련, 평가 및 데이터 공유에 대한 실용적인 가이드
[로봇 데이터 수집 안내]
[← 블로그]
레로봇은 데이터 수집에서 훈련된 정책까지의 전체 파이프라인을 이전 프레임워크보다 더 쉽게 접근 할 수 있게 해줍니다.
레로봇은 무엇 입니까?
레로봇은 허깅페이스의 로봇 학습 라이브러리입니다. 표준화된 데이터 세트 형식, 사전 훈련된 모델의 증가하는 컬렉션 및 ACT, 전파 정책 및 TD-MPC2 정책을위한 훈련 스크립트 이전 프레임워크의 핵심 차별은 표준화입니다. 지원되는 모든 로봇에 레로봇과 함께 수집된 데이터 세트는 사용자 지정 데이터 로더나 포맷 변환 없이 모든 레로봇 훈련 스크립트로 훈련될 수 있습니다.
2025년 초에, 레로봇은 8,000명 이상의 회원으로 활발한 디스코드 커뮤니티를 보유하고 있으며, 핵심 팀에서 매주 연구 업데이트를 하고 있으며, 전 세계 연구 그룹으로부터의 모델 동물원 기여가 증가하고 있습니다. 오픈 소스 로봇 학습 데이터 공유에 대한 실질적인 표준이되었습니다.
설치 및 하드웨어 지원
- ** 설치:******pip lerobot을 설치합니다. Python 3.10+, PyTorch 2.1+를 필요로 합니다. 선택적으로 하드웨어 의존성을 별도로 설치합니다. (예를 들어, SO-100 팔 지원에 대해 **pip lerobot을 설치합니다).
- SO-100 팔 ($300): 주요 저렴한 지원 플랫폼. 5DOF 리더+후편 텔레오퍼레이션 팔 Koch 로봇. 물리 로봇 학습에 신규 팀의 가장 좋은 출발점
- ALOHA 양동력: Stanford ALOHA 및 ALOHA 2 구성은 포함됩니다. 14 DOF 총 (7 팔당), 양동력 조작 연구를 위해 사용된다.
- OpenArm: 커뮤니티 어댑터를 통해 지원됩니다. RCSV OpenArm 7-DOF 구성은 RCSV의 LeRobot 통합 패키지를 통해 사용할 수 있습니다.
데이터 수집 작업 흐름
데이터 수집은 자동으로 표준화된 HDF5 + MP4 데이터 세트를 생성합니다.
- 단계 1
로봇을 구성: 로봇의 YAML 구성 (예를 들어, lerobot/configs/robot/so100.yaml) 을 일련 포트 및 카메라 지표로 편집합니다. - ** 단계 2
기록 데이터 세트:** python lerobot/scripts/record_dataset.py --robot-path lerobot/configs/robot/so100.yaml --num-episodes 50 --dataset-id my_task_v1. 스크립트는 카메라 간 프레임 동기화, HDF5 에피소드 작성 및 실시간 에피소드 미니얼 생성 작업을 처리합니다. - ** 3 단계
에피소드를 검토:** python lerobot/scripts/visualize_dataset.py --dataset-id my_task_v1는 인터랙티브 에피소드 시청자를 열고 훈련 전에 배제할 수 있는 플래그 실패 에피소드를 제공합니다. - ** 단계 4
허브로 푸시 (선택):** python lerobot/scripts/push_dataset_to_hub.py --dataset-id my_task_v1 공유를 위해 HuggingFace Hub 또는 관리 저장용 RCSV의 데이터 플랫폼에 업로드됩니다.
정책 훈련
| Policy | Command | Training Time (200 demos, 1× GPU) | Best For |
|---|---|---|---|
| ACT (Action Chunking with Transformers) | --policy act | ~4 hours | Fast-moving tasks, reliable baseline |
| Diffusion Policy | --policy diffusion | ~12 hours | 정밀도 tasks, multimodal behavior |
| TD-MPC2 | --policy tdmpc | ~8 hours | Tasks with clear reward structure |
ACT 훈련 명령어: python lerobot/scripts/train.py --policy act --dataset-id my_task_v1 --training.num_epochs 100. TensorBoard 로그에서 평가/성공률을 모니터링합니다. 배치 전에 목표 >70%입니다. 디푸지션 정책은 더 많은 계산을 필요로 하지만 일반적으로 멀티모달 행동 (예를 들어, 객체를 잡기 위해 여러 가지 유효한 접근 방법이 있는 작업) 을 통해 정확성 작업에 더 나은 성능을 달성합니다.
동물원 모델 및 제로 샷 테스트
르로봇은 허깅페이스 허브에서 미리 훈련된 모델 동물원을 유지하고 있습니다. 2025 년 초부터 사용 가능: 선택 장소, 스택 및 삽입 작업에 대한 SO-100에 훈련 된 ACT 및 전파 정책; 양동력 지우 및 조립을위한 ALOHA 정책. 이 것은 하드웨어에서 제로샷 테스트를 위해 사용할 수 있습니다.
사전 훈련된 정책을 실행하기 위해: python lerobot/scripts/eval.py --pretrained-policy-name-or-path lerobot/act_so100_pick_place --robot-path lerobot/configs/robot/so100.yaml.
레로봇 데이터셋 형식 심층 다이빙
데이터 세트 형식을 이해하는 것은 사용자 지정 통합에 필수적입니다. LeRobot 데이터 세트는 파켓 파일 (구성 데이터) 과 MP4 비디오 (카메라 관측) 의 조합을 사용합니다:
my_dataset_v1/
meta/
info.json # Dataset metadata (robot type, fps, features)
episodes.jsonl # Per-episode metadata (length, task description)
tasks.jsonl # Task definitions
data/
chunk-000/
episode_000000.parquet # State + action data per episode
episode_000001.parquet
...
videos/
chunk-000/
observation.images.top/
episode_000000.mp4 # Camera feed per episode
observation.images.wrist/
episode_000000.mp4
각 파켓 파일에는 다음의 열이 포함되어 있습니다:
데이터 세트를 프로그래밍적으로 로드하려면:
from lerobot.common.datasets.lerobot_dataset import LeRobotDataset
# Load from local path or HuggingFace Hub
dataset = LeRobotDataset("lerobot/aloha_sim_insertion_human_image")
# Access episode data
episode = dataset[0] # First frame of first episode
print(episode.keys())
# dict_keys(['observation.images.top', 'observation.state',
# 'action', 'episode_index', 'frame_index', 'timestamp'])
# Get all frames for episode 5
ep5_frames = [dataset[i] for i in dataset.episode_data_index["from"][5]:
dataset.episode_data_index["to"][5]]
레로봇 (LeRobot) 과 ACT 훈련: 단계별로
키 하이퍼파레머와 함께 완전한 훈련 명령이 설명했습니다.
# Train ACT on your custom dataset
python lerobot/scripts/train.py \
--policy.type=act \
--dataset.repo_id=my_org/my_task_v1 \
--dataset.episodes=[0,1,2,3,4,5,6,7,8,9] \ # Specific episodes
--training.num_epochs=2000 \
--training.batch_size=8 \
--policy.chunk_size=100 \ # Action chunk length
--policy.kl_weight=10 \ # CVAE KL divergence weight
--policy.n_action_steps=100 \ # Steps to execute per chunk
--training.lr=1e-5 \ # Learning rate
--training.save_freq=500 \ # Checkpoint every 500 epochs
--output_dir=outputs/act_my_task
조정할 수 있는 주요 하이퍼파레머:
- chunk_size: 대부분의 작업에 50-100 더 큰 조각은 합성 오류를 줄이지만 예측 문제를 더 어렵게 만듭니다. 100에서 시작하여 50로 줄이십시오.
- kl_weight: CVAE 정규화를 제어한다. 너무 낮 (1): 잠자리 공간 붕괴, 다모달 행동 손실. 너무 높 (100): 정책은 관찰을 무시한다. 하위 집합에 대한 스파이 [1, 5, 10, 50].
- 학습율: 1e-5의 정렬, 1e-4의 처음부터 훈련. 훈련이 불안정하다면 2x로 줄일 수 있습니다.
레로봇의 교육 전파 정책
# Train Diffusion Policy
python lerobot/scripts/train.py \
--policy.type=diffusion \
--dataset.repo_id=my_org/my_task_v1 \
--training.num_epochs=4000 \
--training.batch_size=64 \
--policy.n_action_steps=8 \ # Prediction horizon
--policy.n_obs_steps=2 \ # Observation history length
--policy.num_inference_steps=10 \ # DDIM steps (10 for speed)
--training.lr=1e-4 \
--output_dir=outputs/dp_my_task
디스푸시온 정책은 ACT보다 2-3배 느려지만 정확성 작업에서 더 나은 성능을 달성합니다.
데이터 세트를 HuggingFace Hub로 밀어넣는 것
# Push your dataset to HuggingFace Hub for sharing
huggingface-cli login # One-time authentication
python lerobot/scripts/push_dataset_to_hub.py \
--local-dir outputs/my_task_v1 \
--repo-id my_org/my_task_v1 \
--tags "openarm,pick-place,tabletop"
HuggingFace Hub의 데이터 세트는 레로봇이 설치된 모든 사람이 즉시 사용할 수 있습니다. 설명 태그를 추가하면 데이터 세트가 발견될 수 있습니다. RCSV의 데이터 세트는
일반적인 오류 및 수정
| Error | Cause | Fix |
|---|---|---|
RuntimeError: CUDA out of memory |
Batch size too large for GPU VRAM | Reduce batch_size to 4 or 2; use gradient accumulation |
ValueError: mismatched state dim |
Robot config does not match dataset DOF | Check robot YAML: state_dim must match observation.state columns |
Camera not found at index N |
USB camera enumeration changed | Run v4l2-ctl --list-devices and update camera_index in YAML |
Serial port permission denied |
User not in dialout group | sudo usermod -aG dialout $USER then log out/in |
| Policy outputs all zeros | KL collapse in ACT training | Increase kl_weight to 50; use KL warmup schedule |
| Video frames out of sync with state | USB bandwidth saturation | Use USB3 cameras on separate USB controllers; reduce resolution to 480p |
성능 기준
레로봇의 참조 구현을 사용하여 표준 작업에 대한 예상 성능:
| Task | Platform | Demos | ACT Success | DP Success |
|---|---|---|---|---|
| Pick-place (single object) | SO-100 | 50 | 75-85% | 70-80% |
| Stacking (2 blocks) | SO-100 | 100 | 60-75% | 65-80% |
| Bimanual handover | ALOHA | 200 | 80-90% | 75-85% |
| Insertion (peg-in-hole) | OpenArm | 200 | 50-65% | 60-75% |
지역사회 및 자원
- 분별: 8,000명 이상의 회원이 활동하고 있습니다. #Help 및 #Showcase 채널. 대부분의 질문에 몇 시간 안에 답이 있습니다.
- HuggingFace Hub: hf.co/lerobot - 데이터 세트 및 모델의 증가 추세. 로봇 유형 또는 작업에 따라 필터링.
- ** 주간 업데이트:** HuggingFace 핵심 팀은 HuggingFace 블로그에 연구 업데이트를 1-2 주마다 게시합니다.
- RCSV 통합: RCSV의 데이터 플랫폼 는 관리된 저장, 해설 및 훈련 파이프라인 수출을 위해 LeRobot 형식의 데이터 세트를 수용합니다. 우리의 데이터 수집 서비스 는 기본적으로 LeRobot 형식의 데이터 세트를 제공합니다.
관련 독서
이미테이션 학습 가이드 · 행동과 전파 정책 · 열린 X-체체 · 로봇 팔 비교 · 데이터 해석 · 데이터 서비스 · RCSV 플랫폼
레로봇 호환 데이터 수집
RCSV는 ACT 또는 전파 정책 교육 스크립트와 함께 사용할 수 있는 레로봇 형식으로 데이터 수집 출력을 제공합니다.
[데이터 서비스를 탐구]