LeRobot 학습 로드맵 – Robot's Diary

이 문서는 Hugging Face LeRobot를 “처음부터 실제 로봇 자율제어까지” 끌고 가는 교재형 학습 로드맵이다. 개념 → 하드웨어 → 데이터 → 정책(모델) → 학습 → 평가·배포까지 단계별로 정리한다. 각 단계는 독립적으로도 읽히지만, 0 → 13장 순서대로 따라가면 하나의 커리큘럼이 된다. 모니터링·관측이 필요해지면 Learn → Monitoring 문서를 함께 보면 좋다.

0. 목차

LeRobot이란? 생태계에서의 위치
큰 그림 — 3대 기둥(하드웨어·데이터셋·정책)
학습 로드맵 한눈에 (Level 0 → 5)
환경 구축 (설치 · 계정)
하드웨어 — 지원 로봇과 텔레오퍼레이션
LeRobotDataset 포맷
데이터 수집 워크플로 (calibrate → record → replay)
정책(Policy) 지도 — IL · RL · VLA
핵심 정책 심화 — ACT · Diffusion · SmolVLA
학습(Training) — lerobot-train
평가·배포 — 추론과 Async Inference
시뮬레이션 학습
단계별 커리큘럼 & 마일스톤
실전 미니 프로젝트 — 레고 집어 담기
트러블슈팅 & 자주 막히는 곳
용어 사전 & 링크

1. LeRobot이란? 생태계에서의 위치

LeRobot은 Hugging Face가 만든 오픈소스 PyTorch 로보틱스 라이브러리다. “로보틱스의 진입 장벽을 낮춰, 누구나 데이터셋·사전학습 모델을 공유하고 활용하게 한다”가 목표다. 핵심은 실제 세계로 전이(transfer)되는 모방학습·강화학습에 초점을 둔다는 점이다.

한 줄 정의: LeRobot = “로봇계의 Hugging Face”. 모델·데이터셋·도구를 Hub에서 공유하고, 저가 로봇팔로 데이터를 모아 신경망을 학습시켜 자율제어까지 한 번에 잇는 end-to-end 프레임워크.

비전: 모델(Transformers)·데이터셋(Datasets)·Hub로 NLP/비전 생태계를 연 Hugging Face가, 같은 방식을 물리적 로봇으로 가져온 것. SO-100 같은 $100~$200대 3D 프린팅 로봇팔로도 실습이 가능해 커뮤니티가 빠르게 성장했다.

2. 큰 그림 — 3대 기둥

LeRobot의 모든 것은 세 기둥 위에 서 있다. 이 구조만 잡으면 나머지는 디테일이다.

기둥	역할	대표 요소
① 하드웨어 추상화	제어 로직과 하드웨어를 분리한 통일된 `Robot` 인터페이스	SO-100/101, Koch, LeKiwi, ALOHA, Unitree G1 …
② 데이터셋 인프라	비전(MP4) + 상태/행동(Parquet)을 묶은 표준 포맷 + Hub 호스팅	`LeRobotDataset`
③ 정책(Policy) 구현	SOTA 모방학습·강화학습·VLA 모델을 통일 API로 제공	ACT, Diffusion, SmolVLA, π0 …

[ 텔레오퍼레이션(사람) ]──기록──►[ LeRobotDataset ]──학습──►[ Policy(신경망) ]
        │ 리더암/키보드                  │ MP4 + Parquet            │ ACT·Diffusion·VLA
        ▼                               ▼ Hugging Face Hub         ▼
   [ 팔로워 로봇 ]◄───────────────자율 추론·제어───────────────────┘

흐름 한 줄: 사람이 로봇을 원격조종(teleoperate)하며 시연을 녹화(record) → 그 데이터로 정책을 학습(train) → 로봇이 스스로 재현(inference). 이게 모방학습(Imitation Learning)의 전부다.

3. 학습 로드맵 한눈에 (Level 0 → 5)

레벨	목표	핵심 도구/명령
L0 개념	모방학습·정책·데이터셋 용어 이해	이 문서 1~2장
L1 설치	환경 구축, Hub 로그인	`pip install lerobot`, `hf auth login`
L2 시뮬	로봇 없이 공개 데이터셋으로 학습 체험	`lerobot-train` + `lerobot/*` 데이터셋
L3 텔레옵	실물 로봇 캘리브레이션·원격조종	`lerobot-teleoperate`
L4 수집·학습	내 데이터셋 녹화 → ACT 학습	`lerobot-record` → `lerobot-train`
L5 배포	자율 추론·평가, Async, VLA 파인튜닝	`lerobot-record`(+policy), SmolVLA

처음이라면 L2(시뮬)에서 학습 파이프라인을 한 번 끝까지 돌려보고 실물 로봇(L3+)으로 넘어가는 것을 강력 추천한다. 하드웨어 디버깅과 ML 디버깅을 분리할 수 있다.

4. 환경 구축 (설치 · 계정)

# 1) 가상환경 (conda 권장)
conda create -y -n lerobot python=3.10
conda activate lerobot

# 2) 설치
pip install lerobot
#   특정 로봇/기능 extras:  pip install "lerobot[feetech]"  (SO-100/101 모터)
#                          pip install "lerobot[pi0]"      (π0 VLA)

# 3) Hugging Face 로그인 (데이터셋/모델 업로드용, write 토큰)
hf auth login --token $HF_TOKEN --add-to-git-credential

# 4) 사용자명 변수화
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

팁: GPU(CUDA) 또는 Apple Silicon(MPS)이 있으면 학습이 훨씬 빠르다. 없으면 12장의 Google Colab 경로를 쓴다. 모터 통신용 extras(feetech/dynamixel)는 실물 로봇 종류에 맞춰 설치한다.

5. 하드웨어 — 지원 로봇과 텔레오퍼레이션

LeRobot은 하드웨어 비종속이다. 모든 로봇은 동일한 Robot 인터페이스(connect(), get_observation(), send_action())를 따른다.

로봇	특징	난이도/가격
SO-100 / SO-101	입문용 5~6 DOF 저가 팔. 리더(leader)-팔로워(follower) 쌍	★ 입문 · 저가
Koch v1.1	초기 표준 저가 팔. 자료 풍부	★ 입문
LeKiwi	SO-101 팔 + 모바일 베이스(바퀴)	★★ 모바일
ALOHA / Mobile ALOHA	양팔(bimanual) 정밀 조작 플랫폼	★★★ 고급
Unitree G1 · Reachy2 · HopeJR	휴머노이드/상체 플랫폼	★★★ 연구

텔레오퍼레이션 — 사람이 리더 암을 움직이면 팔로워 로봇이 따라 한다. 이 동작을 녹화한 것이 곧 학습 데이터다. id는 캘리브레이션 파일 식별자이므로 teleoperate·record·eval에서 동일하게 써야 한다.

lerobot-teleoperate \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodem58760431541 \
  --robot.id=my_follower \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/tty.usbmodem58760431551 \
  --teleop.id=my_leader \
  --display_data=true     # rerun으로 카메라·관절 실시간 시각화

최초 실행 시 누락된 캘리브레이션을 자동 감지해 절차를 시작한다. Python API로도 동일하게 robot.send_action(teleop.get_action()) 루프를 돌릴 수 있다.

6. LeRobotDataset 포맷

LeRobot의 표준 데이터 포맷. 영상은 MP4, 상태/행동은 Parquet으로 저장하고 Hugging Face Hub에 호스팅한다. 대용량을 효율적으로 저장·스트리밍·시각화할 수 있게 설계됐다.

구성	내용
영상(MP4)	카메라별 프레임 시퀀스. 디스크/대역폭 절약
Parquet	`observation.state`(관절각 등), `action`(목표 명령), 타임스탬프
meta	fps, robot_type, feature 스키마, 통계(정규화용 mean/std)
episode	한 번의 시연(=하나의 trajectory) 단위. 데이터셋은 여러 episode의 모음

from lerobot.datasets.lerobot_dataset import LeRobotDataset
ds = LeRobotDataset("lerobot/aloha_static_coffee")   # Hub에서 바로 로드
print(ds.num_episodes, ds.num_frames, ds.fps)
print(ds.features)          # observation.images.*, observation.state, action ...
sample = ds[0]              # dict: 텐서들(이미지/상태/행동)

핵심: observation(센서로 본 것)과 action(로봇에 보낸 명령)의 시간 정렬 쌍이 데이터의 본질이다. 정책은 결국 관측 → 행동 함수를 배운다.

7. 데이터 수집 워크플로 (calibrate → record → replay)

실물 로봇 모방학습의 표준 4단계.

Calibrate — 리더/팔로워 관절 영점·범위 보정 (teleoperate 첫 실행에서 자동 유도).
Teleoperate — 손에 익을 때까지 원격조종 연습.
Record — 같은 작업을 여러 episode 반복 녹화 → 데이터셋 생성·Hub 업로드.
Replay — 녹화 trajectory를 로봇에 그대로 재생해 데이터 품질 검증.

lerobot-record \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodem585A0076841 \
  --robot.id=my_follower \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/tty.usbmodem58760431551 \
  --teleop.id=my_leader \
  --display_data=true \
  --dataset.repo_id=${HF_USER}/record-test \
  --dataset.num_episodes=5 \
  --dataset.single_task="Grab the black cube"

데이터 양 감각: 단순 픽앤플레이스라도 수십~수백 episode를 권장한다. 시작/물체 위치를 조금씩 바꿔가며 다양성을 주면 일반화가 좋아진다. “느리고 일관된 시연”이 “빠르고 들쭉날쭉한 시연”보다 학습에 유리하다.

녹화 중 키보드로 episode 조기 종료/재시도/리셋을 제어한다. 녹화가 끝나면 자동으로 Hub에 push하고, 웹 뷰어로 episode를 시각화해 품질을 점검할 수 있다.

8. 정책(Policy) 지도 — IL · RL · VLA

LeRobot의 정책은 크게 세 갈래다. 모두 --policy.type=... 한 줄로 교체된다.

분류	대표 정책	한 줄 설명
모방학습 (IL)	ACT	Action Chunking + Transformer. 입문 1순위 — 빠르고 가볍고 강력
	Diffusion Policy	행동을 디퓨전으로 생성. 멀티모달·정밀 작업에 강함
	VQ-BeT	행동을 토큰화(VQ)해 예측. 다봉(multi-modal) 행동 처리
강화학습 (RL)	TD-MPC	모델 기반 RL. 샘플 효율적
강화학습 (RL)	HIL-SERL	사람 개입형(Human-in-the-Loop) 실세계 RL
VLA (Vision-Language-Action)	SmolVLA	LeRobot 자체 경량 VLA. 커뮤니티 데이터로 학습, 파인튜닝 친화적
	π0 (Pi0)	Physical Intelligence의 flow 기반 대형 VLA
	GR00T · others	NVIDIA GR00T 등 대형 파운데이션 정책

고르는 법: 단일 작업·단일 셋업이면 ACT로 시작. 정밀하거나 행동이 여러 갈래로 갈리면 Diffusion. “말로 지시(언어 조건)”하거나 여러 작업을 한 모델로 하고 싶으면 VLA(SmolVLA)를 파인튜닝.

9. 핵심 정책 심화 — ACT · Diffusion · SmolVLA

9.1 ACT — Action Chunking with Transformers

관측을 받아 미래 여러 스텝의 행동 묶음(action chunk)을 한 번에 예측하는 Transformer. 매 스텝 단발 예측의 누적 오차(compounding error)와 끊김을 줄인다. 학습이 빠르고 자원 소모가 적어 LeRobot 입문 1순위로 공식 권장된다.

입력: 카메라 이미지 + 관절 상태(observation.state)
출력: 향후 k 스텝 action chunk (예: 100스텝)
특징: CVAE로 시연의 다양성을 흡수, temporal ensembling으로 부드러운 실행

9.2 Diffusion Policy

행동 시퀀스를 디퓨전(노이즈 제거) 과정으로 생성한다. “어디로 갈지 길이 여러 갈래”인 멀티모달 상황에서, 평균으로 뭉개지 않고 하나의 일관된 궤적을 샘플링한다. 정밀·접촉 작업에 강하나 추론이 ACT보다 무겁다.

9.3 SmolVLA

LeRobot이 내놓은 경량 Vision-Language-Action 모델. 이미지 + 자연어 지시 → 행동을 수행한다. 커뮤니티 공개 데이터로 사전학습돼 있어, 소량의 내 데이터로 파인튜닝하면 언어로 지시 가능한 멀티태스크 정책을 비교적 저렴하게 얻을 수 있다.

VLA의 의미: 기존 IL 정책이 “이 셋업, 이 한 작업”에 묶였다면, VLA는 언어 일반화를 더해 “빨간 블록을 상자에 넣어” 같은 지시를 처리한다. 단, 그만큼 모델·데이터·연산이 커진다.

10. 학습(Training) — `lerobot-train`

정책 종류와 무관하게 동일한 명령으로 학습한다. 정책은 데이터셋의 모터 수·카메라 수에 자동으로 맞춰진다.

lerobot-train \
  --dataset.repo_id=${HF_USER}/so101_test \
  --policy.type=act \
  --output_dir=outputs/train/act_so101_test \
  --job_name=act_so101_test \
  --policy.device=cuda \          # Apple silicon이면 mps
  --wandb.enable=true \           # 학습 곡선 시각화(선택)
  --policy.repo_id=${HF_USER}/my_policy

체크포인트는 outputs/train/.../checkpoints/에 저장된다.
재개: --config_path=.../checkpoints/last/pretrained_model/train_config.json --resume=true
Hub 업로드 끄기: --policy.push_to_hub=false / 비공개·태그·라이선스 옵션도 지원.
GPU가 없으면 공식 ACT 학습 Colab 노트북으로 동일 파이프라인을 돌릴 수 있다.

관측 연동 팁: 장기 학습/추론 파이프라인을 운영화하면 메트릭·트레이스를 남기고 싶어진다. 일반 관측 표준은 OpenTelemetry, LLM/에이전트 계열은 Langfuse, 대시보드는 Grafana 문서를 참고.

11. 평가·배포 — 추론과 Async Inference

평가는 학습 때 쓰던 lerobot-record에 정책을 얹는 방식이다. 텔레옵 대신 정책이 행동을 만든다는 점만 다르다. 데이터셋 이름은 관례적으로 eval_로 시작한다.

# 정책 체크포인트로 10 episode 자율 수행·녹화
lerobot-record \
  --robot.type=so100_follower \
  --robot.port=/dev/ttyACM1 \
  --robot.id=my_follower \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --dataset.repo_id=${HF_USER}/eval_act_so101 \
  --dataset.single_task="Put lego brick into the box" \
  --policy.path=outputs/train/act_so101_test/checkpoints/last/pretrained_model

# Python: 사전학습 정책 로드 후 추론 루프
from lerobot.policies.act.modeling_act import ACTPolicy
policy = ACTPolicy.from_pretrained("${HF_USER}/act_so101_test")
# get_observation() → policy → send_action() 루프 (record_loop가 처리)

Async Inference — 큰 정책(특히 VLA)은 추론 지연이 크다. LeRobot은 정책 추론과 로봇 제어 루프를 분리해, 추론이 도는 동안 로봇이 이전 action chunk를 부드럽게 실행하도록 한다. 이로써 무거운 모델도 실시간성에 가깝게 동작한다.

성공률(success rate)로 평가한다. 여러 시작 위치에서 N회 시도해 성공 비율을 본다. 실패 패턴(특정 위치·조명에서 실패)을 보고 데이터 보강 방향을 정한다.

12. 시뮬레이션 학습

실물 로봇이 없어도 시작할 수 있다. 공개 데이터셋과 시뮬 환경으로 학습 파이프라인 전체를 무료로 체험하라.

공개 데이터셋: lerobot/aloha_*, lerobot/pusht 등 Hub에서 바로 사용.
벤치마크: LIBERO, MetaWorld 등 평가용 시뮬 태스크 지원.
이점: 하드웨어 변수 없이 ML 디버깅(데이터·하이퍼파라미터·정책 선택)에 집중.

# 로봇 없이: 공개 데이터셋으로 ACT 학습만 돌려보기
lerobot-train \
  --dataset.repo_id=lerobot/pusht \
  --policy.type=act \
  --output_dir=outputs/train/act_pusht \
  --policy.device=cuda

13. 단계별 커리큘럼 & 마일스톤

이 문서를 “학습 로드맵”으로 쓰는 구체적 순서. 각 마일스톤을 통과 기준으로 삼아라.

주차	할 일	통과 기준(마일스톤)
1주	1~6장 정독, 설치, 공개 데이터셋 로드·시각화	`LeRobotDataset`을 코드로 열어 샘플 출력 성공
2주	12장 — 시뮬/공개 데이터셋으로 ACT 학습 1회 완주	체크포인트 생성 + 학습 곡선 확인
3주	5·7장 — 실물 로봇 캘리브레이션·텔레옵·녹화	내 데이터셋 20+ episode 녹화·Hub 업로드
4주	9·10장 — 내 데이터로 ACT 학습 + 11장 평가	실물 로봇 자율 픽앤플레이스 성공률 측정
5주+	Diffusion 비교, SmolVLA 파인튜닝, Async 배포	언어 지시형/멀티태스크 정책 동작

학습 원칙: ① 시뮬로 파이프라인을 먼저 끝내라(하드웨어와 ML을 분리). ② ACT를 기준선(baseline)으로 잡고 다른 정책을 비교하라. ③ 모델보다 데이터 품질·다양성이 성공률을 더 좌우한다.

14. 실전 미니 프로젝트 — 레고 집어 담기

LeRobot의 대표 입문 과제. 전 과정을 한 번에 꿰는 캡스톤이다.

셋업: SO-101 리더-팔로워 + 전면 카메라 1대 캘리브레이션.
수집: “레고 블록을 집어 상자에 넣기”를 시작 위치를 바꿔가며 50 episode 녹화.
학습: --policy.type=act로 수 시간 학습.
평가: 정책을 얹어 10 episode 자율 수행, 성공률 기록.
개선: 실패 위치를 집중 보강 녹화 → 재학습 → 성공률 상승 확인.

이 루프(수집 → 학습 → 평가 → 데이터 보강)를 도는 감각을 얻으면, 어떤 작업이든 LeRobot으로 옮길 수 있다.

15. 트러블슈팅 & 자주 막히는 곳

증상	원인/해결
포트(`/dev/tty...`)를 못 찾음	USB 재연결, 권한(`dialout` 그룹), 올바른 포트 식별. 모터 extras 설치 확인
캘리브레이션 이상/관절 튐	`id`가 record/eval과 다름 → 동일 `id` 사용. 영점 재보정
카메라 안 잡힘	`index_or_path` 인덱스 확인, fps/해상도 하향, OpenCV는 `fourcc="MJPG"` 시도
학습은 되는데 성공률 낮음	데이터 부족/단조로움 → episode 다양성↑, 일관된 시연. 정책 교체(ACT↔Diffusion)
추론이 느려 동작이 끊김	Async Inference 활용, 모델 경량화, action chunk 길이 조정
GPU 없음	Colab(ACT 노트북) 또는 `policy.device=mps`(Apple)

16. 용어 사전 & 링크

용어	뜻
Imitation Learning(모방학습)	사람 시연을 따라 하도록 정책을 학습
Teleoperation	리더 암/키보드로 로봇을 원격조종 — 데이터 수집 수단
Episode / Trajectory	한 번의 시연(관측·행동 시퀀스) 단위
Policy	관측 → 행동을 매핑하는 신경망(ACT, Diffusion, VLA …)
Action Chunk	한 번에 예측하는 미래 행동 묶음(ACT 핵심)
VLA	Vision-Language-Action. 이미지+언어 지시→행동
LeRobotDataset	MP4+Parquet 표준 데이터 포맷, Hub 호스팅
Follower / Leader	실제 작업 로봇 / 사람이 잡고 조종하는 짝 로봇

공식 링크

GitHub: github.com/huggingface/lerobot
문서: huggingface.co/docs/lerobot
모델·데이터셋 Hub: huggingface.co/lerobot
커뮤니티: LeRobot Discord