책에 포함된 노트LeRobot 실전 가이드: 데이터 수집부터 로봇 배포까지

Hugging Face Hub로 데이터셋과 모델 다루기

2026-05-20Views 44약 8분생성형 AI 활용

Summary

Hub는 로봇 실험의 보관소다

LeRobot을 제대로 쓰기 시작하면 곧 두 가지 자산이 쌓인다. 하나는 로봇이 움직이며 만든 데이터셋이고, 다른 하나는 그 데이터로 학습한 정책 모델이다. 로컬 폴더에만 두면 한 번의 실험으로 끝나기 쉽다. 반대로 Hugging Face Hub에 올려 두면 검색, 다운로드, 버전 관리, 팀 공유가 가능해진다.

LeRobot은 실제 로봇을 위한 모델, 데이터셋, 도구를 PyTorch 기반으로 제공하며, 공개 데이터셋과 사전학습 모델을 Hugging Face Hub에서 공유하는 것을 중요한 목표로 삼는다¹. 즉 Hub는 단순한 파일 저장소가 아니다. 로봇 실험을 다른 사람이 재현하고, 내 다음 실험이 이어받을 수 있는 형태로 만드는 작업 공간이다.

LeRobot에서 Hub 자산은 보통 repo_id로 식별한다. 예를 들어 다음과 같은 이름이다.

lerobot/aloha_mobile_cabinet
lerobot/pi0
my-team/so101_pick_cube
my-name/act_so101_pick_cube

앞부분은 사용자나 조직 이름이고, 뒷부분은 저장소 이름이다. 공식 LeRobot 자산은 대개 lerobot/... 형태로 찾을 수 있다.

Hugging Face Hub로 데이터셋과 모델 다루기 AI 생성 이미지

공개 데이터셋 찾고 내려받기

가장 먼저 할 일은 Hub에서 데이터셋을 검색하는 것이다. Hugging Face 웹사이트에서 lerobot 조직 페이지나 Datasets 검색창을 열고, lerobot, so100, so101, aloha, robotics, imitation learning 같은 키워드로 찾아본다. 중요한 것은 이름보다 내 실험 조건과 맞는지다.

LeRobot 데이터셋은 비전 정보와 로봇 상태·액션 정보를 함께 다룬다. 공식 설명에 따르면 LeRobotDataset 형식은 카메라 영상은 MP4 또는 이미지로, 상태와 액션 같은 수치 데이터는 Parquet 파일로 저장하는 구조를 사용한다². v3.0 형식에서는 여러 에피소드가 더 큰 Parquet/MP4 shard에 묶일 수 있고, episode 경계는 메타데이터로 복원된다.⁵

파이썬에서 공개 데이터셋을 불러오는 기본 흐름은 다음과 같다.

from lerobot.datasets import LeRobotDataset

dataset = LeRobotDataset("lerobot/aloha_mobile_cabinet")

sample = dataset[0]
print(sample.keys())
print(sample["action"].shape)

설치된 LeRobot 버전에 따라 import 경로나 세부 키 이름은 달라질 수 있지만, 보통 확인해야 할 항목은 비슷하다.

observation.images...: 카메라 이미지 또는 영상에서 디코딩된 프레임
observation.state: 관절 위치, 그리퍼 상태 등 로봇 상태
action: 정책이 예측해야 하는 제어 명령
timestamp: 관찰값과 행동값의 시간 정렬 정보
episode_index, frame_index: 에피소드와 프레임 위치
task: 수행한 작업 설명 또는 task ID

데이터셋을 처음 열었을 때는 학습부터 시작하지 말고 몇 개 샘플을 출력해 보자. 이미지 해상도, 카메라 개수, 액션 차원, 에피소드 길이부터 확인해야 한다. 지난 장에서 살펴본 것처럼 로봇 데이터는 "관찰값과 행동값이 같은 시간축에 잘 맞아 있는가"가 핵심이다.

LeRobot으로 직접 수집한 데이터셋도 같은 방식으로 Hub와 연결할 수 있다. 최신 문서 기준으로 실제 로봇 데이터를 기록할 때는 lerobot-record를 사용하며, --dataset.repo_id를 지정하면 해당 이름을 기준으로 데이터셋을 만들고, 설정에 따라 Hub에 업로드할 수 있다³⁵.

lerobot-record \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodemXXXX \
  --robot.cameras="{front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/tty.usbmodemYYYY \
  --dataset.repo_id=my-name/so101_pick_cube \
  --dataset.num_episodes=10 \
  --dataset.single_task="Pick up the cube"

업로드하지 않고 로컬에만 저장하고 싶다면 다음 옵션을 둔다.

--dataset.push_to_hub=false

로컬 캐시 경로는 운영체제, 환경 변수, LeRobot 버전에 따라 달라질 수 있다. 중요한 것은 "데이터셋 이름을 폴더명으로 기억하는 것"이 아니라, 항상 repo_id와 dataset revision을 기준으로 다시 불러올 수 있게 관리하는 것이다.

데이터셋 카드에서 읽어야 할 것

Hub의 데이터셋 페이지에는 보통 README 또는 데이터셋 카드가 있다. 여기에는 학습 전에 반드시 읽어야 할 정보가 들어 있다.

첫째, 태스크 설명이다. "큐브 잡기"인지, "서랍 열기"인지, "모바일 로봇 이동"인지에 따라 필요한 행동이 완전히 다르다. 이름이 비슷해도 실제 장면이 다르면 재사용성이 낮다.

둘째, 로봇 플랫폼이다. SO-100, SO-101, ALOHA, Koch, LeKiwi처럼 로봇 구조가 다르면 관절 수와 액션 차원이 달라진다. 정책은 보통 정해진 액션 벡터를 출력하므로, 로봇이 다르면 그대로 실행할 수 없다.

셋째, 카메라 구성이다. 카메라가 하나인지 여러 개인지, 손목 카메라인지 외부 카메라인지, 해상도와 프레임레이트는 어떤지 확인해야 한다. 학습된 정책은 특정 관측 키를 기대한다. 예를 들어 학습 때 observation.images.front를 봤던 정책에 실행 때 observation.images.wrist만 넣으면 입력 이름부터 맞지 않을 수 있다.

넷째, 관측 공간과 액션 공간이다. 관측 공간은 정책이 보는 입력이고, 액션 공간은 정책이 내보내는 명령이다. 관절 위치 제어인지, 속도 제어인지, 엔드이펙터 이동량인지도 중요하다. 같은 6차원 액션이라도 의미가 다르면 안전하게 재사용할 수 없다.

다섯째, 라이선스와 사용 제한이다. 공개 데이터라고 해서 모든 용도로 쓸 수 있는 것은 아니다. 상업적 사용이 제한될 수 있고, 사람 얼굴이나 사적 공간이 포함된 영상은 별도 주의가 필요하다. 팀 프로젝트에서는 라이선스를 실험 노트에 남겨 두는 습관이 좋다.

사전학습 정책 불러오기

Hub에는 데이터셋뿐 아니라 학습된 정책도 올라온다. LeRobot은 ACT, Diffusion Policy, VQ-BeT 같은 모방학습 정책과 Pi0·SmolVLA 같은 VLA 계열 모델을 다룬다². VLA는 Vision-Language-Action의 약자로, 이미지와 언어 명령을 보고 로봇 행동을 출력하는 모델 계열이다.

정책을 불러오는 대표적인 방식은 from_pretrained다. 예를 들어 특정 정책 클래스가 설치되어 있다면 다음처럼 모델 ID를 기준으로 로드할 수 있다.

# 예시: 실제 클래스 경로와 extra는 설치한 LeRobot 버전의 문서를 확인한다.
from lerobot.policies.pi0.modeling_pi0 import Pi0Policy

policy = Pi0Policy.from_pretrained("lerobot/pi0")

정책에 따라 추가 의존성이 필요할 수 있다. 공식 설치 문서는 기능별 optional extra를 제공한다고 설명한다.⁶ 예를 들어 특정 VLA 정책을 사용하려면 해당 정책 문서에서 안내하는 extra를 설치해야 한다. 이름은 버전에 따라 pi, pi0, smolvla처럼 달라질 수 있으므로, 블로그 예시를 그대로 복사하기보다 공식 문서와 현재 설치본의 오류 메시지를 기준으로 확인한다.

# 형식 예시: 실제 extra 이름은 공식 문서와 pyproject.toml에서 확인한다.
pip install -e ".[필요한_extra]"

평가는 설치된 LeRobot 버전에 맞는 명령을 사용한다. 최근 문서에서는 lerobot-eval과 lerobot-rollout 계열 명령을 중심으로 안내한다. 핵심은 같다. policy.path에 Hub 모델 ID나 로컬 체크포인트 경로를 넘긴다.

lerobot-eval \
  --policy.path=lerobot/pi0_libero_finetuned \
  --env.type=libero \
  --env.task=libero_object \
  --eval.n_episodes=10

여기서 주의할 점이 있다. 공개 정책은 "바로 내 로봇에서 잘 작동한다"는 뜻이 아니다. 사전학습 모델은 출발점이다. 로봇 종류, 카메라 위치, 조명, 물체 모양, 제어 주기가 달라지면 성능은 크게 떨어질 수 있다. 특히 큰 VLA 정책도 자기 환경 데이터로 파인튜닝하거나, 최소한 제한된 조건에서 안전 평가를 거친 뒤 사용해야 한다.⁴

내 체크포인트를 Hub에 올리기

학습이 끝나면 결과물을 폴더에 방치하지 말고 하나의 모델 저장소로 묶어야 한다. 최소한 다음 파일과 정보는 함께 보존하는 것이 좋다.

학습된 체크포인트
정책 설정 파일
데이터셋 repo_id와 revision
학습 명령어 또는 설정 전체
평가 결과
사용한 LeRobot 버전과 주요 의존성
모델 카드 README

학습 명령은 버전에 따라 다르지만, 기본 구조는 다음과 같다.

lerobot-train \
  --dataset.repo_id=my-name/so101_pick_cube \
  --policy.type=act \
  --output_dir=outputs/train/act_so101_pick_cube \
  --job_name=act_so101_pick_cube \
  --policy.device=cuda

학습 결과는 보통 outputs/train/.../checkpoints/... 아래에 저장된다. 예를 들어 마지막 체크포인트의 사전학습 모델 폴더와 설정 파일을 함께 관리한다.³

outputs/train/act_so101_pick_cube/checkpoints/last/pretrained_model
outputs/train/act_so101_pick_cube/checkpoints/last/pretrained_model/train_config.json

Hub에 올릴 때는 LeRobot이 제공하는 push 옵션, Hugging Face Hub API, 또는 버전에 맞는 업로드 도구를 사용한다. 최신 명령과 옵션은 lerobot-train --help, 저장소 README, Hugging Face Hub 문서를 확인한다. 모델 저장소 이름은 재사용자가 이해하기 쉽게 짓는다.

my-name/act_so101_pick_cube
my-team/diffusion_so100_drawer_open_v2

좋은 모델 카드는 짧아도 충분히 유용하다. "어떤 로봇에서, 어떤 데이터셋으로, 어떤 태스크를, 어떤 설정으로 학습했는지"를 적으면 된다. 평가 성공률과 실패 사례도 함께 쓰자. 성공률만 남기면 다음 실험자가 같은 실수를 반복한다.

팀에서 권한과 이력을 관리하기

개인 실험은 공개 저장소로 시작해도 되지만, 팀 프로젝트는 권한 관리가 필요하다. Hugging Face 계정으로 로그인하고 토큰을 등록하면 명령줄에서 데이터셋과 모델을 올릴 수 있다³. 최근 Hugging Face CLI에서는 다음 명령을 주로 사용한다.

hf auth login
hf auth whoami

구버전 문서에는 huggingface-cli login이 남아 있을 수 있다. 둘 중 하나로 인증이 되면 되지만, 새 프로젝트라면 hf auth ... 흐름을 우선 확인한다.

조직 저장소를 쓰면 개인 노트북이 바뀌어도 실험 자산이 팀에 남는다. 데이터셋은 비공개로 두고 모델만 공개할 수도 있고, 반대로 논문 제출 전까지 모든 저장소를 비공개로 유지할 수도 있다. 중요한 것은 공개/비공개 여부보다 누가 읽고 쓸 수 있는지를 명확히 하는 것이다.

커밋 이력과 태그도 실험 관리 도구로 활용하자.

v0.1-data-cleaned: 데이터 정제 완료
v0.2-act-baseline: ACT 첫 기준 모델
v0.3-camera-fixed: 카메라 위치 수정 후 재학습
eval-2026-05-20: 특정 평가 결과 보존

README를 업데이트하는 것도 실험의 일부다. 데이터 수집 날짜, 로봇 수리 여부, 카메라 변경, 정규화 통계 재계산 같은 정보는 나중에 성능 차이를 설명하는 단서가 된다.

공개 자산을 안전하게 재사용하는 체크리스트

다른 사람이 올린 데이터셋이나 정책을 사용할 때는 다음 항목을 확인하자.

LeRobot 버전: 저장소가 만들어진 시점의 코드와 내 코드가 호환되는가?
로봇 종류: SO-100, SO-101, ALOHA 등 플랫폼이 같은가?
카메라 수와 위치: 입력 이미지 키, 해상도, 시점이 맞는가?
관측 키 이름: 정책이 기대하는 observation.* 이름과 내 환경 출력이 같은가?
액션 차원과 의미: 관절 위치, 속도, 그리퍼 명령의 순서가 같은가?
제어 주기: 초당 몇 번 행동을 보내는지 학습 조건과 맞는가?
정규화 통계: 상태와 액션을 어떤 평균·표준편차 또는 범위로 정규화했는가?
의존성 옵션: 특정 정책에 별도 extra 설치가 필요한가?
라이선스: 내 사용 목적과 충돌하지 않는가?
평가 환경: 시뮬레이션용 정책인지 실제 로봇용 정책인지 구분했는가?

이 체크리스트를 통과하지 못하면 바로 배포하지 말고, 먼저 오프라인 평가나 시뮬레이션 평가를 하자. 실제 로봇에서 테스트할 때는 속도 제한, 비상 정지, 사람과의 거리 확보가 우선이다.

Hub를 잘 쓰면 LeRobot 실험은 한 번의 실행으로 끝나지 않는다. 데이터셋은 다음 학습의 재료가 되고, 체크포인트는 다음 정책의 출발점이 되며, 카드와 커밋 이력은 팀의 기억이 된다. 이것이 개인 실험을 재사용 가능한 로보틱스 자산으로 바꾸는 가장 현실적인 방법이다.

참고

¹LeRobot Hugging Face 조직 페이지

²Hugging Face LeRobot GitHub 저장소

³LeRobot SO-100/SO-101 실행 예시와 Hub 업로드 흐름

⁴LeRobot에서 π0와 π0-FAST 사용하기

⁵LeRobotDataset v3.0 · Hugging Face

⁶Hugging Face LeRobot 설치 문서

책 목록

LeRobot 실전 가이드: 데이터 수집부터 로봇 배포까지

전체 목차 보기