만들 로봇과 준비물
LeRobot은 Hugging Face의 오픈소스 로봇공학 라이브러리입니다. 하나의 명령어 체계로 로봇을 움직이고, 시연을 녹화하고, 정책을 학습시키고, 실행할 수 있습니다. SO-101은 LeRobot의 대표 로봇 팔입니다. 사람이 리더 암을 손으로 움직이면 팔로워 암이 그대로 따라 움직이고, 이때 녹화된 동작과 카메라 이미지로 신경망이 같은 작업을 스스로 반복하도록 학습합니다.
작업은 일곱 단계로 이루어집니다. 부품을 구하고 소프트웨어를 설치하고, 모든 모터에 ID를 지정하고, 두 팔을 조립하고, 보정하고, 카메라를 붙여 원격 조작하고, 데이터셋을 녹화한 다음 정책을 학습시켜 실행합니다. 마지막 제작 섹션에서는 LeKiwi 이동 베이스를 추가하고, 이어서 문제 해결 체크리스트를 제공합니다.
좌우로 스크롤하면 그림 전체를 볼 수 있습니다.
팔 두 개(부품은 다음 섹션에 있습니다), 팔마다 USB 버스 서보 제어 보드와 전원 공급 장치 하나씩, Python 3.12 이상이 설치된 컴퓨터, USB 카메라 두 대(이 가이드의 명령어는 두 대를 사용합니다), 데이터셋과 체크포인트를 올릴 무료 Hugging Face 계정, 그리고 학습용 GPU가 필요합니다. 여기서 쓰는 ACT 정책에는 노트북급 GPU로도 충분하며, 임대한 GPU를 써도 됩니다.
이 가이드는 공식 문서와 커뮤니티의 제작 후기를 바탕으로 정리했으며, 모든 하드웨어 리비전에서 모든 단계를 직접 시험해 본 것은 아닙니다. control_robot.py를 호출하는 예전 튜토리얼은 lerobot-* 명령어를 쓰는 0.7.0에는 적용되지 않습니다.
부품, 3D 프린팅, 전원
SO-101 프로젝트는 부품 목록과 출력 파일을 공개하며, Hugging Face의 SO-101 페이지에서 두 가지 모두 링크로 연결됩니다. 리더와 팔로워 한 쌍을 완성하려면 Feetech STS3215 서보 12개, 제어 보드 두 개, 전원 공급 장치 두 개, USB-C 케이블 두 개, 테이블 클램프가 필요합니다. 조립에는 M2×6과 M3×6 나사를 쓰는데, 프로젝트의 부품 목록에는 나사가 없으니 서보나 키트에 무엇이 들어 있는지 확인하세요. 출력된 부품과 구성품이 모두 들어 있는 키트도 판매됩니다.
팔로워는 기어비 1/345의 서보 여섯 개를 사용합니다. 리더는 서로 다른 기어비 세 가지를 사용하므로, 자체 무게를 버티면서도 작은 힘으로 움직일 수 있습니다.
전원 공급 장치는 서보에 맞게 선택합니다. 7.4 V STS3215 서보의 스톨 토크는 6 V에서 16.5 kg·cm이고(5 V 전원에서는 이보다 약간 낮습니다) 보통 5 V 전원 공급 장치로 구동합니다. 팔로워는 더 큰 힘을 위해 12 V 서보(30 kg·cm)를 쓸 수도 있지만, 이 경우 5 A 이상 정격의 12 V 전원 공급 장치가 필요합니다. 리더는 항상 7.4 V 서보를 사용합니다. 7.4 V 서보가 연결된 보드에는 절대 12 V 전원 공급 장치를 연결하지 마세요. 전원 공급 장치마다 전압과 어느 팔용인지 표시해 두세요.
좌우로 스크롤하면 그림 전체를 볼 수 있습니다.
PLA+로 출력하며, 노즐 0.4 mm에 레이어 0.2 mm(또는 노즐 0.6 mm에 레이어 0.4 mm), 인필 15%로 설정합니다. 각 팔의 부품은 서포트가 적게 필요한 방향으로 배치된 단일 파일로 제공되며, 수평 나사 구멍 안에는 서포트가 생기지 않게 합니다. 먼저 Gauge Zero와 Gauge Tight 시험 조각을 출력해 서보에 대어 확인하고, Gauge Zero가 프로젝트 영상에서 보여 주는 것처럼 맞지 않으면 프린터 설정을 조정해 다시 출력한 뒤에 팔 부품을 출력합니다.
십자 드라이버 #0과 #1을 준비하고, 테스트하기 전에 각 베이스를 테이블에 클램프로 고정합니다. 이 제작에 쓰이는 부품 중 저희가 공급하는 것은 아래에 링크되어 있습니다.
옆으로 스크롤하여 모든 열을 비교하세요.
| 관절 | 모터 ID | 리더 기어비 | 팔로워 기어비 |
|---|---|---|---|
| 어깨 팬(회전) | 1 | 1/191 | 1/345 |
| 어깨 리프트(올림) | 2 | 1/345 | 1/345 |
| 팔꿈치 플렉스(굽힘) | 3 | 1/191 | 1/345 |
| 손목 플렉스(굽힘) | 4 | 1/147 | 1/345 |
| 손목 롤(회전) | 5 | 1/147 | 1/345 |
| 그리퍼 | 6 | 1/147 | 1/345 |
LeRobot과 모터 지원 설치
LeRobot 0.7.0에는 Python 3.12 이상이 필요합니다. conda(miniforge) 또는 uv로 독립된 환경을 만들고, 새 터미널을 열 때마다 활성화합니다. 동영상 처리에는 대부분의 플랫폼에서 ffmpeg가 필요합니다(Intel Mac의 macOS와 32비트 ARM Linux에서는 LeRobot이 대신 PyAV를 쓰므로 건너뛰어도 됩니다). conda 패키지는 모든 PyTorch 버전에서 동작합니다.
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge필요한 extras와 함께 PyPI에서 LeRobot을 설치합니다. core_scripts는 녹화, 재생, 보정에 쓰이는 구성 요소를, feetech는 STS3215 서보 지원을, training은 학습 도구를 추가합니다.
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'플랫폼별 참고 사항입니다. Apple silicon에서 PyTorch를 쓰려면 macOS 14 이상이 필요하고, GPU(MPS) 가속에는 macOS 15 이상이 필요합니다. Linux에서 NVIDIA GPU를 쓰려면 기본 PyTorch 빌드에 드라이버 580.65 이상이 필요하며, 드라이버가 더 오래되었다면 먼저 맞는 CUDA 빌드의 PyTorch를 설치하고 torchcodec은 CPU 인덱스에서 받습니다(Hugging Face 설치 페이지 참고). WSL 안에서는 evdev도 설치합니다(conda install evdev -c conda-forge, uv를 쓴다면 sudo apt install libevdev-dev를 실행한 뒤 uv pip install evdev). PyTorch 2.10 이상에서는 conda의 ffmpeg 대신 시스템 ffmpeg를 사용할 수 있습니다.
포트 찾기와 모터 ID 설정
새 STS3215 서보는 보통 ID 1로 출하되며, 컨트롤러와 모든 서보는 같은 보드레이트를 사용해야 합니다. LeRobot은 이 두 값을 각 서보의 메모리에 한 번 기록하므로, 조립하기 전에 서보를 한 개씩만 연결해서 진행합니다. 다른 로봇에서 가져온 서보에도 아마 같은 작업이 필요할 것입니다.
좌우로 스크롤하면 그림 전체를 볼 수 있습니다.
제어 보드를 USB로 컴퓨터에 연결하고 전원을 켠 다음 포트 탐색 도구를 실행합니다. 안내가 나오면 해당 보드의 USB 케이블만 뽑고 Enter를 누릅니다. 그러면 스크립트가 Linux에서는 /dev/ttyACM0, macOS에서는 /dev/tty.usbmodem…, Windows에서는 COM3 같은 포트를 출력합니다. 케이블을 다시 꽂은 뒤 두 번째 보드로도 반복합니다. Linux에서는 각 포트에 sudo chmod 666으로 접근을 허용해야 할 수 있습니다(예: /dev/ttyACM0과 /dev/ttyACM1).
lerobot-find-port팔로워용 설정 스크립트를 먼저 실행한 다음 리더용을 실행하며, 각각 자신의 포트를 지정합니다. 스크립트는 한 번에 모터 하나씩 지정하므로, 실행하기 전에 아래 단계를 먼저 읽어 보세요.
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0리더는 로봇 옵션이 아니라 원격 조작 장치(teleop) 옵션을 사용합니다. 안내가 나올 때마다 부품 섹션의 표에서 해당 관절에 지정된 기어비의 모터를 고르고(리더에서는 어깨 팬과 팔꿈치 플렉스가 1/191, 어깨 리프트가 1/345, 손목 플렉스·손목 롤·그리퍼가 1/147입니다), 스크립트가 설정되었다고 알려 주면 바로 각 모터에 ID를 표시해 둡니다.
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- 스크립트는 그리퍼(ID 6)부터 시작해 어깨 팬(ID 1)으로 끝나도록 모터를 한 번에 하나씩 지정합니다. 지정된 모터 하나만 제어 보드에 연결하며, 다른 모터와 체인으로 연결되어 있으면 안 됩니다.
- Enter를 누릅니다. ID가 설정되었다고 스크립트가 알려 주면 해당 모터의 케이블을 보드에서 뽑고, 스크립트가 지정하는 다음 모터를 연결한 뒤 다시 Enter를 누릅니다.
- Enter를 누르기 전에 전원, USB, 3핀 케이블을 확인합니다. 스크립트가 오류를 알리면 먼저 이 케이블들을 확인하고, Waveshare 보드에서는 점퍼 두 개가 모두 채널 B(USB)에 있어야 합니다.
- 스크립트가 끝나면 모터를 순서대로 체인으로 연결하고, 어깨 팬 모터(ID 1)를 제어 보드에 연결합니다.
좌우로 스크롤하면 그림 전체를 볼 수 있습니다.
서보를 한 번에 하나씩 연결해 모터 ID를 설정한 뒤, 순서대로 체인으로 연결하기
리더 암과 팔로워 암 조립
두 팔은 출력 부품 대부분을 공유하며 조립 순서도 같습니다(손목 롤 부품은 다르고, 팔로워에 움직이는 집게가 있는 자리에 리더는 손잡이와 트리거가 있습니다). 베이스와 어깨, 상완, 전완, 손목 순으로 만들고, 마지막으로 팔로워에는 그리퍼를, 리더에는 손잡이와 트리거를 붙입니다. Hugging Face는 SO-101 페이지에 관절마다 짧은 영상을 공개하고 있으니 이 안내와 함께 보면서 따라 하세요. 먼저 출력된 부품에서 서포트 재료를 모두 제거하고, 서보를 닫아 넣기 전에 모든 서보에 3핀 케이블을 꽂아 둡니다.
- 관절 1, 어깨 팬: 모터에 혼 두 개를 모두 끼우고 위쪽 혼을 M3×6 나사 하나로 고정합니다(아래쪽 혼에는 나사가 필요 없습니다). 모터를 M2×6 나사 네 개로 베이스에 장착하고, 첫 번째 모터 홀더를 M2×6 나사 두 개로 밀어 끼운 다음, 어깨를 M3×6 나사로 위쪽에 네 개, 아래쪽에 네 개 고정하고 어깨 모터 홀더를 추가합니다.
- 관절 2, 어깨 리프트: 혼 두 개를 모두 끼우고 위쪽 혼은 M3×6 나사 하나로 고정한 다음(아래쪽 혼에는 필요 없습니다), 모터를 위에서 밀어 넣어 M2×6 나사 네 개로 고정하고, 상완을 양쪽에 M3×6 나사 네 개씩으로 붙입니다.
- 관절 3, 팔꿈치: 혼 두 개를 모두 끼우고 위쪽 혼은 M3×6 나사 하나로 고정한 다음(아래쪽 혼에는 필요 없습니다), 모터 3을 M2×6 나사 네 개로 넣고, 전완을 양쪽에 M3×6 나사 네 개씩으로 연결합니다.
- 관절 4, 손목 플렉스: 혼 두 개를 모두 끼우고 위쪽 혼은 M3×6 나사 하나로 고정한 다음(아래쪽 혼에는 필요 없습니다), 모터 홀더 4를 밀어 씌우고, 모터 4를 밀어 넣어 M2×6 나사 네 개로 고정합니다.
- 관절 5, 손목 롤: 모터 5를 손목 홀더에 앞쪽 M2×6 나사 두 개로 넣고, 혼 하나를 M3×6 나사로 끼운 다음, 손목을 모터 4에 공식 관절 5 영상에 나온 대로 M3×6 나사로 고정합니다(서면 안내에는 양쪽에 네 개씩이라고 되어 있습니다).
- 팔로워 그리퍼: 그리퍼를 손목 모터의 혼에 M3×6 나사 네 개로 붙이고, 그리퍼 모터를 양쪽 M2×6 나사 두 개씩으로 장착한 다음, 혼 두 개를 모두 끼우고 위쪽 혼은 M3×6 나사 하나로 고정하고(아래쪽 혼에는 필요 없습니다), 집게는 공식 그리퍼 영상에 나온 대로 M3×6 나사로 고정합니다(서면 안내에는 양쪽에 네 개씩이라고 되어 있습니다).
- 리더 손잡이: 리더 홀더를 손목에 M3×6 나사 네 개로 장착하고, 손잡이를 M2×6 나사 하나로 홀더에 고정합니다. 모터 6, 즉 트리거 모터(공식 가이드에서는 그리퍼 모터라고 부릅니다)를 양쪽 M2×6 나사 두 개씩으로 끼우고 혼을 M3×6 나사로 장착한 뒤, 트리거를 M3×6 나사 네 개로 붙입니다.
- 전원을 넣기 전에 각 관절을 손으로 천천히 전체 가동 범위까지 돌려 보되, 멈춤 지점을 넘어 억지로 돌리지 마세요. 긁히는 곳 없이 움직여야 합니다. 모터를 닫아 넣기 전에 각 모터에 ID를 표시해 두고, 두 베이스를 테이블에 클램프로 고정합니다.
두 팔 보정
보정은 각 관절의 가동 범위를 기록하여 리더와 팔로워가 같은 물리적 자세에서 같은 값을 보고하게 합니다. 또한 한 로봇에서 학습한 정책을 다른 로봇에서 실행할 수 있게 해 줍니다. 팔마다 한 번씩 실시하고, 하드웨어를 바꾼 뒤나 LeRobot이 보정이 없다고 알려 줄 때 다시 합니다. 다시 보정하기 전에 만든 녹화 데이터와 정책은 이전 보정을 기준으로 한 것입니다.
팔로워를 먼저 보정합니다. 스크립트가 모든 관절을 가동 범위의 중간에 놓고 Enter를 누르라고 안내한 다음, 각 관절을 전체 가동 범위로 움직이게 하고 모든 관절을 다 움직였으면 Enter를 다시 누르라고 안내합니다. 팔마다 고유한 id를 지정하세요. 이 이름이 보정 파일의 이름이 됩니다. 이 가이드의 명령어는 예시로 팔로워에 /dev/ttyACM0, 리더에 /dev/ttyACM1을 사용합니다. 직접 찾은 포트로 바꿔 쓰고, 두 팔을 서로 바꾸지 마세요.
좌우로 스크롤하면 그림 전체를 볼 수 있습니다.
lerobot-calibrate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm그런 다음 같은 동작으로 리더를 보정합니다.
lerobot-calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm이후의 모든 명령에서 같은 id를 사용합니다. LeRobot은 이렇게 보정 파일을 찾으며, 이 파일은 기본적으로 ~/.cache/huggingface/lerobot/calibration 아래에 저장됩니다. 파일을 백업하고 임시 폴더에는 두지 마세요. 한 커뮤니티 제작자는 전원을 껐다 켜는 과정에서 보정 파일을 잃어버렸고, 모든 관절을 가동 범위 중간에 놓지 않은 채 다시 보정하는 바람에 일부 관절의 호밍 오프셋이 잘못되었습니다.
리더로 팔로워 원격 조작
원격 조작은 두 팔을 연결하여 팔로워가 리더를 따라 움직이게 합니다. 보정이 없으면 명령이 먼저 보정 절차를 시작합니다. 작고 느린 동작으로 시작하고, 팔로워의 관절에서 떨어져 있으며, 전원 공급 장치를 손이 닿는 곳에 둡니다.
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm다음으로 카메라를 추가합니다. 카메라 탐색 도구로 카메라를 나열하면 각 카메라의 식별자가 출력되고, 카메라마다 테스트 프레임이 outputs/captured_images에 저장됩니다. 프레임을 열어 어느 인덱스가 어느 카메라인지 확인하세요. 인덱스는 재부팅하거나 카메라를 다시 꽂으면 바뀔 수 있습니다.
lerobot-find-cameras opencv이번에는 카메라를 연결하고 Rerun의 실시간 화면을 켠 채로 다시 원격 조작합니다. 여기서 정하는 카메라 이름(예: top, wrist)이 나중에 데이터셋의 키가 되므로, 지금부터 같은 이름과 설정을 계속 사용하세요.
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=true정책이 학습할 수 있도록 카메라 배치
정책은 카메라 이미지와 관절 위치만 봅니다. 그래서 높은 해상도보다 좋은 카메라 설정이 더 중요합니다. 대부분의 작업에는 640×480, 30 fps면 충분하며, 녹화와 학습도 빠르게 유지됩니다.
좌우로 스크롤하면 그림 전체를 볼 수 있습니다.
- 확산광으로 장면을 고르게 비춥니다. 직사광선, 강한 반사, 움직이는 그림자는 피하세요. 녹화할 때와 실행할 때 조명이 다르면 정책이 실패할 수 있습니다.
- 카메라는 단단히 고정하고 녹화와 실행 사이에 절대 움직이지 마세요. 한 커뮤니티 제작자의 첫 정책은 테이블만 쪼아 댔는데, 여러 원인 중 하나는 녹화와 테스트 사이에 카메라가 조금 움직인 것이었습니다.
- 작업을 화면에 담습니다. 물체, 그리퍼, 목표 지점이 적어도 한 카메라에는 보여야 합니다. 카메라 이미지만 보고도 직접 그 작업을 할 수 있는지가 좋은 시험 기준입니다. 같은 커뮤니티 제작자는 카메라 화면만 보면서 시연했습니다. 그렇게 해 본다면 전원 공급 장치를 손이 닿는 곳에 두세요.
- 같은 제작자는 잡는 동안 그리퍼 끝이 잘 보이지 않던 측면 카메라를 정면 카메라 옆에 둔 상단 카메라로 바꿔 가림을 줄였습니다. 손목 카메라는 그 글에서 다음 단계로만 언급됩니다. 하루 종일 녹화한다면 웹캠 자체 설정에서 노출과 화이트 밸런스를 고정하세요. LeRobot의 RealSense 카메라 설정은
exposure,gain,white_balance도 받습니다. - Ubuntu에서 동일한 웹캠 두 대를 쓰면 USB 주소가 서로 바뀌어 카메라 오류로 녹화가 멈출 수 있습니다. 같은 제작자는 각 카메라를 물리 USB 포트로 식별하는 udev 규칙으로 이를 해결했으니, 각 카메라를 항상 같은 포트에 꽂아 두세요. 그렇게 하지 않으면 재부팅할 때마다 카메라 탐색 도구를 다시 실행하세요.
데이터셋 녹화
데이터셋은 LeRobotDataset 형식을 사용하며 Hugging Face Hub에 업로드됩니다. 무료 계정을 만들고 Hugging Face 설정에서 쓰기 권한이 있는 토큰을 발급한 다음, 로그인하고 사용자 이름을 변수에 저장해 둡니다. 먼저 HUGGINGFACE_TOKEN을 본인의 토큰으로 설정하거나, hf auth login을 단독으로 실행하고 요청이 나오면 토큰을 붙여 넣으세요.
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER설정을 시험하려면 먼저 에피소드 5개를 녹화합니다. 원격 조작 때와 같은 로봇 id, 포트, 카메라 설정을 사용하고, 작업을 쉬운 말로 설명합니다.
lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=true \
--dataset.repo_id=${HF_USER}/record-test \
--dataset.num_episodes=5 \
--dataset.single_task="Grab the black cube" \
--dataset.streaming_encoding=trueLeRobot은 데이터셋 이름 뒤에 날짜와 시간을 붙이므로 ${HF_USER}/record-test는 ${HF_USER}/record-test_YYYYMMDD_HHMMSS로 저장됩니다. 이후 명령에서는 이 전체 이름을 사용하세요. 이름은 ls ~/.cache/huggingface/lerobot/${HF_USER}로 확인할 수 있고, 입력한 이름을 그대로 두려면 --dataset.no_stamp=true를 추가합니다. 데이터셋은 ~/.cache/huggingface/lerobot에 저장되고 녹화가 끝나면 Hub로 푸시됩니다. 개인 계정에서 푸시한 데이터셋은 공개 상태일 수 있으니 Hub에서 공개 여부를 확인하고, 비공개여야 한다면 --dataset.private=true를 추가하세요. 로컬에만 두려면 --dataset.push_to_hub=False를 추가합니다. 중단된 세션을 이어서 하려면 --resume=true, 타임스탬프가 붙은 전체 --dataset.repo_id, 데이터셋의 로컬 폴더로 지정한 --dataset.root, 그리고 전체 개수가 아니라 추가로 녹화할 에피소드 수로 지정한 --dataset.num_episodes를 넣어 명령을 다시 실행합니다.
에피소드 시간과 리셋 시간의 기본값은 각각 60초(--dataset.episode_time_s, --dataset.reset_time_s)이고, 에피소드 수의 기본값은 50입니다. 녹화하는 동안에는 아래 표와 같이 키보드로 진행을 제어합니다.
처음 쓸 만한 데이터셋은 여러 위치에서 물체를 집어 상자에 넣는 것처럼 단순한 작업으로 만듭니다. 최소 50개의 에피소드를 녹화하되 위치당 약 10개씩 넣고, 카메라와 잡는 방식을 일관되게 유지하며, 다양성은 천천히 늘립니다. 실패한 에피소드는 다시 녹화하세요. 고정된 위치에서 녹화한 에피소드 50개는 시작점일 뿐이며, 정책은 주로 녹화한 위치 근처에서 작동한다고 보면 됩니다. LeRobot은 저장한 에피소드마다 주기 줄을 출력하고 녹화가 끝나면 요약을 출력합니다. 주기가 목표인 30 Hz보다 크게 낮더라도 데이터셋에는 여전히 30 Hz로 기록되므로 동작이 실제보다 빠르게 보입니다. 무엇이 루프를 느리게 하는지 찾아(문서의 예에서는 카메라 읽기였습니다) 해당 에피소드로 학습하지 말고 다시 녹화하세요.
학습하기 전에 데이터를 확인합니다. Hugging Face의 LeRobot 데이터셋 시각화 도구에서 데이터셋을 열어 보고, 로봇에서 에피소드를 재생하여 동작이 반복되는지 시험합니다. 재생하면 팔이 사용자의 조작 없이 움직이므로, 작업 공간을 비우고 팔을 에피소드의 첫 자세 근처에서 시작하며 전원 공급 장치를 손이 닿는 곳에 두세요.
lerobot-replay \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--dataset.episode=0옆으로 스크롤하여 모든 열을 비교하세요.
| 키 | 동작 |
|---|---|
| 오른쪽 화살표 또는 n | 에피소드 또는 리셋 구간을 일찍 끝내고 다음으로 넘어갑니다 |
| 왼쪽 화살표 또는 r | 현재 에피소드를 버리고 다시 녹화합니다 |
| Esc 또는 q | 세션을 중지합니다. 진행 중인 에피소드는 저장되고, 이어서 영상이 인코딩되고 데이터셋이 업로드됩니다(그 에피소드를 버리려면 먼저 왼쪽 화살표 또는 r을 누르세요) |
ACT 정책 학습
ACT(Action Chunking Transformer)는 LeRobot 튜토리얼에서 쓰는 정책입니다. 데이터셋에 저장된 모터와 카메라에 맞춰집니다. 하드웨어 가이드는 가벼운 정책(ACT, VQ-BeT, TD-MPC)의 GPU 메모리를 배치 크기 8에서 약 2~6 GB로 보며, 이는 참고용 수치입니다. NVIDIA GPU(cuda)에서 학습하세요. Apple silicon에서는 명령을 --policy.device=mps로 바꿔야 하며, macOS 15 이상이 필요합니다(macOS 14에서는 LeRobot이 CPU로 대체되는데, CPU는 학습에 적합하지 않습니다).
전체 데이터셋 이름으로 학습을 시작합니다.
lerobot-train \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--trackio.enable=true \
--policy.repo_id=${HF_USER}/my_policy \
--steps=20000--steps 없이 실행하면 학습은 100,000 스텝을 진행하는데, 작은 데이터셋에는 대체로 필요 이상으로 많은 양입니다. 모방 학습은 보통 데이터를 5~10회 훑으면 수렴합니다. 30초짜리 에피소드 50개로 이루어진 데이터셋을 30 fps로 녹화하면 프레임이 약 45,000개이고, 배치 크기 8에서는 한 번 훑는 데 약 5,600 스텝이 드니 5~10회 훑는 데는 대략 28,000~56,000 스텝이 필요합니다. 위의 명령은 짧은 첫 실행으로 약 3.5회 훑는 --steps=20000을 사용합니다. 정책이 덜 학습되었다면 값을 늘리고, 훨씬 낮게 줄인다면 --policy.scheduler_decay_steps도 --steps에 가깝게 설정하세요. 하드웨어 가이드는 배치 크기 8에서 ACT를 5회 훑는 데 RTX 3090 또는 4090에서 약 30~60분, L4 또는 A10G에서 1~2시간, M1, M2 또는 M3 Max에서는 배치 크기 4로 6~14시간이 걸리는 것으로 추정합니다. 이 수치는 참고용이며 실제 실행은 약 50% 정도 달라질 수 있다고 밝힙니다.
적합한 GPU가 없다면 ACT 노트북으로 Google Colab에서 학습하거나, hf auth login을 실행한 뒤 같은 명령에 --job.target=a10g-small 같은 Hugging Face Jobs 플레이버를 추가합니다. 이 명령은 Trackio를 켜 두므로 작업에는 --trackio.space_id=<user>/<space>도 필요하며(Space를 비공개로 두려면 --trackio.private=true를 추가), 그렇지 않으면 --trackio.enable=true를 제거하세요. Jobs는 초 단위로 요금이 청구되고 --job.timeout을 설정하지 않으면 최대 48시간으로 제한되며, 로컬에만 있는 데이터셋은 비공개 저장소에 대신 업로드해 주고, 학습이 끝나면 모델을 푸시합니다. hf jobs hardware로 플레이버 목록을 볼 수 있습니다.
체크포인트는 outputs/train/act_so101_test/checkpoints에 저장됩니다. 중단된 학습은 마지막 체크포인트에서 재개합니다. 학습 명령이 --policy.repo_id=${HF_USER}/my_policy를 지정하므로 완성된 모델은 마지막에 해당 저장소로 푸시됩니다(--policy.push_to_hub=false로 끄고, --policy.private=true로 비공개로 만들 수 있습니다). 체크포인트를 직접 업로드하려면 --policy.path=${HF_USER}/my_policy가 찾을 수 있도록 같은 저장소 이름을 사용하세요.
lerobot-train \
--config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
--resume=true
hf upload ${HF_USER}/my_policy \
outputs/train/act_so101_test/checkpoints/last/pretrained_modelLeRobot의 학습 스크립트는 실제 로봇 정책을 평가하지 않으므로, 일부 에피소드는 학습에서 빼 두고 녹화하지 않은 시작 위치도 포함해 그 위치에서 정책을 시험하세요. 한 커뮤니티 제작자는 50개 에피소드(시작 위치 구역 다섯 곳에서 각각 10개)로 학습한 뒤, 해당 구역의 새 에피소드에서는 성공률 60%, 학습에서 제외한 구역의 에피소드에서는 10%에 그쳤습니다. 구역당 에피소드를 25개로 늘리자 같은 제작자는 각각 90%와 75%에 도달했습니다. 표본이 작고, 제작자 본인의 스크립트로 채점한 결과입니다.
팔로워에서 정책 실행
학습한 정책은 lerobot-rollout으로 배포합니다. 녹화할 때 사용한 것과 같은 로봇 id, 카메라 이름, 카메라 설정, 작업 텍스트를 사용하고, 그 뒤에 재부팅했거나 카메라를 다시 꽂았다면 포트 탐색 도구를 다시 실행하세요. --duration의 단위는 초이며, 지정하지 않으면 정책은 사용자가 멈출 때까지 실행됩니다.
lerobot-rollout \
--strategy.type=base \
--policy.path=${HF_USER}/my_policy \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--task="Grab the black cube" \
--duration=60전략은 실행 중에 일어나는 일을 정하며, 아래 표와 같습니다. 데이터셋을 녹화하는 전략에는 사용자 이름 뒤에 rollout_로 시작하는 저장소 이름이 필요합니다(예: --dataset.repo_id=${HF_USER}/rollout_so101_test). 여기에는 타임스탬프가 붙습니다. sentry 같은 녹화 전략은 --task 대신 --dataset.single_task를 받습니다. 각 전략의 옵션은 LeRobot 문서를 참고하세요.
LeRobot v0.5.x 이하에는 lerobot-rollout이 없습니다. v0.5.1 문서에 설명된 대로 lerobot-record를 사용하세요. 이 가이드의 학습 옵션은 현재 릴리스를 기준으로 합니다.
처음 실행할 때는 짧은 시간(예: 15초)으로, 작업 공간을 비우고 팔을 어떻게 멈출지 계획을 세운 채 실행합니다. 전원을 끊으면 모터가 풀리므로 무언가에 받쳐져 있지 않은 팔은 떨어질 수 있습니다. 팔이 테이블을 쪼거나 지나치게 뻗는다면 모델을 탓하기 전에 설정을 확인하세요. 같은 보정 id, 같은 위치에 같은 이름과 해상도로 설치된 카메라, 같은 조명, 그리고 데이터셋이 다루는 위치에 놓인 물체인지 확인합니다.
옆으로 스크롤하여 모든 열을 비교하세요.
| 전략 | 하는 일 |
|---|---|
| base | 녹화 없이 자율적으로 실행합니다. 빠른 테스트용입니다 |
| sentry | 계속 녹화하고 자동으로 업로드합니다 |
| highlight | 링 버퍼를 유지하다가 키를 누르면 저장합니다 |
| dagger | 사람이 개입하는 데이터 수집 |
| episodic | 에피소드 단위로 녹화하며 사이에 리셋 단계를 둡니다 |
LeKiwi로 확장하기
LeKiwi는 SO-101 팔로워 암을 싣는 바퀴 세 개짜리 이동 베이스입니다. Raspberry Pi 또는 카메라와 모터 제어 보드에 쓸 USB 포트가 충분한 다른 5 V 컴퓨터(LeKiwi 페이지에는 2개 이상이라고 되어 있습니다)가 로봇을 구동하고, 노트북에서 리더 암과 키보드로 조종합니다. 유선 버전에서는 모든 것이 노트북에서 실행되므로 Pi 단계는 건너뛸 수 있습니다. 부품 목록, 출력 파일, 베이스 조립 안내는 Hugging Face LeKiwi 페이지에 링크된 LeKiwi 프로젝트에서 제공합니다.
좌우로 스크롤하면 그림 전체를 볼 수 있습니다.
키보드로 베이스를 조종하려면 글로벌 키 백엔드가 필요하므로, X11, Windows 데스크톱, 또는 터미널에 입력 모니터링 권한을 부여한 macOS에서는 동작하지만 Wayland나 헤드리스 머신에서는 동작하지 않습니다.
- 위의 섹션들을 따라 SO-101 암 두 개를 만듭니다. 하나는 베이스에 장착하고 하나는 리더로 씁니다. 그런 다음 베이스를 조립합니다.
- Raspberry Pi OS를 설치하고 SSH를 활성화한 뒤
ssh <user>@<pi-ip>로 로그인할 수 있는지 확인합니다. Pi와 노트북 모두에 설치 섹션에 나온 대로 LeRobot을 설치한 다음 LeKiwi extra를 추가합니다. 이 extra가 서보 드라이버와 ZeroMQ를 가져옵니다.LeKiwi extra 설치 pip install 'lerobot[lekiwi]' - 명령 하나로 모든 모터를 설정합니다. 팔 모터에는 ID 6~1이, 바퀴에는 9, 8, 7이 지정되며, 바퀴 ID는 LeKiwi 문서에 나온 설치 위치와 일치해야 합니다. LeKiwi는 제어 보드를 하나만 사용합니다.
LeKiwi 모터 ID 설정 lerobot-setup-motors \ --robot.type=lekiwi \ --robot.port=/dev/ttyACM0 - Pi에서는 팔로워 암을, 노트북에서는 리더 암을 보정합니다. LeKiwi 페이지는 리더에
--teleop.type=so100_leader를 보여 주는데,examples/lekiwi/teleoperate.py가 어떤 리더 클래스를 만드는지 확인하고 같은 타입과--teleop.id로 보정합니다. 바퀴 모터는 보정이 필요 없습니다.LeKiwi 팔 보정 lerobot-calibrate \ --robot.type=lekiwi \ --robot.id=my_awesome_kiwi - Pi에서 LeRobot 환경을 활성화하고 호스트를 시작합니다.
--host.connection_time_s를 늘리지 않으면(예: 600) 30초 후에 멈추므로, 녹화처럼 더 긴 세션에는 늘려야 합니다.Pi에서 LeKiwi 호스트 시작 python -m lerobot.robots.lekiwi.lekiwi_host \ --robot.id=my_awesome_kiwi \ --host.connection_time_s=600 - 노트북에서 LeRobot 소스 저장소의
examples/lekiwi/teleoperate.py를 수정합니다.remote_ip를 Pi의 주소로, 리더 암의port와 id를 본인 값으로 설정한 뒤 실행하세요.record.py에서는HF_REPO_ID와TASK_DESCRIPTION도 설정하고,replay.py에서는remote_ip,port, 데이터셋 id, 에피소드 인덱스를 설정합니다. 학습한 정책을 실행하려면 LeKiwi 페이지는examples/lekiwi/evaluate.py를 쓰며(remote_ip,port, 모델을 설정), 이전 섹션의lerobot-rollout명령은 독립형 SO-101용으로 작성되었습니다. 속도는 R과 F로 바꾸는 세 가지 모드가 있습니다. 빠름은 0.3 m/s와 90°/s, 중간은 0.2 m/s와 60°/s, 느림은 0.1 m/s와 30°/s입니다.
옆으로 스크롤하여 모든 열을 비교하세요.
| 키 | 동작 |
|---|---|
| W | 전진 |
| A | 왼쪽으로 이동 |
| S | 후진 |
| D | 오른쪽으로 이동 |
| Z | 왼쪽으로 회전 |
| X | 오른쪽으로 회전 |
| R | 속도 높이기 |
| F | 속도 낮추기 |
문제 해결 체크리스트
많은 문제는 전원, 케이블, 포트, 또는 녹화와 실행 사이에 달라진 설정에서 비롯됩니다. 코드를 바꾸기 전에 이 표를 먼저 하나씩 확인하세요.
LeRobot 자체에 대한 질문은 Hugging Face 문서에 링크된 Discord 커뮤니티에 문의하세요. 저희 상점에서 구입한 부품에 대해서는 WhatsApp 버튼이나 문의 양식을 이용하세요.
옆으로 스크롤하여 모든 열을 비교하세요.
| 증상 | 확인할 사항 |
|---|---|
| 시리얼 포트를 찾을 수 없거나 접근이 거부됩니다 | 보드에 전원을 넣고 USB 케이블을 꽂은 상태에서 포트 탐색 도구를 다시 실행합니다. Linux에서는 해당 포트에 sudo chmod 666으로 접근을 허용합니다. 포트는 재부팅하거나 다시 꽂으면 바뀔 수 있으니 포트 탐색 도구를 다시 실행하세요. |
| ID 설정 스크립트가 모터를 찾지 못합니다 | 전원 공급 장치, USB 케이블, 3핀 케이블을 확인합니다. 설정 중인 모터 하나만 연결되어 있어야 합니다. Waveshare 보드에서는 점퍼 두 개가 모두 채널 B(USB)에 있어야 합니다. |
| 재사용한 서보가 인식되지 않거나 응답하지 않습니다 | SO-101 가이드에도 나와 있듯이 ID와 보드레이트가 새 로봇과 맞지 않을 가능성이 큽니다. 모터 설정을 서보 한 개씩 다시 실행합니다. |
| 보정이 실패하거나, 보정한 뒤 팔이 잘못 움직입니다 | 다시 보정합니다. 먼저 모든 관절을 가동 범위의 중간에 놓고 Enter를 누른 다음, 각 관절을 전체 가동 범위로 움직입니다. 모든 관절을 중간에 놓지 않았던 한 커뮤니티 제작자는 호밍 오프셋이 잘못되었습니다. 이후에는 같은 로봇 id를 사용하세요. |
| 카메라 연결이 끊기거나 인덱스가 바뀝니다 | 재부팅하거나 카메라를 다시 꽂을 때마다 카메라 탐색 도구를 다시 실행합니다. 동일한 웹캠 두 대는 Linux에서 USB 주소가 서로 바뀔 수 있으며, 한 커뮤니티 제작자는 물리 USB 포트를 기준으로 하는 udev 규칙으로 이를 해결했습니다. |
| 녹화 키가 반응하지 않습니다 | 대화형 터미널에서 명령을 시작하고 그 터미널에 포커스를 유지합니다. 화살표 키와 Esc 키뿐 아니라 문자 키 n, r, q도 동작합니다. 키보드로 로봇을 주행시킬 때만(LeKiwi처럼) X11, Windows 데스크톱 또는 macOS 권한이 필요합니다. |
| 학습이 데이터셋을 찾지 못합니다 | 날짜와 시간 접미사를 포함한 전체 데이터셋 이름을 사용합니다. |
| 녹화 주기가 30 Hz보다 크게 낮습니다 | 녹화가 출력하는 주기 줄을 읽어 보세요. 카메라 읽기가 주된 원인이라면 해상도를 낮추거나 카메라 수를 줄이고 다시 녹화하세요. 정책은 실행할 때도 같은 카메라 구성을 기대하며, 30 Hz보다 크게 낮게 녹화된 에피소드도 30 Hz로 실행된 것처럼 저장됩니다. |
| 정책이 테이블을 쪼거나 지나치게 뻗습니다 | 보정 id, 카메라 위치와 이름, 조명을 녹화 세션과 비교하고, 물체가 데이터셋에 예시가 있는 위치에서 시작하는지 확인합니다. |
| LeKiwi가 연결되지 않거나 호스트가 30초 후에 멈춥니다 | hostname -I로 Pi의 주소를 확인하고, 노트북에서 그 주소로 ping을 보내 보고 ssh <user>@<pi-ip>로 접속을 시험합니다. 필요하면 sudo raspi-config에서 SSH를 활성화하세요. --host.connection_time_s를 설정하지 않으면 호스트는 30초 후에 멈춥니다. |