elice_gr00t_install

GR00T N1.7 (lerobot native GrootPolicy) 학습 환경 설치 + 데이터 검증 + 동시 학습 실행 스크립트 모음.

UR7e / RH5DG2 Isaac Lab task를 EE-space 수정 데이터셋으로 파인튜닝하기 위한 세팅이며, A100 80GB × 4 장비에서 두 task(cup_hang, pour_cup)를 GPU를 2장씩 나눠 동시에 학습한다.

---

1. 왜 이 repo가 필요한가

맨바닥(conda 없음 / ffmpeg 없음 / HF 로그인 없음) 서버에서 lerobot 81db623b(0.6.1) + GR00T N1.7 학습을 굴리려면 문서에 안 나오는 함정이 3개 있다. 이 repo의 setup.sh는 그 3개를 전부 흡수한 idempotent 설치 스크립트다.

함정 ① Python 3.11 로는 설치 자체가 안 된다

lerobot 81db623b의 pyproject.toml 이 requires-python = ">=3.12". 3.11 env 에서 pip install -e '.[groot]' 하면:

ERROR: Package 'lerobot' requires a different Python: 3.11.16 not in '>=3.12'

→ conda env 는 Python 3.12 로 만든다.

함정 ② .[groot] 가 torch 와 ABI 안 맞는 torchvision 을 끌어온다

extras 가 PyPI 기본 빌드 torchvision 을 설치하는데, 이게 torch 2.11.0+cu128 과 ABI 불일치:

RuntimeError: operator torchvision::nms does not exist

버전 번호가 같아서(0.26.0) 그냥 pip install 하면 Requirement already satisfied 로 no-op 이 된다. → --force-reinstall --no-deps 로 cu128 wheel 을 강제 교체해야 한다.

pip install --force-reinstall --no-deps \
  --index-url https://download.pytorch.org/whl/cu128 torchvision==0.26.0
# -> torchvision 0.26.0+cu128

함정 ③ torchcodec 이 ffmpeg 를 못 찾는다 + LD_LIBRARY_PATH 필수

학습에 --dataset.video_backend=torchcodec 을 쓰는데, 이 서버엔 시스템 ffmpeg 가 없다:

OSError: libavutil.so.60: cannot open shared object file

conda-forge 로 ffmpeg 를 env 안에 깔면 libavutil.so.60 은 생기지만, 그것만으로는 부족하다. conda ffmpeg 가 딸고 오는 libopenvino.so 가 시스템 libstdc++ 로는 로드가 안 된다:

OSError: /lib/x86_64-linux-gnu/libstdc++.so.6: version `CXXABI_1.3.15' not found
         (required by .../lib/libopenvino.so.2600)

→ env 의 lib 디렉터리를 loader path 에 반드시 올려야 한다. 세 스크립트 전부에 들어있다:

export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH

이거 빠지면 학습이 데이터 로딩 단계에서 죽는다.

함정 ④ (실행 시) lerobot_train.py 는 파일 경로로 실행하면 안 된다

lerobot_train.py 는 상대 import (from .lerobot_eval import eval_policy_all) 를 쓴다. 그래서 accelerate launch .../scripts/lerobot_train.py 로 띄우면:

ImportError: attempted relative import with no known parent package

→ 모듈로 실행한다: accelerate launch --module lerobot.scripts.lerobot_train

---

2. 파일

파일	역할
setup.sh	miniconda → conda env(py3.12) → torch cu128 → lerobot 81db623b .[groot]+.[training] → torchvision ABI 수정 → ffmpeg → hf cli. idempotent
download.sh	데이터셋에서 필요한 두 폴더만 다운로드 (cup_hang_ee/, pour_cup_ee/) + 잘못된 폴더 혼입 경고
verify_dataset.py	학습 전 읽기전용 검증 — ①포맷 v3.0 ②EE convention ③LeRobotDataset 로드
train_all.sh	검증 재실행 → 두 job 을 GPU 2장씩 동시 launch → wait → 성공한 task 만 Hub 업로드
upload_task.py	체크포인트 폴더 전체 업로드(sharded safetensors 대응) + 업로드 후 검증
ENVIRONMENT.txt	실제로 동작한 환경 스냅샷
requirements-freeze.txt	pip freeze 전체

---

3. 사용법

bash setup.sh                     # 1회 (재실행해도 안전)

# HF 인증 (dataset private / base model 접근용)
source ~/miniconda3/etc/profile.d/conda.sh && conda activate lerobot_groot
hf auth login                     # 또는 export HF_TOKEN=...

bash download.sh                  # 데이터 두 폴더만

nohup bash train_all.sh > logs/train_all.log 2>&1 &

진행 확인:

tail -f logs/gr00t_n17_cup_hang_ee.log     # GPU 0,1 / port 29500
tail -f logs/gr00t_n17_pour_cup_ee.log     # GPU 2,3 / port 29501
nvidia-smi

---

4. 데이터셋 convention (EE 수정본)

action[:, 0:6]   tool0(EE) delta, 로봇 root 프레임, Diff-IK 단위
                 (Δpos / 0.03 m,  axis-angle Δrot / 0.05 rad)
action[:, 6:19]  손 13 관절 절대 목표값 (rad)
observation.state  (24)
영상  third_person / eye_in_hand  각 (3, 480, 640)

verify_dataset.py 의 EE 판정 기준: arm 6축 std 전부 > 0, |q99| <= 3, mean 평균절대값 < 1. 관절 절대값 convention 폴더는 mean 이 ±3 rad 근처로 나와서 여기서 걸러진다.

실제 검증 결과 (2026-09-08)

cup_hang_ee   codebase_version=v3.0 -> OK
              total_episodes=200  frames=98351
              arm std  = [0.067, 0.043, 0.07, 0.06, 0.153, 0.049]
              arm mean = [-0.006, 0.004, -0.004, 0.008, 0.01, 0.006]   |q99|max=0.702
              task: 'Lift the hung cup off the holder'                  -> EE OK

pour_cup_ee   codebase_version=v3.0 -> OK
              total_episodes=150  frames=69642
              arm std  = [0.079, 0.16, 0.107, 0.242, 0.23, 0.285]
              arm mean = [0.002, -0.012, -0.012, -0.164, -0.05, -0.058] |q99|max=0.611
              task: 'Grasp the cup, lift it, and pour it out.'          -> EE OK

참고: cup_hang_ee 의 arm std 가 pour_cup_ee 보다 뚜렷하게 작다. EE 판정 기준은 확실히 통과하므로 convention 문제는 아니고, cup_hang 의 동작 자체가 더 작은 것으로 보인다.

---

5. 학습 레시피 (GR00T N1.7 native)

--policy.type=groot
--policy.base_model_path=nvidia/GR00T-N1.7-3B
--policy.embodiment_tag=new_embodiment
--policy.device=cuda
--policy.push_to_hub=false
--steps=30000 --save_freq=30000        # 체크포인트는 마지막에 한 번만
--batch_size=16 --num_workers=8 --seed=1000
--dataset.video_backend=torchcodec
--wandb.enable=false

실행:

CUDA_VISIBLE_DEVICES=0,1 accelerate launch --num_processes=2 \
  --mixed_precision=bf16 --main_process_port=29500 \
  --module lerobot.scripts.lerobot_train <위 인자들> ...

effective batch = num_processes(2) × batch_size(16) = 32. steps 는 optimizer update 수.

pi0.5 레시피에서 뺀 것들과 이유

--policy.compile_model / --policy.gradient_checkpointing / --policy.dtype / pi05 optimizer·scheduler override / use_imagenet_stats → GrootConfig 에 해당 필드가 없어서 draccus 가 에러를 낸다. 확인 방법:

python -c "import dataclasses; from lerobot.policies.groot.configuration_groot import GrootConfig; \
           print(sorted(f.name for f in dataclasses.fields(GrootConfig)))"

dtype 대신 accelerate 의 --mixed_precision=bf16 을 쓴다 (FP32 master + BF16 autocast = N1.7 native). pretrained_path 대신 base_model_path + embodiment_tag 를 쓴다.

---

6. 검증된 환경

Python        3.12.14
lerobot       0.6.1 @ 81db623b4409f160901b266776e6e87a87e5b1b8
torch         2.11.0+cu128
torchvision   0.26.0+cu128        <- cu128 강제 재설치 필요
torchcodec    0.11.1
transformers  5.5.4
accelerate    1.14.0
peft          0.20.0
timm          1.0.29
ffmpeg        8.0.1 (conda-forge)
driver        535.230.02  /  A100 80GB PCIe × 4

driver 535(CUDA 12.2) 에서 cu128 wheel 은 CUDA minor version compatibility 로 정상 동작한다.