메인 콘텐츠로 건너뛰기
Tilnote
Tilnote로 만들기
로버트
로버트
조회수 8•

생성형 AI 도구를 활용하여 작성 및 편집된 노트입니다.

LeRobot 코드베이스 핵심 정리 (v0.4.4)

요약

LeRobot은 Hugging Face가 만드는 PyTorch 기반 로봇 제어·학습 라이브러리다. 로봇 프로젝트에서 반복되는 모델, 데이터셋, 도구를 한 틀로 묶어 표준화하고, Hugging Face Hub에 올라온 데이터셋과 사전학습 모델을 바로 가져다 쓰는 흐름을 목표로 한다.12 v0.4.4 기준으로 Python 3.10+를 전제로 하며 라이선스는 Apache 2.0이다.2

Generated image

코드베이스 큰 그림

LeRobot의 중심은 "관측을 모으고(카메라/로봇), 정책이 액션을 고르고(모델/정책), 액션을 하드웨어나 환경에 보내며(모터/로봇/환경), 그 과정을 데이터로 남겨 다시 학습에 쓴다(데이터셋/스크립트)"로 정리할 수 있다. 그래서 코드 구조도 하드웨어 계층, 데이터 계층, 학습 계층, 실행·운영 계층이 서로 맞물리는 방식으로 나뉜다.12

소스 코드 구조(주요 모듈)와 역할

robots/, motors/, cameras/, teleoperators/는 물리 세계와 맞닿는 층이다. 로봇과 모터 드라이버가 "어떻게 움직일지"를 담당하고, 카메라가 "무엇을 볼지"를 제공하며, 텔레오퍼레이터가 "사람 입력으로 어떻게 조종할지"를 정의한다.2

datasets/, data_processing/, processor/는 데이터 층이다. 수집된 시연/로그를 LeRobotDataset 포맷으로 정리하고, 학습이 먹기 좋은 형태로 변환하거나 스트리밍 로딩 같은 실행 방식을 지원한다.12

policies/, model/, optim/, rl/는 학습·추론 층이다. 정책이 실제로 액션을 산출하는 핵심이며, 모델 베이스 클래스와 최적화/강화학습 유틸이 이를 받친다.2

envs/는 시뮬레이션 층이다. 실제 로봇이 없거나 반복 실험이 필요한 경우, 정해진 벤치마크 환경에서 동일한 인터페이스로 정책을 학습·평가하는 데 쓰인다.12

scripts/와 configs/는 운영 층이다. CLI 스크립트가 "학습/평가/수집/재생/설정"을 커맨드 한 줄로 묶고, 설정 파일이 실험 재현성과 공유를 돕는다.12

마지막으로 async_inference/, transport/, utils/, templates/는 성능과 확장성을 위한 기반이다. 비동기 추론이나 통신, 공통 유틸을 분리해 두면 로봇과 정책의 조합이 늘어도 전체 구조가 무너지지 않는다.2

하드웨어 지원 범위: 로봇·조종·카메라

LeRobot은 로봇 인터페이스를 11종으로 제공해, 소형 팔(예: SO 시리즈, Koch, OpenArm)부터 휴머노이드(hope_jr, unitree_g1), 모바일 베이스(lekiwi, earthrover_mini_plus), 그리고 reachy2 같은 고급 로봇까지 같은 파이프라인에 얹는 방향을 취한다.2

원격조종 장치는 리더 암(so/openarm/omx 계열), 게임패드, 키보드/폰 입력, 휴머노이드 전용 조종 등 12종이 정리되어 있다. 이는 데이터 수집(시연)과 실시간 테스트를 "장치만 바꿔 끼우는 방식"으로 반복하기 좋게 만든다.2

카메라는 OpenCV(일반 USB), Intel RealSense(깊이), ZMQ(네트워크), Reachy2 전용 구성이 핵심이다. 즉 센서 입력을 통일된 관측으로 뽑아내는 데 초점을 둔다.2

정책(Policies) 14종: 무엇을 바로 쓸 수 있나

정책은 크게 모방학습(IL), 강화학습(RL), 그리고 최근 흐름인 VLA(vision-language-action) 계열로 나뉜다.12 ACT, Diffusion Policy, VQ-BeT 같은 IL 계열은 시연 데이터가 있을 때 "데이터셋 → 정책 학습 → 로봇 실행"으로 직결되기 좋다. SAC, TDMPC, RTC 같은 RL 계열은 환경에서 보상 기반으로 최적화하거나, 실시간성/안정성을 고려한 제어 루프를 구성할 때 유용하다. Pi0 계열, SmolVLA, GR00T, XVLA, SARM, Wall-X 같은 VLA 계열은 이미지와 언어 지시를 함께 다루는 방향으로 확장되어, 정책을 "태스크 지시를 이해하는 실행기"로 만드는 쪽에 가깝다.2

시뮬레이션 환경: 학습·평가의 공통 운동장

ALOHA(AlohaInsertion/TransferCube), PushT, LIBERO, MetaWorld(ML1) 같은 환경이 포함된다. 중요한 점은 환경이 다양하더라도 학습/평가 스크립트와 정책 인터페이스를 일정하게 유지해 실험 비교가 쉬워진다는 것이다.12

데이터셋 표준: LeRobotDataset 포맷

LeRobotDataset은 영상과 로봇 상태/액션을 같이 다루는 "로봇 시연 데이터의 최소 단위"를 정의한다. 영상은 MP4 또는 이미지 시퀀스로 저장하고, 상태/액션은 Parquet으로 저장하는 구성이 기본이며, Hugging Face Hub에 올려 공유하고 그대로 불러오는 흐름을 염두에 둔다.12 메인 클래스 LeRobotDataset 외에, 큰 데이터를 바로 쓰기 위한 StreamingDataset, 온라인 학습을 위한 OnlineBuffer 같은 구성도 제공한다.2

CLI 스크립트: 실험을 '명령어'로 표준화

LeRobot의 장점은 주요 작업이 스크립트로 박혀 있다는 점이다. lerobot-train, lerobot-eval로 학습/평가를 돌리고, lerobot-record, lerobot-replay로 데이터 수집과 재생을 처리한다.12 실제 로봇에서 자주 막히는 부분(카메라 탐색, 포트 찾기, 모터 설정, CAN 설정, 관절 제한 탐색)은 lerobot-find-cameras, lerobot-find-port, lerobot-setup-motors, lerobot-setup-can, lerobot-find-joint-limits처럼 별도 도구로 빼서 운영 부담을 줄인다.2 데이터셋을 눈으로 확인하고 손보는 작업도 lerobot-dataset-viz, lerobot-edit-dataset, lerobot-imgtransform-viz로 분리되어 있다.2

빠른 시작 흐름: 설치 이후 무엇을 따라가면 되나

가장 단순한 진입은 uv로 가상환경을 만들고 LeRobot을 설치한 뒤 lerobot-info로 환경을 확인하는 것이다.12

uv venv
# macOS/Linux
source .venv/bin/activate
# (Windows PowerShell) .venv\Scripts\Activate.ps1

uv pip install lerobot
lerobot-info

이후 흐름은 로봇 제어의 기본 루프에 가깝다. 로봇을 연결하고, 데이터셋을 로드하거나 관측을 얻고, 정책이 액션을 선택하면 그 액션을 로봇(또는 환경)에 보내고, 필요하면 다시 데이터를 쌓아 학습으로 되돌린다.12 예를 들어 ACT 정책을 특정 데이터셋으로 학습하거나, Hub의 파인튜닝된 정책을 불러 LIBERO 태스크에서 평가하는 방식이 CLI 예시로 제공된다.1

설치/초기 세팅 스크립트(명령어) 모음

0) FFmpeg 설치(영상 저장/변환에 필요)

LeRobot은 데이터셋 영상(MP4) 저장/로딩, lerobot-dataset-viz 같은 시각화 도구에서 FFmpeg가 필요할 수 있다. lerobot-info에서 FFmpeg 감지를 확인할 수 있다.1

Ubuntu/Debian

sudo apt update
sudo apt install -y ffmpeg
ffmpeg -version

macOS (Homebrew)

brew install ffmpeg
ffmpeg -version

Windows

  1. https://ffmpeg.org 에서 Windows 빌드(zip) 다운로드 후 압축 해제

  2. ffmpeg\bin 경로를 시스템 PATH에 추가

  3. PowerShell에서 확인

ffmpeg -version

(설치 확인)

lerobot-info

1) 기본 설치(가장 단순)

uv venv
source .venv/bin/activate
uv pip install lerobot
lerobot-info

  • lerobot-info: 설치된 LeRobot/파이썬/토치/FFmpeg 등 런타임 정보를 출력해 환경 점검에 쓴다.2

2) 소스 설치(개발/로봇 하드웨어 의존성 포함)

하드웨어(모터 SDK, 카메라 드라이버 등)까지 함께 다루는 경우, 레포를 클론한 뒤 extras로 의존성을 추가 설치하는 흐름이 자주 쓰인다.2

git clone https://github.com/huggingface/lerobot.git
cd lerobot
uv venv
source .venv/bin/activate

uv pip install -e .

하드웨어별 예시(extras):2

# Feetech 기반 로봇(예: SO-101 계열 문서에서 안내)
uv pip install -e ".[feetech]"
# Intel RealSense 카메라
uv pip install -e ".[intelrealsense]"
# Dynamixel 모터
uv pip install -e ".[dynamixel]"
# LeKiwi(Feetech + ZMQ 등 포함)
uv pip install -e ".[lekiwi]"

3) 설치 직후 ‘장치 찾기/설정’용 CLI(현장 작업 필수 유틸)

아래 스크립트들은 위에서 만든 가상환경(.venv)을 활성화한 상태에서, 실제 로봇을 연결했을 때 가장 먼저 돌리는 경우가 많다.2

  • 포트 탐색

    • lerobot-find-port: USB/시리얼 포트 중 로봇(모터 버스)이 연결된 포트를 찾는 도구.

  • 카메라 탐색

    • lerobot-find-cameras: 연결된 카메라를 탐색(드라이버/디바이스 확인).

  • 모터 초기 설정

    • lerobot-setup-motors: 모터 ID/baudrate 등 초기 설정을 단계적으로 수행.

  • CAN 설정

    • lerobot-setup-can: CAN 인터페이스 설정/점검(환경에 따라 python-can 패키지 설치가 요구될 수 있음).3

  • 관절 한계 탐지

    • lerobot-find-joint-limits: 로봇 관절 범위(리밋) 탐지/기록.

  • 캘리브레이션

    • lerobot-calibrate: 로봇(또는 리더 텔레옵) 캘리브레이션 수행.

4) (예시) SO-101 문서에 나오는 대표 커맨드 흐름

# 1) 포트 찾기
lerobot-find-port

# 2) 팔(팔로워) 모터 설정
lerobot-setup-motors \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodemXXXX

# 3) 팔(팔로워) 캘리브레이션
lerobot-calibrate \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodemXXXX \
  --robot.id=my_follower

# (리더 암도 동일하게 teleop.* 옵션으로 수행)

참고

1huggingface/lerobot GitHub

2LeRobot 문서

3Bug: lerobot-setup-can fails to detect python-can package · Issue #2883 · huggingface/lerobot · GitHub

이 노트는 요약·비평·학습 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.