LeRobot을 읽는 가장 쉬운 기준
LeRobot 코드베이스를 처음 볼 때 모든 파일을 한 번에 이해하려고 하면 금방 길을 잃습니다. 먼저 실행 흐름을 기준으로 보면 훨씬 단순해집니다.
LeRobot의 핵심 흐름은 다음 네 가지입니다.
데이터셋을 읽는다.
LeRobotDataset이 로봇 시연 데이터, 카메라 영상, 상태 값, 행동 명령을 불러옵니다.정책을 만든다.
정책, 즉policy는 관측값을 입력받아 다음 행동을 예측하는 모델입니다. 예를 들어 ACT, Diffusion Policy 같은 방식이 여기에 해당합니다.학습하거나 평가한다.
lerobot-train은 데이터셋으로 정책을 학습하고,lerobot-eval은 저장된 정책을 환경에 연결해 성능을 확인합니다. 실제 로봇 배포와 롤아웃에는lerobot-rollout도 사용합니다.로봇 또는 환경과 연결한다.
실제 로봇은 로봇 클래스가 담당하고, 시뮬레이션 태스크는 환경, 즉env설정이 담당합니다.
공식 문서에서 소개하는 기본 진입점도 이 흐름과 맞닿아 있습니다. 정보 확인은 lerobot-info, 학습은 lerobot-train, 평가는 lerobot-eval, 데이터 기록은 lerobot-record, 실제 정책 배포는 lerobot-rollout으로 시작합니다.1 중요한 점은 이 명령들이 독립적으로 움직이는 것이 아니라, 데이터셋·정책·환경·로봇·설정 파일을 하나로 묶어 실행한다는 것입니다.
AI 생성 이미지
명령줄 진입점이 하는 일
LeRobot을 사용할 때 자주 만나는 명령은 다음과 같습니다.
lerobot-info
lerobot-train
lerobot-eval
lerobot-record
lerobot-rolloutlerobot-info는 데이터셋이나 모델의 구성을 확인할 때 유용합니다. 예제를 실행하기 전에 "이 데이터셋에 어떤 관측값이 들어 있는가?", "카메라 키는 무엇인가?", "행동 벡터의 차원은 몇 개인가?"를 확인하는 용도로 생각하면 됩니다.
lerobot-train은 학습 실행의 입구입니다. 예를 들어 다음과 같은 명령은 ACT 정책을 선택하고, 지정한 데이터셋으로 학습을 시작하라는 뜻입니다.
lerobot-train \
--policy.type=act \
--dataset.repo_id=lerobot/aloha_mobile_cabinet여기서 policy.type=act는 모델 구조와 학습 방식의 큰 틀을 정합니다. dataset.repo_id=...는 어떤 데이터셋을 사용할지 정합니다. 로컬 데이터셋을 쓸 때는 dataset.root 같은 로컬 경로 옵션을 함께 지정하는 경우가 있습니다.
lerobot-train \
--dataset.repo_id=local/my_dataset \
--dataset.root=/path/to/lerobot_dataset \
--policy.type=act \
--output_dir=outputs/train/act_baseline단, LeRobot은 활발히 바뀌는 프로젝트입니다. 어떤 버전의 문서나 예제에서는 --policy=act처럼 더 짧은 표기를 볼 수 있고, 다른 버전에서는 --policy.type=act를 사용합니다. 이 책에서는 최신 문서에서 자주 쓰이는 --policy.type=... 표기를 기본으로 삼되, 실제 실행 전에는 반드시 현재 설치한 버전의 도움말을 확인하세요.
lerobot-train --helplerobot-eval은 학습된 정책을 다시 불러와 시뮬레이션 환경에서 성능을 확인합니다.
lerobot-eval \
--policy.path=outputs/train/act_baseline/checkpoints/last/pretrained_model \
--env.type=libero \
--env.task=libero_object \
--eval.n_episodes=10실제 로봇에 정책을 배포할 때는 lerobot-rollout을 사용합니다. 평가는 "환경에서 점수를 확인하는 일"일 수도 있고, "실제 로봇에서 제한된 시간 동안 정책을 실행해 성공과 실패를 기록하는 일"일 수도 있습니다. 어느 경우든 명령줄은 단순한 실행 버튼이 아닙니다. 어떤 정책을 쓸지, 어떤 데이터셋을 읽을지, 어떤 태스크에서 평가할지, 결과를 어디에 저장할지를 연결하는 조립 지점입니다.
데이터셋 루트부터 확인하기
LeRobot에서 가장 먼저 익숙해져야 할 구성요소는 데이터셋입니다. 로봇 학습은 결국 "어떤 관측에서 어떤 행동을 했는가"를 반복해서 배우는 과정이기 때문입니다.
LeRobotDataset v3.0 형식은 사용자에게는 에피소드 단위 접근을 제공하지만, 디스크에는 여러 에피소드를 더 큰 Parquet/MP4 shard로 묶어 저장할 수 있습니다.2 단순화하면 다음과 같은 구조를 가집니다.
your_dataset/
├── meta/
│ ├── info.json
│ ├── stats.json
│ ├── tasks.jsonl
│ └── episodes/
│ └── ...parquet
├── data/
│ └── chunk-000/
│ └── file-000.parquet
└── videos/
└── chunk-000/
├── observation.images.front/
│ └── file-000.mp4
└── observation.images.wrist/
└── file-000.mp4이 구조에서 기준점은 항상 meta/info.json이 들어 있는 폴더입니다. 학습 명령에서 dataset.root를 지정할 때는 그 부모 폴더가 아니라, meta/info.json을 직접 포함한 데이터셋 루트를 가리켜야 합니다.3
예를 들어 파일이 다음처럼 있다면,
/workspace/dataset/my_task/meta/info.jsondataset.root는 다음이어야 합니다.
--dataset.root=/workspace/dataset/my_task실무에서 자주 나는 오류는 한 단계 위 폴더를 지정하는 것입니다.
# 잘못된 예
--dataset.root=/workspace/dataset이렇게 지정하면 LeRobot은 meta/info.json을 찾지 못합니다. 학습이 시작되지 않거나, 데이터셋을 찾을 수 없다는 오류가 납니다. 문제가 생기면 가장 먼저 "내가 지정한 경로 바로 아래에 meta/info.json이 있는가?"를 확인하세요.
observation과 action이 정책으로 들어가는 방식
LeRobot 데이터셋의 핵심 필드는 크게 두 종류입니다.
observation.*: 로봇이 그 시점에 본 것과 자신의 상태action: 그 시점에 사람이 내렸거나 로봇이 실행한 행동 명령
대표적인 키는 다음과 같습니다.
observation.images.front
observation.images.wrist
observation.state
action
timestamp
taskobservation.images.front는 정면 카메라 영상일 수 있습니다. 손목 카메라가 있다면 observation.images.wrist처럼 별도 키를 둘 수 있습니다. 이름 자체는 프로젝트마다 달라질 수 있지만, 중요한 것은 데이터셋의 features 정의와 학습 설정의 카메라 키가 서로 일치해야 한다는 점입니다.
observation.state는 로봇의 내부 상태입니다. 보통 관절 각도, 그리퍼 상태, 엔드이펙터 위치 같은 숫자 벡터가 들어갑니다. action은 로봇에 보낸 명령입니다. 예를 들어 목표 관절 각도, 속도 명령, 그리퍼 열기·닫기 값이 될 수 있습니다.
학습할 때 LeRobotDataset은 메타데이터를 기준으로 Parquet shard와 영상 shard를 연결해 배치를 만듭니다. 배치에는 여러 시점의 이미지, 상태, 행동이 함께 들어갑니다.
배치
├── observation.images.front → 카메라 이미지 텐서
├── observation.images.wrist → 보조 카메라 이미지 텐서
├── observation.state → 상태 벡터
└── action → 정답 행동 텐서정책은 이 배치를 입력으로 받습니다. 이미지와 상태를 보고 action을 예측합니다. 학습 중에는 예측한 행동과 데이터셋의 실제 행동을 비교해 손실을 계산합니다. 손실은 "모델이 얼마나 틀렸는가"를 나타내는 값입니다. 이 값을 줄이는 방향으로 모델 파라미터가 업데이트됩니다.
따라서 새 로봇을 붙일 때 가장 먼저 맞춰야 하는 것도 이 스키마입니다. 카메라 이름이 바뀌었는지, 상태 벡터 차원이 달라졌는지, action 차원이 정책 설정과 맞는지 확인해야 합니다.
설정 조합이 실험을 만든다
LeRobot 실험은 코드 한 줄만으로 결정되지 않습니다. 보통 다음 조합으로 결정됩니다.
policy + env/task 또는 robot/task + dataset + 하이퍼파라미터 + 출력 경로예를 들어 다음 명령은 "ALOHA 계열 데이터셋으로 ACT 정책을 학습한다"는 뜻으로 읽을 수 있습니다.
lerobot-train \
--policy.type=act \
--dataset.repo_id=lerobot/aloha_mobile_cabinet다른 예로 PushT 환경에 맞는 데이터셋과 Diffusion 계열 정책을 조합할 수도 있습니다.
lerobot-train \
--policy.type=diffusion \
--dataset.repo_id=lerobot/pusht일부 예전 예제나 연구용 포크에서는 python lerobot/scripts/train.py policy=act env=aloha처럼 Hydra 스타일의 인자를 사용하기도 합니다.4 현재 프로젝트에서 어떤 표기법을 쓰는지는 설치한 버전의 도움말을 확인하는 것이 좋습니다.
lerobot-train --help
lerobot-eval --help
lerobot-rollout --help중요한 것은 표기법 자체보다 구조입니다. policy.type=...는 모델을 바꾸고, env.type=...와 env.task=...는 시뮬레이션 문제를 바꾸며, dataset.repo_id=...와 dataset.root=...는 학습 데이터를 바꿉니다. 실제 로봇 배포에서는 여기에 robot.type, robot.port, robot.cameras, task가 더해집니다. 이 값들이 저장된 설정 파일과 함께 남아 있어야 나중에 같은 실험을 다시 실행할 수 있습니다.
학습 결과 폴더에는 보통 체크포인트, 정책 설정, 학습 상태가 저장됩니다. 체크포인트는 특정 시점의 모델 저장본입니다. 평가할 때는 이 체크포인트 안의 pretrained_model 경로를 다시 지정해 정책을 불러옵니다.
학습 루프의 내부 흐름
lerobot-train을 실행하면 내부에서는 대체로 다음 순서가 진행됩니다.
설정을 읽는다.
정책 종류, 데이터셋 경로, 배치 크기, 학습률, 출력 폴더 같은 값을 확정합니다.데이터셋을 연다.
LeRobotDataset이meta/info.json을 읽고, Parquet shard와 영상 shard를 메타데이터로 연결합니다.배치를 샘플링한다.
여러 에피소드와 여러 시점에서 학습용 샘플을 가져옵니다.정책을 실행한다.
이미지와 상태를 입력으로 넣고 action 예측값을 얻습니다.손실을 계산한다.
예측 action과 데이터셋의 실제 action을 비교합니다.optimizer가 업데이트한다.
optimizer는 손실을 줄이도록 모델의 숫자 파라미터를 조정하는 도구입니다.로그와 체크포인트를 저장한다.
학습 손실, 평가 점수, 설정 파일, 모델 가중치가 출력 폴더에 남습니다.
이 흐름을 알고 있으면 오류를 추적하기 쉽습니다. 데이터셋을 못 찾는다면 2번 문제입니다. 이미지 키가 없다는 오류가 나면 2번 또는 3번에서 데이터 스키마가 맞지 않는 것입니다. action 차원이 다르다는 오류가 나면 4번 또는 5번에서 정책 출력과 데이터셋 정답이 맞지 않는 것입니다.
평가와 배포 루프는 정책을 실행 흐름에 다시 꽂는 과정
평가는 학습과 비슷하지만 목적이 다릅니다. 학습은 정답 행동을 보고 모델을 고치는 과정입니다. 평가는 모델을 고치지 않고, 저장된 정책이 실제로 얼마나 잘 행동하는지 확인하는 과정입니다.
평가 루프는 보통 다음과 같습니다.
환경 또는 로봇 초기화
→ 관측값 수집
→ 정책이 action 예측
→ 환경 또는 로봇에 action 전달
→ 결과 기록
→ 여러 에피소드 반복실제 로봇 제어 흐름도 이와 비슷합니다. 로봇 객체를 만들고 연결한 뒤, 관측값을 읽고, 모델이 행동을 고르고, 그 행동을 로봇에 보냅니다. 공식 예제도 robot.connect(), robot.get_observation(), policy.select_action(obs), robot.send_action(action)에 가까운 흐름으로 로봇 제어를 설명합니다.1
이 구조를 이해하면 LeRobot이 특정 로봇 하나에 묶인 도구가 아니라는 점이 보입니다. 새 로봇을 쓰려면 로봇 클래스가 같은 역할을 하도록 만들면 됩니다. 즉, 연결하고, 관측을 반환하고, 행동을 받아 실행하는 인터페이스를 맞추는 것이 핵심입니다.
예제를 내 로봇 프로젝트로 바꿀 때 볼 곳
기존 예제를 새 로봇이나 새 태스크로 확장할 때는 무작정 코드를 고치지 말고 다음 순서로 추적하세요.
첫째, 데이터셋 스키마를 확인합니다. meta/info.json의 features에서 이미지 키, 상태 벡터 shape, action shape를 봅니다. 정책 설정이 이 값들과 맞아야 합니다.
둘째, 카메라 키를 맞춥니다. 예제가 observation.images.front를 기대하는데 내 데이터셋이 observation.images.main을 쓰면 학습 중 키 오류가 날 수 있습니다. 둘 중 하나를 통일해야 합니다.
셋째, 로봇 클래스 import 경로와 등록 이름을 확인합니다. 커스텀 로봇은 LeRobot의 Robot 인터페이스에 맞춰 구현하고, CLI에서 사용할 수 있도록 등록해야 합니다. 예제에서는 RobotConfig와 Robot 클래스를 함께 정의하는 방식을 보여줍니다.1
넷째, policy 설정을 봅니다. action 차원, 이미지 입력 수, 상태 입력 사용 여부가 내 데이터와 맞는지 확인합니다. ACT 예제를 Diffusion Policy로 바꾸는 것은 단순히 이름만 바꾸는 일이 아닙니다. 정책마다 필요한 시퀀스 길이, 입력 구성, 하이퍼파라미터가 다를 수 있습니다.
다섯째, env/task 또는 robot/task 설정을 확인합니다. 시뮬레이션이면 env.type, env.task가 태스크를 결정합니다. 실제 로봇이면 robot.type, robot.port, robot.cameras, task가 실행 조건을 결정합니다.
여섯째, train/eval/rollout 명령의 인자를 함께 추적합니다. 코드만 바꾸고 명령줄 인자를 예전 값으로 둔 채 실행하면, 바꾼 코드가 실제로 사용되지 않을 수 있습니다.
이 장의 핵심
LeRobot 프로젝트 구조는 파일 트리를 외우는 방식으로 이해할 필요가 없습니다. 실행 흐름으로 보면 됩니다.
명령줄 진입점
→ 설정 조합
→ LeRobotDataset
→ policy
→ env 또는 robot
→ 로그와 체크포인트자신만의 로봇 프로젝트를 만들 때 수정해야 할 곳도 이 흐름 위에 있습니다. 데이터셋 루트가 맞는지, observation/action 키가 맞는지, 정책 입력과 출력 차원이 맞는지, 로봇 클래스가 올바른 관측과 행동 인터페이스를 제공하는지 확인하면 됩니다.
예제를 따라 실행하는 단계에서는 명령어만 복사해도 됩니다. 하지만 예제를 넘어서는 순간에는 이 연결 구조를 알아야 합니다. LeRobot을 제대로 활용한다는 것은 결국 데이터, 정책, 환경, 로봇 클래스를 한 실험 안에서 일관되게 맞추는 일입니다.
참고
2LeRobotDataset v3.0 · Hugging Face
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.