훈련 — 정책 학습하기

훈련 탭은 데이터 수집으로 모은 데이터셋으로 정책(policy)을 학습시킵니다. 정책은 카메라 영상과 관절값을 보고 로봇이 다음에 할 동작을 정하는 모델이며, 학습이 끝나면 추론 탭에서 이 정책으로 로봇을 스스로 움직일 수 있습니다. 앱이 LeRobot 의 학습 명령(lerobot-train)을 대신 만들어 실행하므로 터미널 명령을 몰라도 됩니다. 학습하는 동안에는 로봇에 연결하지 않으므로 로봇은 꺼져 있어도 됩니다.

학습 목표

  • 환경 진단으로 이 PC 가 GPU 로 학습할 수 있는지 확인하고, 필요하면 GPU 버전 PyTorch 로 바꿀 수 있다.
  • ACT · SmolVLA · X-VLA · NVIDIA GROOT 네 모델의 차이를 알고 알맞은 모델을 고를 수 있다.
  • 새 학습 6단계(모델 → 데이터셋 → 옵션 → 증강 → 명령 미리보기 → 실행)를 따라 학습을 돌리고 결과 폴더를 찾을 수 있다.
  • W&B 기록과 Hugging Face Hub 업로드를 설정하고, 멈춘 학습을 학습 재개로 이어 갈 수 있다.

1. 훈련 탭 한눈에 보기

1.1. 들어가는 길

  1. [앱] 왼쪽 사이드바의 로봇 창고 에서 학습할 로봇의 카드를 누릅니다. 사이드바 최근 로봇 에서 골라도 됩니다.
  2. [앱] 위쪽 탭 줄에서 훈련 을 누릅니다.

훈련 탭은 SO-101 · SO-102 · Lekiwi 세 기종 모두에 있습니다. 로봇 카드에서 들어가므로 로봇 설정에서 로봇을 먼저 저장해 두어야 합니다. 어느 로봇으로 들어왔는지는 세 군데에 쓰입니다. 결과 폴더 이름에 그 로봇의 이름(robot id)이 들어가고, 데이터셋 목록이 기종이 다른 데이터셋에 경고를 붙이며, 학습 재개 목록에는 그 로봇의 학습만 나옵니다.

훈련 탭 안에는 하위 탭이 세 개 있습니다.

하위 탭하는 일
환경 진단이 PC 가 학습할 수 있는지 11개 항목을 검사하고, GPU 버전 PyTorch 로 바꾸는 버튼을 보여 줍니다 (2절)
새 학습모델 · 데이터셋 · 옵션을 골라 학습을 시작합니다 (3~5절)
학습 재개멈추거나 끝난 학습을 마지막 체크포인트부터 이어서 더 학습합니다 (8절)

A-Go(LeKiwi) 데이터셋도 같은 방법으로 학습합니다

로봇 쪽 준비부터 데이터 수집 · 추론까지 이어지는 흐름은 데이터 · 학습 · 추론에 따로 정리했습니다.

1.2. 처음 열면 — 설치 카드

훈련에 필요한 라이브러리는 앱을 처음 설치할 때 함께 깔리지 않습니다. 그래서 훈련 탭을 처음 열면 탭 화면 대신 설치 카드가 뜹니다. 설치하기 를 누르면 로봇 제어 · 데이터 · 학습 패키지 세 개를 한 번에 설치합니다 (합계 내려받기 약 371MB, 약 3분). 칼리브레이션 같은 다른 탭에서 이미 설치한 패키지는 빼고 남은 것만 설치합니다. 설치할 때 관리자(시스템) 비밀번호를 한 번 묻습니다.

훈련 탭을 처음 열 때 뜨는 설치 카드 — 로봇 제어 패키지 · 데이터 패키지 · 학습 패키지 세 줄과 설치하기 버튼

훈련 탭의 설치 카드입니다. 설치가 끝나면 훈련 준비 중입니다 창이 잠깐 뜬 뒤 이 자리에 훈련 탭이 열립니다.

설치 카드의 문구와 설치에 실패했을 때의 대처는 기능 패키지 설치에서 자세히 설명합니다.

1.3. 준비물

준비물설명
데이터셋이 PC 에 있는 LeRobot 데이터셋. 데이터 수집으로 만들었거나, 데이터셋 창고에서 Hub 데이터셋을 내려받은 것
NVIDIA GPU (권장)드라이버 570 이상. GPU 가 없어도 학습은 되지만 CPU 로 돌아 매우 느립니다
디스크 여유 공간20GB 이상 권장 (환경 진단은 20GB 미만이면 주의 로 표시). GPU 버전 PyTorch 는 내려받기 약 4.0GB · 설치 후 약 5.9GB 입니다
인터넷라이브러리 설치, GPU 버전 PyTorch 설치, SmolVLA · X-VLA · NVIDIA GROOT 사전학습 모델 받기, Hub 업로드, W&B 기록에 필요합니다. LeKiwi 를 AP 모드로 붙인 노트북은 인터넷이 없으니, 이런 작업은 공유기에 붙인 뒤 하세요
Hugging Face 토큰 (선택)학습 결과를 Hub 에 올릴 때만 필요합니다. 설정 › 일반 › API 키 의 HuggingFace Access Token 에 저장합니다

Windows 판(0.1.7)은 조금 다릅니다

이 문서는 Ubuntu 판 0.2.0 기준입니다. Windows 판도 훈련 탭의 흐름은 같지만 일부 화면과 명령 미리보기가 다를 수 있습니다. 확인된 차이는 두 가지입니다. Windows 설치 프로그램은 NVIDIA GPU 와 570 이상의 드라이버를 찾으면 처음부터 GPU 버전 PyTorch 를 설치합니다. 또 앱이 사용자 폴더(%LOCALAPPDATA%\Programs\PhysicalLabs)에 설치되므로 라이브러리를 설치할 때 관리자 비밀번호를 묻지 않습니다.


2. 환경 진단 — 이 PC 로 학습할 수 있을까?

2.1. 화면 읽기

훈련 탭을 처음 열면 환경 진단 이 자동으로 검사를 시작합니다. 카드마다 오른쪽 위의 표시가 검사 중… 에서 결과로 바뀝니다. 무언가를 설치하거나 드라이버를 바꾼 뒤에는 오른쪽 위 다시 검사 를 누릅니다.

검사가 끝난 환경 진단 화면 — 시스템 정보 카드 4개와 설치 가능한 의존성 카드 7개, 오른쪽 위 다시 검사 버튼

GPU 버전 PyTorch 가 이미 깔린 PC 의 환경 진단입니다. 그림의 PyTorch 판은 앱이 설치하는 것과 다르며, 앱으로 GPU 버전을 설치하면 PyTorch 카드에 PyTorch 2.11.0+cu128 / CUDA build 12.8 이 보입니다. 앱을 막 설치한 PC 는 PyTorch 가 CPU 버전이라 카드 위에 GPU 안내 배너가 뜹니다 (2.2절).

카드 오른쪽 위의 표시는 다섯 가지입니다.

표시뜻
정상문제없습니다
주의학습은 되지만 확인이 필요합니다 (예: GPU 를 못 쓰는 PyTorch, 디스크 20GB 미만)
없음설치되어 있지 않습니다. 의존성 카드는 눌러서 설치할 수 있습니다
오류설치는 됐지만 불러오지 못했습니다
알수없음확인하지 못했습니다

카드별로 볼 것은 다음과 같습니다.

카드무엇을 보나볼 것
운영체제 · CPU / RAMPC 정보참고용
GPUNVIDIA GPU 이름 · VRAM · 드라이버 버전GPU 가 없으면 NVIDIA GPU 미감지(CPU 전용)
디스크 여유남은 공간20GB 미만이면 주의
Python앱이 쓰는 파이썬참고용
PyTorch설치된 PyTorch 와 CUDA 빌드앱을 막 설치한 PC 는 PyTorch 2.11.0+cpu / CUDA build 없음
CUDA 지원PyTorch 가 GPU 를 쓸 수 있는지CUDA 사용 가능 / 장치: … 여야 GPU 로 학습합니다. CPU 버전이면 CUDA 미지원 빌드 (CPU 전용으로 훈련 가능하나 느림)
lerobot[training]학습을 실행하는 라이브러리(accelerate)없음 이면 눌러서 학습 패키지를 설치합니다
Flash Attention선택 라이브러리flash-attn 미설치 (없어도 훈련 가능) — 그대로 두어도 됩니다
Wandb학습 기록 라이브러리없음 이면 눌러서 학습 패키지를 설치합니다
영상 디코더학습 데이터의 영상을 읽는 부품없음 이면 꼭 눌러서 설치합니다 (2.3절)

맨 아래 사용자 보강 입력(GPU 모델명 · VRAM · 원하는 CUDA 버전 · 가상환경 종류)은 검사 결과가 미리 채워지는 참고용 칸입니다. 값을 바꿔도 학습 설정에는 반영되지 않습니다.

2.2. [앱] GPU 버전 PyTorch 로 바꾸기

앱을 처음 설치하면 PyTorch 가 CPU 버전으로 들어갑니다. NVIDIA GPU 가 있어도 이 상태로는 GPU 를 쓰지 못해 학습이 매우 느립니다. 환경 진단이 NVIDIA GPU 와 570 이상의 드라이버를 확인하면 카드 위에 NVIDIA GPU(<GPU 이름>)가 인식되었습니다. 지금은 CPU 버전 PyTorch 라 학습이 느립니다. … 배너와 GPU 버전 PyTorch 설치 버튼이 뜹니다.

  1. [앱] 배너 오른쪽의 GPU 버전 PyTorch 설치 를 누릅니다.
  2. [앱] GPU 버전 PyTorch 설치 창에서 감지된 GPU 이름과 용량(내려받기 약 4.0GB · 설치 후 약 5.9GB)을 확인하고 GPU 버전 설치하기 를 누릅니다.
  3. [앱] 관리자 비밀번호를 묻는 창이 뜨면 이 PC 의 비밀번호를 입력합니다. 설치는 약 15분 걸립니다 (인터넷 속도에 따라 다릅니다). 진행 상황은 ▸ 설치 로그 보기 로 볼 수 있습니다.
  4. [앱] GPU 버전 PyTorch 설치가 완료되었습니다. 앱을 다시 시작하면 적용됩니다. 가 나오면 지금 다시 시작 을 누릅니다.
  5. [앱] 앱이 다시 켜지면 로봇 카드 → 훈련 → 환경 진단 에서 CUDA 지원 카드가 정상(CUDA 사용 가능 / 장치: <GPU 이름>)인지 확인합니다.

GPU 버전 PyTorch 설치 창 — PyTorch GPU 빌드(CUDA 12.8), 내려받기 약 4.0GB · 설치 후 약 5.9GB, 예상 시간 약 15분, GPU 버전 설치하기 버튼

GPU 버전 PyTorch 설치 창입니다. torch · torchvision · torchcodec 을 GPU 빌드로 바꿉니다.

설치가 끝날 때까지 앱을 켜 두세요

설치 창은 닫아도 설치가 계속되지만, 앱을 끄면 설치가 중간에 멈춰 일부만 설치된 채 남을 수 있습니다. 또 앱은 켤 때 로그인을 확인하므로 지금 다시 시작 은 인터넷이 연결된 상태에서 누르세요.

배너 문구에 따라 할 일이 다릅니다.

배너뜻 · 할 일
NVIDIA GPU(…)가 인식되었습니다. 지금은 CPU 버전 PyTorch 라 학습이 느립니다. …위 순서대로 GPU 버전을 설치합니다
NVIDIA GPU(…)가 인식되었지만 드라이버(…)가 오래되어 GPU 버전 PyTorch(CUDA 12.8)를 쓸 수 없습니다. …NVIDIA 드라이버를 570 이상으로 올린 뒤 다시 검사 를 누릅니다
… 이 환경에서는 GPU 버전 PyTorch 를 자동으로 설치할 수 없습니다 (Linux x86_64 · Python 3.12 필요).지원하는 환경(64비트 PC 의 Ubuntu 24.04)이 아닙니다
NVIDIA GPU 가 인식되지 않아 CPU 로 학습합니다 — 학습이 매우 느릴 수 있습니다.NVIDIA GPU 가 없거나 드라이버가 설치되지 않았습니다
GPU 버전 PyTorch 가 설치되어 있지만 GPU 를 쓸 수 없습니다. …NVIDIA 드라이버가 제대로 설치됐는지 확인합니다
GPU 버전 PyTorch 가 설치되었습니다. 앱을 다시 시작하면 GPU 로 학습합니다.배너 오른쪽의 지금 다시 시작 을 누릅니다
배너 없음GPU 버전이 이미 동작하고 있습니다

드라이버 버전은 터미널에서 확인할 수 있습니다. 출력 위쪽의 Driver Version: 이 570 이상이어야 합니다.

Ubuntu
nvidia-smi

드라이버가 오래됐다면 Ubuntu 의 소프트웨어 & 업데이트 › 추가 드라이버 탭에서 570 이상의 NVIDIA 드라이버를 골라 적용하고 PC 를 다시 시작합니다.

앱이 확인하는 것은 드라이버 버전입니다

앱이 설치하는 GPU 버전 PyTorch 에는 CUDA 12.8 런타임이 함께 들어 있습니다. GPU 버전 PyTorch 설치 버튼이 뜨는 조건은 NVIDIA GPU · 드라이버 570 이상 · 64비트 Ubuntu(파이썬 3.12) 입니다.

2.3. 다른 카드가 없음 일 때

설치가 끝나면 다시 검사 로 카드가 정상 이 됐는지 확인합니다.


3. 새 학습 ① 모델 고르기

3.1. 네 가지 모델

새 학습 탭의 첫 화면 모델 선택 에는 카드가 네 개 있습니다. 화면 안내 그대로 처음이라면 ACT 를 권장합니다.

새 학습 › 모델 선택 화면 — ACT · SmolVLA · X-VLA · NVIDIA GROOT 카드 네 개가 2×2 로 놓여 있음

새 학습 탭의 첫 화면입니다. 카드마다 모델 설명과 권장 GPU · 사전학습 모델이 적혀 있습니다.

카드카드에 적힌 설명이런 때처음 고를 때 추가 설치
🤖 ACTTransformer 정책 — 처음 시도용 · ~80M 파라미터 · 단일 GPU · 8GB VRAM~처음 학습할 때. 가볍고 GPU 한 장으로 충분합니다없음 — 바로 다음 단계로
🧠 SmolVLA비전-언어-액션 모델 (0.5B) · 사전학습 필수 (lerobot/smolvla_base) · A100 권장사전학습 모델을 내 데이터로 다듬고, 영어 지시문을 함께 쓰고 싶을 때num2words · transformers 등
🔭 X-VLA비전-언어-액션 모델 (0.9B) · 사전학습 필수 (lerobot/xvla-base) · bfloat16 권장SmolVLA 보다 큰 VLA 모델을 다듬을 때transformers
🌌 NVIDIA GROOT3B Diffusion 모델 · 사전학습 필수 · 멀티 GPU 강력 권장GPU 메모리가 넉넉한 고급 사용자transformers · peft · timm 등, (선택) GPU 버전 PyTorch

SmolVLA · X-VLA · NVIDIA GROOT 는 VLA(비전-언어-액션) 계열로, 카메라 영상 · 관절값과 함께 문장(지시문)도 입력으로 받습니다. 많은 데이터로 미리 학습된 사전학습 모델에서 출발해 내 데이터로 다듬는 방식(파인튜닝)이라, 사전학습 모델을 Hub 에서 받아 올 인터넷이 필요합니다. 데이터 수집 때 적은 태스크 설명(영어 문장)을 함께 배우므로, 추론할 때도 같은 뜻의 지시문을 넣습니다.

처음에는 ACT 로 시작하세요

ACT 는 추가 설치가 없고 GPU 한 장으로 학습할 수 있습니다. ACT 로 데이터 수집 → 학습 → 추론을 한 바퀴 돌려 본 뒤 VLA 모델을 시도하는 것이 좋습니다.

3.2. [앱] 추가 라이브러리 확인 · 설치 (SmolVLA · X-VLA · NVIDIA GROOT)

SmolVLA · X-VLA · NVIDIA GROOT 카드를 누르면 앱이 그 모델에 필요한 라이브러리가 있는지 먼저 확인합니다. 빠진 것이 있으면 SmolVLA 학습 의존성 설치 같은 창이 뜨고, 같은 창에서 확인과 설치를 차례로 진행합니다. 모두 있으면 창 없이 바로 데이터셋 선택으로 넘어갑니다.

  1. [앱] 확인 단계에서 누락된 필수 패키지: 목록과 다음 패키지를 이 앱의 파이썬 환경에 설치합니다. 설치하시겠습니까? 를 보고 예 를 누릅니다. Ubuntu 앱은 설치 위치가 관리자 소유라 [예] 를 누르면 시스템 비밀번호 창이 뜹니다 라는 안내가 함께 보입니다.
  2. [앱] 비밀번호 창에 이 PC 의 비밀번호를 입력합니다.
  3. [앱] 같은 창이 설치 단계로 바뀌고, 단계 1/1: lerobot[smolvla]==0.6.0 설치 (num2words · accelerate · transformers) 같은 진행 줄과 검은 설치 로그가 나옵니다.
  4. [앱] 모든 SmolVLA 의존성 설치가 완료되었습니다. 가 나오면 뒤의 화면은 이미 데이터셋 선택 으로 넘어가 있습니다. 닫기 로 창을 닫습니다.

아니오 를 누르거나 창을 닫으면 모델 선택 화면에 그대로 머뭅니다. 설치가 실패하면 로그에 [실패] 단계 1/1 가 종료 코드 N 로 실패했습니다. 와 원인 안내가 나옵니다. 인터넷을 확인한 뒤 카드를 다시 누르면 처음부터 다시 시도합니다.

NVIDIA GROOT 의 확인 단계에는 현재 torch: … 와 체크박스 PyTorch 를 GPU 버전(2.11.0+cu128)으로 교체 허용 — 약 4GB, 끝나면 앱 재시작 이 더 있습니다. 2.2절에서 이미 GPU 버전으로 바꿨다면 체크박스 옆에 (이미 정합) 이 보이므로 신경 쓰지 않아도 됩니다. NVIDIA GPU PC 인데 아직 CPU 버전이면 체크하고 예 를 누릅니다. 끝나면 앱 다시 시작 창에서 지금 다시 시작 을 누릅니다. 창 아래의 .agent/GROOT_INSTALL.md 안내는 개발용 문서를 가리키는데, 설치된 앱에는 이 파일이 들어 있지 않습니다.

관리자 비밀번호로 시작한 설치는 바로 멈추지 않을 수 있습니다

설치 중 중단 을 누르거나 창을 닫아도 진행 중인 설치가 곧바로 끝나지 않을 수 있고, 중간에 끊기면 일부만 설치된 채 남을 수 있습니다. 한 번 시작했으면 끝날 때까지 기다리세요.


4. 새 학습 ② 데이터셋 · 옵션 · 증강

4.1. [앱] 데이터셋 선택

데이터셋 선택 화면의 💾 로컬 데이터셋 에는 이 PC 의 ~/.cache/huggingface/lerobot/<사용자명>/<이름>/ 에 있는 데이터셋이 최근에 바뀐 것부터 나옵니다. 카드에는 이름(예: HueyWoo/pick_and_place), N 에피소드 · N 프레임 · 30fps, 로봇 타입이 적혀 있습니다. 학습할 카드를 누르고 다음 → 을 누릅니다.

데이터셋 선택 화면 — 로컬 데이터셋 카드 목록에서 하나를 고른 상태, 오른쪽 아래 다음 버튼

이 PC 에 받아 둔 데이터셋만 카드로 나옵니다. 카드에는 에피소드 · 프레임 수, FPS, 로봇 종류가 보입니다.

데이터셋의 로봇 타입과 관절 수는 기종마다 다릅니다.

로봇이 앱으로 수집한 데이터셋의 로봇 타입관절 수
SO-101so_follower (아래 정보 상자 참고)6
SO-102so102_follower7
Lekiwilekiwi_client9 (팔 6 + 바퀴 3)

기종이 다른 데이터셋으로 학습하면 학습 자체는 끝나지만, 관절 구성이 달라 지금 로봇으로 추론을 시작할 수 없습니다. 몇 시간 학습한 뒤에야 알게 되는 실수라서, 앱은 기종이 다른 데이터셋 카드에 붉은 ⚠ <로봇 타입> — 지금 로봇과 다름 을 붙입니다. 그래도 다음 → 을 누르면 로봇 기종 불일치 창이 한 번 더 묻습니다 (기본값 No). 경고가 보이면 다른 데이터셋을 고르세요.

SO-101 데이터셋에 ‘지금 로봇과 다름’ 이 보일 때

이 앱으로 SO-101 에서 수집한 데이터셋은 로봇 타입이 so_follower 로 기록되는데, 훈련 탭은 SO-101 을 so101_follower 와 비교합니다. 그래서 SO-101 로봇에서는 내 SO-101 데이터셋 카드에도 붉은 ⚠ so_follower — 지금 로봇과 다름 이 붙고 로봇 기종 불일치 창이 뜹니다. 로봇 타입이 so_follower 이고 SO-101 로 모은 데이터셋이 맞다면 Yes 를 눌러 계속하세요. 관절 구성이 같아 학습과 추론에 문제가 없습니다. lekiwi_client · so102_follower 처럼 정말 다른 기종이면 No 를 누릅니다.

4.2. [앱] 학습 옵션

학습 옵션 화면은 위쪽 공통 옵션 과 아래쪽 모델별 옵션 으로 나뉩니다. 제목 옆 배지(ACT, SMOLVLA …)가 고른 모델입니다. 처음에는 기본값 그대로 다음 → 을 눌러도 됩니다.

학습 옵션 화면 — 공통 옵션(작업 이름 · 출력 폴더 · step 수 · 배치 크기 · 저장 주기 등)과 모델별 옵션

ACT 를 고른 예. 작업 이름과 출력 폴더는 로봇 · 정책 · 데이터셋 이름으로 미리 채워집니다.

칸기본값설명
작업 이름:<정책>_<로봇 이름>_<데이터셋 이름> (예: act_a-ba_pick_and_place)학습 기록에 붙는 이름입니다
출력 폴더:~/.PhysicalLabs/outputs/train/<로봇 이름>/<정책>/<데이터셋 이름>결과가 저장되는 곳입니다 (7.1절)
학습 step 수:50,000학습을 몇 번 갱신할지 정합니다 (1,000~2,000,000). 한 step 에 배치 크기만큼의 프레임을 봅니다
배치 크기:ACT 8 · SmolVLA 8 · X-VLA 4 · NVIDIA GROOT 4한 번에 보는 프레임 수입니다. GPU 메모리가 모자라면 줄입니다
저장 주기 (step):20,000체크포인트(중간 저장본)를 남기는 간격입니다. 중단 · 재개의 기준이 됩니다
로그 주기 (step):200학습 기록(loss · lr)을 실행 출력과 그래프에 남기는 간격입니다
DataLoader 워커 수:4데이터를 읽는 작업자 수입니다
시드:1000같은 값이면 같은 순서로 학습합니다
GPU 수 (GROOT 전용):1NVIDIA GROOT 일 때만 바꿀 수 있습니다. 2 이상이면 GPU 여러 장으로 학습합니다
wandb 로깅 사용꺼짐켜면 wandb project: 칸(기본 lerobot)이 보입니다 (6절)
HuggingFace Hub 에 업로드 (학습 종료 후)꺼짐켜면 policy.repo_id: 칸이 보입니다 (7.2절)

배치 크기 기본값은 GPU 메모리와 관계없이 모델마다 정해진 값입니다. Hub 업로드를 켜고 policy.repo_id: 를 비운 채 다음 → 을 누르면 HuggingFace Hub 업로드를 사용하려면 policy.repo_id 를 입력하세요. 가 뜹니다.

모델별 옵션 은 고른 모델의 칸만 보입니다. 잘 모르겠으면 기본값을 그대로 둡니다.

모델주요 칸 (기본값)
ACTchunk_size 100 · n_action_steps 100 · vision_backbone resnet18 · VAE 목적함수 사용 (켬)
SmolVLA사전학습 경로 lerobot/smolvla_base · chunk_size 50 · n_action_steps 50 · 비전 인코더 동결 (켬) · Action Expert 만 학습 (켬) · 옵티마이저 학습률 0.0001
X-VLA사전학습 경로 lerobot/xvla-base (목록에 lerobot/xvla-libero · lerobot/xvla-folding · lerobot/xvla-agibot-world) · dtype (bfloat16 권장) · action_mode · 최대 액션 차원 32
NVIDIA GROOT백본 경로 nvidia/GR00T-N1.7-3B · LoRA rank 16 · bfloat16 사용 (켬) · diffusion model 학습 (끔) · 메모리 fragmentation 회피 (끔)

NVIDIA GROOT 는 GPU 메모리에 따라 화면의 안내 VRAM 가이드: 12GB → lora_rank=16 + DiT 동결 / 24GB+ → lora_rank=0 + DiT 학습 을 따릅니다. 기본값은 12GB GPU 에 맞춘 설정입니다.

4.3. [앱] 데이터 증강 (선택)

데이터 증강 은 같은 영상의 밝기 · 대비 · 색 · 선명도를 조금씩 바꾸거나 살짝 돌려 가며 학습하는 기능입니다. 화면 설명처럼 조명 변화나 카메라 흔들림이 있는 실제 환경에서 모델이 더 잘 버티게 해 줍니다. 기본은 꺼져 있고, 데이터 증강 사용 (—dataset.image_transforms.enable) 을 체크하면 켜집니다.

데이터 증강 화면 — 데이터 증강 사용 체크(기본 꺼짐), 프레임당 적용 개수, 밝기 · 대비 · 채도 · 색상 · 선명도 · 기하 변환 칸

증강은 기본으로 꺼져 있습니다. 켜면 아래 여섯 가지 변환의 비율 · 범위를 정할 수 있습니다.

칸기본값
프레임당 적용 개수 (max_num_transforms):3 (1~6)
적용 순서 무작위 (random_order)꺼짐
Transform 6종밝기 0.8~1.2 · 대비 0.8~1.2 · 채도 0.5~1.5 · 색상 -0.05~0.05 · 선명도 0.5~1.5 · 기하(affine) ±5° 회전과 약간의 이동

처음에는 끈 채로 학습해 보고, 조명이 자주 바뀌는 곳에서 쓸 정책이면 켜 보세요. 설정을 마치면 다음 → 을 누릅니다.


5. 새 학습 ③ 명령 미리보기와 실행

5.1. [앱] 명령 미리보기

명령 미리보기 화면은 지금까지 고른 내용으로 만든 학습 명령을 보여 줍니다. 위에 출력 폴더: …, 가운데 합성된 명령 과 📋 복사, 아래 ▶ 시작 이 있습니다. SO-101 로봇 a-ba 에서 HueyWoo/pick_and_place 를 ACT 기본값으로 학습하면 이런 명령이 됩니다.

명령 미리보기 화면 — 출력 폴더와 합성된 lerobot-train 명령, 복사 버튼

앱이 실행할 학습 명령을 그대로 보여 줍니다. 그림의 홈 경로 /home/user 는 촬영용 값입니다.

lerobot-train \
  --dataset.repo_id=HueyWoo/pick_and_place \
  --dataset.root=/home/<사용자>/.cache/huggingface/lerobot/HueyWoo/pick_and_place \
  --policy.type=act \
  --policy.device=cuda \
  --policy.push_to_hub=false \
  --output_dir=/home/<사용자>/.PhysicalLabs/outputs/train/a-ba/act/pick_and_place \
  --job_name=act_a-ba_pick_and_place \
  --steps=50000 \
  --batch_size=8 \
  --save_freq=20000 \
  --log_freq=200 \
  --num_workers=4 \
  --seed=1000 \
  --wandb.enable=false \
  --policy.chunk_size=100 \
  --policy.n_action_steps=100 \
  --policy.vision_backbone=resnet18 \
  --policy.use_vae=true

--policy.device=cuda 는 늘 붙습니다. GPU 를 쓸 수 없는 PC 에서는 LeRobot 이 실행 출력에 Device 'cuda' is not available. Switching to 'cpu'. 를 남기고 CPU 로 학습합니다.

학습은 앱에서 ▶ 시작으로 돌리세요

화면 안내처럼 명령을 복사해 터미널에서 직접 실행할 수도 있지만, 앱은 Hugging Face 토큰과 영상 디코더 경로를 함께 넣어 실행합니다. 터미널에서는 이것들이 빠지고, 맨 앞의 lerobot-train 도 /opt/physical-labs/venv/bin/lerobot-train 처럼 앱 가상환경의 경로로 바꿔 써야 합니다.

5.2. 사전학습 모델의 카메라 이름 자동 맞춤 (SmolVLA · X-VLA)

사전학습 모델은 카메라를 일반 이름으로 배웠습니다. lerobot/smolvla_base 는 camera1 · camera2 · camera3, lerobot/xvla-* 는 image · image2 · image3 입니다. 내 데이터셋은 front · wrist 같은 실제 이름이라 그대로 넣으면 LeRobot 이 ValueError: Feature mismatch … 를 내고 시작하자마자 멈춥니다.

그래서 앱은 SmolVLA · X-VLA 를 사전학습 경로와 함께 학습할 때 카메라 이름을 짝지어 주는 설정(--rename_map)을 명령에 자동으로 넣습니다. 미리보기에는 이런 줄이 보입니다.

카메라 이름 맞춤: front → camera1 · wrist → camera2 — 사전학습 모델의 카메라 이름에 맞춥니다. 추론할 때도 같은 매핑이 자동으로 적용됩니다.

SO-101 카메라는 역할이 드러나는 이름으로

SO-101 은 로봇 설정에서 카메라 이름을 직접 짓습니다. front · wrist 처럼 역할이 드러나는 이름을 쓰면 자리가 알맞게 정해집니다. 추론할 때도 학습한 데이터셋과 같은 카메라 이름이어야 하므로, 한 번 정한 이름은 바꾸지 마세요.

5.3. [앱] 같은 폴더가 이미 있을 때 — 훈련 폴더 충돌

▶ 시작 을 눌렀을 때 출력 폴더가 이미 있으면 훈련 폴더 충돌 창이 뜹니다. 같은 로봇 · 모델 · 데이터셋으로 두 번째 학습을 시작할 때 흔히 봅니다.

버튼하는 일
삭제하고 다시 학습기존 폴더를 체크포인트까지 모두 지우고 처음부터 학습합니다
이어서 학습 (기본)학습 재개 탭으로 넘어갑니다. 거기서 이어 갈 학습 카드를 다시 고릅니다 (8절)
새 폴더로 저장폴더 이름 뒤에 _2, _3 … 을 붙여 새로 학습합니다. 기존 결과는 그대로 남습니다
취소아무것도 하지 않고 미리보기로 돌아갑니다

‘삭제하고 다시 학습’ 은 다시 묻지 않고 바로 지웁니다

이전 학습의 체크포인트가 모두 사라지고 되돌릴 수 없습니다. 확실하지 않으면 새 폴더로 저장 을 고르세요.

5.4. [앱] 학습 실행 화면

▶ 시작 을 누르면 실행 화면으로 바뀝니다.

위치보이는 것
위진행 막대 — 시작 중... → 12,345 / 50,000 step (24%) → 끝나면 완료, 실패하면 오류 (rc=N). 그 아래 경과: · 남은 시간:
가운데실행 출력 — LeRobot 이 내는 글 그대로입니다. 오류가 나면 여기 마지막 줄에 이유가 있습니다
아래Loss · Learning Rate 그래프 — Loss 가 차츰 내려가면 잘 학습되고 있는 것입니다

5.5. 학습 중에 다른 일을 하거나 앱을 끌 때


6. W&B 로 학습 기록 보기 (선택)

W&B(Weights & Biases)는 학습 그래프를 웹에서 보고 여러 학습을 비교하는 서비스입니다. 앱의 Loss 그래프만으로 충분하면 쓰지 않아도 됩니다.

설정의 Wandb API Key 는 학습에 전달되지 않습니다

설정 › 일반 › API 키 의 Wandb API Key 에 키를 저장해도 학습은 그 키를 받지 못합니다. W&B 를 쓰려면 아래 1단계의 wandb login 을 이 PC 에서 한 번 해 두어야 합니다. 로그인하지 않은 채 wandb 로깅 사용 을 켜면 학습이 W&B 단계에서 실패할 수 있습니다.

  1. [PC] 학습 패키지가 설치된 뒤 터미널에서 W&B 에 로그인합니다. sudo 는 붙이지 않습니다 — 로그인 정보는 내 홈 폴더에 저장됩니다.

    Ubuntu
    /opt/physical-labs/venv/bin/wandb login

    API 키를 물으면 W&B 사이트의 API 키 페이지에서 복사한 키를 붙여 넣고 Enter 를 누릅니다. 입력한 키는 화면에 보이지 않습니다. 계정을 고르는 물음까지 포함한 순서는 설정 3.5절에 있습니다.

  2. [앱] 학습 옵션 에서 wandb 로깅 사용 을 켜고, wandb project: 에 W&B 프로젝트 이름을 적습니다 (기본 lerobot).

  3. [앱] 학습을 시작하면 W&B 의 그 프로젝트에 기록이 쌓이고, 결과 폴더에 wandb/ 폴더가 생깁니다.

Windows 판

명령 프롬프트에서 "%LOCALAPPDATA%\Programs\PhysicalLabs\venv\Scripts\wandb.exe" login 을 실행합니다.


7. 학습 결과 — 어디에 저장되고 어떻게 쓰나

7.1. 결과 폴더

학습 결과는 출력 폴더에 쌓입니다. <로봇 이름> 은 로봇 설정의 robot id 입니다.

~/.PhysicalLabs/outputs/train/<로봇 이름>/<정책>/<데이터셋 이름>/
├── checkpoints/
│   ├── 020000/                ← 저장 주기마다 (6자리 step 번호)
│   │   ├── pretrained_model/  ← 추론에 쓰는 모델 (config.json · model.safetensors …)
│   │   └── training_state/    ← 학습 재개에 쓰는 상태
│   ├── 040000/
│   ├── 050000/                ← 마지막 step 에도 저장
│   └── last → 050000          ← 가장 최근 체크포인트
├── command.txt                ← 실행한 명령 (학습 재개 때 재개 명령으로 바뀜)
└── wandb/                     ← W&B 를 켰을 때

체크포인트는 저장 주기(기본 20,000 step)마다, 그리고 학습이 끝나는 마지막 step 에 남습니다. 추론 탭은 이 폴더를 스스로 찾아 💾 로컬 모델 목록에 a-ba/act/pick_and_place — 050000 step · 최신 처럼 보여 줍니다. 중간에 멈춘 학습도 남은 체크포인트로 추론해 볼 수 있습니다.

체크포인트는 디스크를 차지합니다

학습을 여러 번 하면 결과 폴더가 빠르게 커집니다. 필요 없는 학습은 학습 재개 의 학습 삭제(8.3절)나 추론 탭의 모델 삭제 로 지웁니다.

7.2. Hugging Face Hub 에 올리기

학습한 모델을 Hub 에 올리면 다른 PC 의 추론 탭에서도 받아 쓸 수 있고, 다른 사람과 나눌 수 있습니다.

  1. [앱] 설정 › 일반 › API 키 › HuggingFace Access Token 에 쓰기(write) 권한이 있는 토큰을 저장해 둡니다. 앱은 학습을 실행할 때 이 토큰을 자동으로 넣어 줍니다.
  2. [앱] 학습 옵션 에서 HuggingFace Hub 에 업로드 (학습 종료 후) 를 켜고, policy.repo_id: 에 올릴 저장소 이름을 적습니다. 예: HueyWoo/act_a-ba_pick_and_place (앞부분은 토큰의 계정 이름입니다)
  3. [앱] 학습이 마지막 step 까지 끝나면 LeRobot 이 모델을 그 저장소에 올립니다.

올린 모델은 누구나 볼 수 있습니다

모델 저장소는 기본으로 공개(public) 로 만들어집니다. 남에게 보이면 안 되는 모델이면 업로드를 켜지 말거나, 올린 뒤 Hugging Face 사이트의 저장소 설정에서 비공개로 바꾸세요. 이 학습을 학습 재개 로 이어 가면 재개한 학습이 끝날 때도 같은 저장소로 다시 올라갑니다.

학습을 다른 PC(GPU PC)에서 한다면

데이터를 모은 PC 의 데이터셋 창고에서 데이터셋을 Hub 에 올리고, 학습 PC 의 데이터셋 창고에서 내려받아 학습합니다. 학습할 때 Hub 업로드를 켜 두면 로봇 PC 의 추론 탭 ☁ HuggingFace Hub 목록에서 모델을 고를 수 있습니다. 두 PC 는 같은 Hugging Face 계정의 토큰을 씁니다. 학습 PC 에서도 훈련 탭은 로봇 카드에서 열리므로 같은 기종의 로봇을 저장해 두어야 합니다. 로봇을 저장할 때는 팔의 USB 가 그 PC 에 꽂혀 있어야 하므로(SO-101 · SO-102 는 두 팔, Lekiwi 는 리더암), 처음 한 번은 팔을 학습 PC 에 연결해 저장합니다.


8. 학습 재개 — 멈춘 학습 이어 가기

8.1. [앱] 이어 갈 학습 고르기

학습 재개 탭은 지금 로봇의 학습 폴더(~/.PhysicalLabs/outputs/train/<로봇 이름>/)를 찾아 카드로 보여 줍니다. 카드에는 결과 폴더 이름(예: pick_and_place)과 3시간 전 같은 시간, 정책: act · 데이터: HueyWoo/pick_and_place, 20,000 / 50,000 step(마지막 체크포인트 / 목표)이 적혀 있습니다.

학습 재개 목록 — 학습 카드 세 개(결과 폴더 이름 · 정책 · 데이터 · step · 시간)와 오른쪽 위 다시 검색 · outputs/train 폴더 열기 · 학습 삭제 버튼

학습 재개 목록입니다. 카드마다 결과 폴더 이름, 정책 · 데이터셋, 마지막 체크포인트 / 목표 step 이 보입니다. 가운데 카드의 이름은 가렸습니다.

이어 갈 카드를 누르면 설정 화면으로 넘어갑니다.

8.2. [앱] 학습 재개 설정

학습 재개 설정 화면 위에는 이전 학습 설정은 이어 갑니다. 데이터셋 / 정책 / optimizer 옵션은 수정 불가합니다. 가 보입니다. 아래에 설정 파일 · 이전 정책 · 이전 데이터셋 · 현재 step / 목표 step 이 읽기 전용으로 나오고, 바꿀 수 있는 칸은 둘입니다.

학습 재개 설정 화면 — 설정 파일 · 이전 정책 · 이전 데이터셋 · 현재/목표 step, 새 목표 step(누적) 칸과 재개 시작 버튼

32,000 / 70,000 step 에서 멈춘 학습을 80,000 step 까지 이어 가는 예. 새 목표 step 은 누적 값입니다.

칸기본값설명
새 목표 step (누적)이전 목표 + 10,000처음부터 센 전체 step 수입니다. 이전 목표보다 커야 합니다
save_freq 변경 (선택)기본값 유지저장 주기를 바꾸고 싶을 때만 적습니다

“누적” 은 더할 step 이 아니라 도달할 step 이라는 뜻입니다. 학습은 마지막 체크포인트부터 이어집니다.

이전 학습새 목표 step (누적)결과
목표 50,000 · 끝까지 마침60,00050,000 부터 10,000 step 더 학습합니다
목표 50,000 · 30,000 에서 중단 (마지막 체크포인트 20,000)60,00020,000 부터 이어서 60,000 까지 학습합니다

새 목표가 이전 목표 이하이면 새 목표 step(50,000)은 이전 목표(50,000)보다 커야 합니다. 처럼 나오고 재개 시작 이 눌리지 않습니다. 그래서 중간에 멈춘 학습을 원래 목표까지만 마치는 설정은 할 수 없습니다. 이전 목표보다 큰 값을 넣으세요.

재개 시작 을 누르면 새 학습과 같은 실행 화면(5.4절)이 나옵니다. 실행되는 명령은 이런 모양입니다.

lerobot-train \
  --config_path=/home/<사용자>/.PhysicalLabs/outputs/train/a-ba/act/pick_and_place/checkpoints/last/pretrained_model/train_config.json \
  --resume=true \
  --steps=60000

8.3. [앱] 학습 삭제

  1. [앱] 학습 재개 목록 위쪽의 학습 삭제 를 누릅니다.
  2. [앱] 지울 학습 카드를 눌러 고르고 삭제 (N) 을 누릅니다 (그만두려면 취소).
  3. [앱] 모델 삭제 확인 창에서 Yes 를 누르면 그 학습 폴더가 체크포인트까지 모두 지워집니다.

지운 학습은 되돌릴 수 없습니다

디스크의 파일이 모두 삭제됩니다. 학습이 진행 중일 때는 학습이 진행 중이라 로컬 모델을 삭제할 수 없습니다. 가 뜨고 지워지지 않습니다.


9. 문제 해결

증상확인할 것
훈련 탭에 설치 카드만 보입니다처음 한 번은 설치가 필요합니다. 인터넷을 연결하고 설치하기 를 누릅니다 → 기능 패키지 설치
NVIDIA GPU 가 있는데 GPU 버전 PyTorch 설치 버튼이 없습니다배너 문구를 봅니다 (2.2절 표). 드라이버가 570 미만이면 올린 뒤 다시 검사 를 누릅니다
실행 출력에 Device 'cuda' is not available. Switching to 'cpu'. 가 보입니다GPU 를 못 쓰고 CPU 로 학습하는 중입니다. GPU 버전을 설치한 뒤 앱을 다시 시작했는지, CUDA 지원 카드가 정상 인지 확인합니다
학습이 시작하자마자 멈춥니다환경 진단 의 영상 디코더 카드가 없음 이면 눌러서 설치합니다 (2.3절). 실행 출력의 마지막 오류 줄도 확인합니다
실행 출력에 CUDA out of memory 가 보입니다GPU 메모리가 모자랍니다. 배치 크기 를 줄이고(예: 8 → 4), 다른 학습이나 GPU 를 쓰는 프로그램을 끈 뒤 다시 시작합니다
SmolVLA · X-VLA 학습이 Feature mismatch 로 멈춥니다명령 미리보기에 카메라 이름 맞춤 줄이 있었는지 봅니다. 없었다면 인터넷을 연결하고 데이터 증강 화면에서 다음 → 을 다시 눌러 미리보기를 새로 만듭니다 (5.2절)
데이터셋 선택에 내 데이터셋이 없습니다이 PC 에 있는 데이터셋만 보입니다. 새로고침 을 누르고, Hub 에만 있으면 데이터셋 창고에서 내려받습니다
SO-101 데이터셋인데 ⚠ so_follower — 지금 로봇과 다름 이 보입니다앱의 표시 문제입니다 (4.1절 정보 상자). SO-101 로 모은 데이터셋이 맞으면 Yes 를 누릅니다
오류: 프로세스 시작 실패 (실행 파일 또는 권한 확인). …학습 명령(lerobot-train)을 실행하지 못했습니다. 앱은 앱 메뉴나 터미널의 physical-labs 로 실행해야 이 명령을 찾습니다. 그래도 나오면 환경 진단 의 lerobot[training] 카드를 보고, 설정 › 기능 패키지 에서 다시 설치합니다
학습 패키지 미설치 창이 뜹니다설정 › 기능 패키지 에서 학습 패키지를 설치하거나 환경 진단 의 lerobot[training] 카드를 누릅니다
wandb 로깅 사용 을 켜면 학습이 바로 실패합니다터미널에서 wandb login 을 했는지 확인합니다 (6절)
학습이 끝났는데 Hub 에 모델이 없습니다학습을 끝까지 마쳤는지(중단하면 안 올라감), 토큰이 저장돼 있고 쓰기 권한이 있는지, 인터넷이 되는지, policy.repo_id 가 맞는지 확인합니다
학습 재개 목록이 비어 있습니다지금 로봇의 학습만 보입니다. 로봇을 지웠다 다른 이름으로 다시 만들었다면 예전 학습은 ~/.PhysicalLabs/outputs/train/<예전 로봇 이름>/ 에 그대로 있고, 같은 robot id 로 로봇을 저장하면 다시 보입니다
재개 시작 이 눌리지 않습니다새 목표 step (누적) 이 이전 목표보다 커야 합니다 (8.2절)
재개한 학습이 시작하자마자 멈춥니다처음 학습에 쓴 데이터셋을 지웠거나 옮겼을 수 있습니다. 같은 데이터셋을 처음 위치로 되돌린 뒤 다시 재개합니다 (8.2절)
앱을 껐더니 학습이 멈췄습니다정상 동작입니다. 마지막 체크포인트부터 학습 재개 로 이어 갑니다

그 밖의 앱 전반 문제는 문제 해결을 보세요.


10. 정리

다음 페이지 추론에서는 학습한 정책으로 로봇을 스스로 움직여 봅니다.