JSHNSL/humanoid-imitation-learning

Cyclo-Lab → LeRobot Sim2Real 워크플로우

FFW_SG2 (L-Table) 기준. HF 계정: JSHNSL.

핵심: 단계마다 실행하는 파이썬이 다르다.

명령	실체	용도
lerobot-python	lerobot venv (/root/lerobot_env, py3.12 / lerobot 0.5.2 / 데이터 v3.0)	변환·업로드·학습
python	Isaac Sim (_isaac_sim/python.sh, py3.11 / lerobot 0.3.3 / 데이터 v2.1)	시뮬 롤아웃 (isaaclab)
$ISAACLAB_PATH/_isaac_sim/python.sh	위 python의 풀 경로	isaac python에 pip 설치할 때

⚠️ 버전 분리: 학습용 venv는 lerobot 0.5.2(v3.0). 롤아웃용 isaac python은 3.11이라 0.5.2(≥3.12 요구)를 못 넣어 0.3.3 유지. 둘은 별개라 서로 영향 없음.

---

이 저장소 구조 (JSHNSL/humanoid-imitation-learning)

코드 · 모델 · 데이터셋이 이 repo 한 곳에 모여 있음. 베이스는 ROBOTIS cyclo_lab + lerobot-cyclo 0.5.2.

humanoid-imitation-learning/
├── README.md                        이 문서 (= WORKFLOW.md)
├── LEROBOT_UPGRADE.md               lerobot 0.3.3 → 0.5.2 업그레이드
├── DASHBOARD_CHANGES.md             대시보드 세션 네이밍 변경
├── HDF5_HUB_README.md               HDF5 허브 repo의 README (sync_docs.py가 업로드)
├── push_dataset.py                  LeRobot 데이터셋 HF 업로드 (학습용 repo)
├── push_hdf5.py                     원본 HDF5 HF 업로드 (HDF5 허브 repo)
├── merge_hdf5_demos.py              HDF5 병합 (세션/단계별)
├── hpo_optuna.py                    Optuna 하이퍼파라미터 튜닝 + 튜닝값으로 학습
├── hpo_train_shim.py                └ 튜닝이 쓰는 학습 런처 (diffusion 샘플러 버그 우회)
├── sg2_ltable_dashboard.py          녹화·파이프라인 대시보드 (세션 네이밍)
├── scripts/sim2real/imitation_learning/
│   ├── data_converter/isaaclab2lerobot.py      HDF5 → LeRobot(v3.0) 변환
│   └── inference/
│       ├── eval_policy_sim.py                   시뮬 롤아웃 평가
│       └── convert_policy_v05_to_v03.py         0.5.2 정책 → 0.3.3 (롤아웃용)
├── models/                          학습 정책 (0.5.2 원본 + _v03 롤아웃용)
└── datasets/ffw_sg2_ltable_merge/   v3.0 LeRobot 데이터셋

재현 순서: ① cyclo_lab + lerobot-cyclo 준비 → ② 위 스크립트 배치 → ③ 아래 파이프라인 실행.

---

Setup — 환경 준비 (최초 1회)

Prerequisites: NVIDIA Docker(Container Toolkit) · Isaac Sim 컨테이너 요구사항 충족 · NVIDIA GPU + 드라이버

1. EKAIWORKER 오버레이 클론 + 셋업 — cyclo_lab / ai_worker / robotis_applications 한 번에:

git clone https://github.com/Disniekie01/EKAIWORKER.git AIWORKER
cd AIWORKER
./setup.sh ~/AIWORKER

setup.sh가 세 저장소를 고정 커밋으로 클론 + 서브모듈 초기화 + 오버레이 적용까지 자동 처리 (upstream 전체를 vendoring 하지 않음). 구성:

• cyclo_lab — Isaac Sim 환경 · 녹화 · Mimic 파이프라인 (+ 이 워크플로우 스크립트)
• ai_worker — 모션 제어
• robotis_applications — VR teleop 퍼블리셔

2. Docker 컨테이너 기동:

cd ~/AIWORKER/cyclo_lab/docker && ./container.sh start              # 학습·시뮬 (필수)
cd ~/AIWORKER/robotis_applications/docker && ./container.sh start   # VR teleop (녹화 시)
cd ~/AIWORKER/ai_worker/docker && ./container.sh start              # 모션 제어 (녹화 시)

컨테이너 진입 (이후 모든 작업은 이 안에서):

cd ~/AIWORKER/cyclo_lab && ./docker/container.sh enter

포함된 것: Isaac Sim 5.1.0 · Isaac Lab v2.3.0 · CycloneDDS 0.10.2 · LeRobot venv

3. LeRobot 0.5.2(v3.0) 설치 (학습 venv /root/lerobot_env, 자세히는 LEROBOT_UPGRADE.md):

(a) venv가 이미 있으면 (lerobot-python alias 동작) — 업그레이드만:

lerobot-pip install "lerobot[training,av-dep] @ git+https://github.com/ROBOTIS-GIT/lerobot-cyclo.git"

(b) venv가 없으면 — 처음부터 생성. ⚠️ python3는 isaac 3.11 alias라 안 됨 → 시스템 python3.12로:

/usr/bin/python3.12 -m venv /root/lerobot_env
/root/lerobot_env/bin/pip install --upgrade pip
/root/lerobot_env/bin/pip install "lerobot[training,av-dep] @ git+https://github.com/ROBOTIS-GIT/lerobot-cyclo.git" h5py
# alias 등록
cat >> ~/.bashrc <<'EOF'
export LEROBOT_VENV=/root/lerobot_env
alias lerobot-python='${LEROBOT_VENV}/bin/python3'
alias lerobot-pip='${LEROBOT_VENV}/bin/pip'
alias lerobot-hf='${LEROBOT_VENV}/bin/hf'
alias lerobot-activate='source ${LEROBOT_VENV}/bin/activate'
EOF
source ~/.bashrc
lerobot-python -c "import lerobot; print(lerobot.__version__)"   # 0.5.2 확인

⚠️ (필수) torch/torchvision 버전 맞추기 — 안 맞으면 학습이 mismatch로 안 돎:

lerobot-python -c "import torch,torchvision; print(torch.__version__, torchvision.__version__)"
# 반드시  2.7.1+cu128 / 0.22.1+cu128  이어야 함.
# 다르면(예: 2.7.0/0.22.0) 강제 재설치:
lerobot-pip install --index-url https://download.pytorch.org/whl/cu128 \
    --force-reinstall "torch==2.7.1" "torchvision==0.22.1"

롤아웃용 isaac python(3.11)은 0.3.3 유지 (4-a 참고).

4. (녹화 시) VR teleop 대시보드:

cd ~/AIWORKER/cyclo_lab && python3 sg2_ltable_dashboard.py     # http://localhost:8765

5. 이 repo의 스크립트 받기 (컨테이너 안, /workspace/cyclo_lab 에서):

cd /workspace/cyclo_lab

# 루트 스크립트 (변환·업로드·병합·튜닝)
lerobot-hf download JSHNSL/humanoid-imitation-learning \
    push_dataset.py push_hdf5.py merge_hdf5_demos.py \
    hpo_optuna.py hpo_train_shim.py sync_docs.py \
    --local-dir .

# 롤아웃/변환 스크립트 (경로 구조 그대로 재현됨)
lerobot-hf download JSHNSL/humanoid-imitation-learning \
    --include "scripts/sim2real/imitation_learning/**" \
    --local-dir .

--local-dir . 이라 repo 안의 경로가 그대로 재현된다 → scripts/sim2real/imitation_learning/inference/eval_policy_sim.py 등이 제자리에 떨어진다.

⚠️ 기존 파일을 덮어쓴다. 로컬에서 고친 게 있으면 먼저 백업할 것. ⚠️ model repo라 --repo-type 이 필요 없다 (기본값이 model).

6. (선택) 데이터셋·모델: JSHNSL/humanoid-imitation-learning 의 models/ · 데이터셋 repo ffw_sg2_ltable_merge · HDF5 허브 ffw_sg2_hdf5 에서.

→ 이후 매번은 ./docker/container.sh enter 로 접속해서 아래 1~4단계 실행.

---

경로 규칙 (이 repo 그대로 따라할 때)

이 repo에는 scripts/ · datasets/ffw_sg2_ltable_merge/ · models/ 가 들어있음. 아래 명령은 cyclo_lab 루트(/workspace/cyclo_lab)에서 실행 기준이며, repo의 폴더를 cyclo_lab에 배치했다고 가정한다:

repo 폴더	cyclo_lab에 두는 위치	명령에서 쓰는 경로
scripts/	그대로	scripts/sim2real/...
datasets/ffw_sg2_ltable_merge/	./datasets/ 아래	--dataset.root=./datasets/ffw_sg2_ltable_merge
models/<이름>/	./models/ 아래	롤아웃 --policy ./models/<이름>

직접 데이터를 만드는 경우: 변환 출력(./datasets/lerobot/<타임스탬프>)·학습 출력(./outputs/train/<NAME>)을 대신 쓰면 된다.

---

1. HDF5 → LeRobot 변환 (lerobot-python) — 직접 데이터 만들 때만

lerobot-python scripts/sim2real/imitation_learning/data_converter/isaaclab2lerobot.py \
    --task=Cyclo-Real-Pick-Place-LTable-FFW-SG2-v0 \
    --robot_type FFW_SG2 \
    --dataset_file ./datasets/ffw_sg2_l_table_raw.hdf5

결과: ./datasets/lerobot/<타임스탬프>/ (data/ videos/ meta/)

---

1.5 여러 HDF5 병합 (선택) (lerobot-python)

여러 세션/단계의 HDF5를 하나로 합쳐서 변환하고 싶을 때. 스크립트: merge_hdf5_demos.py (저장소 루트에 있음 → 컨테이너 /workspace/cyclo_lab에서 실행).

lerobot-python merge_hdf5_demos.py \
    --inputs <파일1.hdf5> <파일2.hdf5> ... \
    --output <병합결과.hdf5>

• --inputs : 합칠 HDF5들 (원하는 순서대로, 필수)
• --output : 결과 파일 (필수)
• --prefix : 출력 데모 라벨 접두사 (기본 demo)

예 — 한 태스크의 모든 joint 세션을 glob으로:

lerobot-python merge_hdf5_demos.py \
    --inputs datasets/ffw_sg2_l_table/*/*_joint.hdf5 \
    --output datasets/ffw_sg2_l_table_merged_joint.hdf5

• 데모 라벨(demo_0..demo_N)은 숫자순 정렬 + 순차 재번호 처리됨
• 합치는 파일끼리 로봇·태스크·차원·카메라가 같아야 함 (보통 joint끼리)
• 병합 후 isaaclab2lerobot(1단계)에 --dataset_file 로 넘겨 변환
• raw를 섞을 땐 먼저 action_data_converter --action_type joint 로 통일

---

2. HuggingFace 업로드 — 전부 humanoid-imitation-learning 한 repo로

별도 데이터셋/모델 repo를 만들지 않고 이 repo의 하위폴더(datasets/, models/)에 모은다.

로그인 (1회):

export HF_TOKEN=hf_write토큰          # 또는: lerobot-python -c "from huggingface_hub import login; login()"
unset HF_HUB_OFFLINE                  # 오프라인 변수 남아있으면 해제

데이터셋 → 별도 dataset repo (학습에서 --dataset.repo_id로 바로 당기려면 dataset 타입 repo여야 함):

lerobot-python push_dataset.py \
    --repo_id JSHNSL/ffw_sg2_ltable_merge \
    --root ./datasets/lerobot/<타임스탬프>       # 1단계 변환 출력 폴더

→ https://huggingface.co/datasets/JSHNSL/ffw_sg2_ltable_merge (3단계 학습이 이걸 씀)

모델(학습 결과) → models/<이름>/:

lerobot-python -c "
from huggingface_hub import upload_folder
upload_folder(folder_path='./outputs/train/act_merge/checkpoints/last/pretrained_model',
  repo_id='JSHNSL/humanoid-imitation-learning', repo_type='model',
  path_in_repo='models/act_merge')
"

그래서 학습은 --policy.push_to_hub=false로 두고(별도 repo 안 만들게), 여기처럼 수동 업로드한다.

---

2.5 원본 HDF5 → HDF5 허브 repo (push_hdf5.py)

push_dataset.py는 변환된 LeRobot 데이터셋(meta/ data/ videos/)만 올린다. Isaac Sim에서 나온 원본 HDF5(raw / annotate / ik / generate / joint)는 별도 "허브" dataset repo에 쌓는다.

왜 따로?

• 학습용 repo(ffw_sg2_ltable_merge)는 학습 때마다 통째로 받으므로 가볍게 유지해야 함 (HDF5는 수 GB)
• 허브 repo엔 앞으로 다른 태스크 HDF5도 계속 누적 가능

허브 repo: JSHNSL/ffw_sg2_hdf5 (dataset 타입, public) → 업로드/다운로드 방법은 그 repo의 README에도 정리되어 있음 (HDF5_HUB_README.md)

export HF_TOKEN=hf_write토큰
unset HF_HUB_OFFLINE

# 1) 뭐가 올라갈지 먼저 확인 (업로드 안 함)
lerobot-python push_hdf5.py \
    --repo_id JSHNSL/ffw_sg2_hdf5 \
    --paths datasets/ffw_sg2_l_table \
    --dry_run

# 2) 실제 업로드 (repo 없으면 자동 생성)
lerobot-python push_hdf5.py \
    --repo_id JSHNSL/ffw_sg2_hdf5 \
    --paths datasets/ffw_sg2_l_table

폴더 구조가 repo 안에 그대로 보존된다 — 태스크별로 자연스럽게 분리됨:

ffw_sg2_l_table/20260710/1421_58_ffw_sg2_l_table_raw.hdf5
ffw_sg2_l_table/20260710/1425_58_ffw_sg2_l_table_ik.hdf5
...

주요 옵션:

옵션	설명
--paths	파일/디렉토리 여러 개 가능. 디렉토리는 재귀 탐색(*.hdf5), 디렉토리 이름이 repo 안 최상위 폴더가 됨
--dry_run	올릴 목록 + 총 용량만 출력하고 종료 (항상 먼저 실행 권장)
--path_in_repo	repo 안 접두 경로 (예: --path_in_repo hdf5). 기본은 repo 루트
--private	비공개 repo로 생성

파일 하나만 올리기 / 여러 경로 한 번에:

lerobot-python push_hdf5.py --repo_id JSHNSL/ffw_sg2_hdf5 \
    --paths datasets/ffw_sg2_l_table_joint.hdf5 datasets/other_dataset --dry_run

다시 받기 (lerobot-hf = venv의 hf CLI. --repo-type dataset 필수):

# 파일 하나
lerobot-hf download JSHNSL/ffw_sg2_hdf5 --repo-type dataset \
    0713_ffw_sg2_l_table_annotate_merge_num96.hdf5 \
    --local-dir ./datasets

# 패턴으로 (예: joint 단계만)
lerobot-hf download JSHNSL/ffw_sg2_hdf5 --repo-type dataset \
    --include "*_joint.hdf5" --local-dir ./datasets

⚠️ HDF5는 크다(단일 3~5GB도 있음). 업로드 전 --dry_run으로 총 용량 확인 필수.

---

2.6 HF에 올린 파일 삭제

잘못 올렸을 때. lerobot-hf repos delete-files 사용 (write 토큰 필요).

lerobot-hf auth login          # 안 했으면

dataset repo (HDF5 허브 등) — --repo-type dataset 필수:

# 파일 하나
lerobot-hf repos delete-files JSHNSL/ffw_sg2_hdf5 \
    1425_58_ffw_sg2_l_table_ik.hdf5 --repo-type dataset

# 여러 개 (공백 구분)
lerobot-hf repos delete-files JSHNSL/ffw_sg2_hdf5 \
    a.hdf5 b.hdf5 --repo-type dataset

# 패턴 (fnmatch, '*'는 재귀)
lerobot-hf repos delete-files JSHNSL/ffw_sg2_hdf5 \
    "*_ik.hdf5" --repo-type dataset

# 폴더 통째로
lerobot-hf repos delete-files JSHNSL/ffw_sg2_hdf5 \
    "ffw_sg2_l_table/*" --repo-type dataset

model repo (humanoid-imitation-learning) — --repo-type 생략 (기본이 model):

lerobot-hf repos delete-files JSHNSL/humanoid-imitation-learning "models/act_8ep/*"

repo 자체 삭제:

lerobot-hf repos delete JSHNSL/어떤repo --repo-type dataset

주의사항:

• ⚠️ --repo-type dataset 빼먹으면 model repo를 찾아서 엉뚱하게 실패한다 (다운로드 때와 같은 함정)
• 패턴이 뭘 지울지 애매하면 repo의 Files and versions 탭에서 먼저 확인
• --create-pr 붙이면 바로 안 지우고 PR로 만들어 검토 후 머지 가능 (실수 방지)

⚠️ 삭제해도 용량은 안 줄어든다 → 스쿼시로 회수

HF는 git 기반이라 delete-files로 지워도 히스토리에 blob이 그대로 남아 저장소 용량은 안 줄어든다. repo를 안 지우고 용량을 회수하려면 히스토리를 스쿼시한다 (커밋을 하나로 눌러 옛 blob 제거).

# ① 먼저 파일을 실제로 삭제 (아직 히스토리엔 남아있음)
lerobot-hf repos delete-files JSHNSL/ffw_sg2_hdf5 "지울파일.hdf5" --repo-type dataset

# ② 히스토리 스쿼시 → 여기서 용량이 실제로 회수됨
lerobot-python -c "
from huggingface_hub import HfApi
HfApi().super_squash_history(repo_id='JSHNSL/ffw_sg2_hdf5', repo_type='dataset')
print('squashed')
"

순서가 중요하다: ①로 지우고 → ②로 스쿼시. 스쿼시는 현재 HEAD 상태만 남기고 이전 커밋을 전부 버리므로, 이미 삭제된 파일의 blob이 함께 사라진다.

대가:

• ⚠️ 커밋 히스토리 영구 소멸 — 되돌릴 수 없다
• ⚠️ 스쿼시한 브랜치는 다른 브랜치와 히스토리가 갈라져 머지 불가
• 과거 버전에 접근할 일이 없을 때만. (HDF5 원본 보관 repo면 히스토리가 별 의미 없어 부담이 적다)
• CLI 명령은 없다 → 파이썬으로만 가능. write 토큰 필요.

방법	용량 회수	히스토리	repo
delete-files 만	❌	유지	유지
delete-files + super_squash_history	✅	소멸	유지 ← 보통 이걸 원함
repo 삭제 후 재생성	✅	소멸	새로 만들어야 함 (README·설정 다시)

---

3. 학습 — ACT / VQ-BeT / Diffusion (lerobot-python)

데이터는 dataset repo JSHNSL/ffw_sg2_ltable_merge 에서 자동으로 받음 (없으면 2단계에서 먼저 생성).

공통 명령 (<POLICY>, <NAME>만 바꿈):

unset HF_HUB_OFFLINE
lerobot-python -m lerobot.scripts.lerobot_train \
    --dataset.repo_id=JSHNSL/ffw_sg2_ltable_merge \
    --policy.type=<POLICY> \
    --output_dir=./outputs/train/<NAME> \
    --policy.device=cuda \
    --policy.push_to_hub=false \
    --num_workers=8 --dataset.video_backend=pyav \
    --steps=100000 --save_freq=20000

정책	<POLICY>	<NAME>	특징
ACT	act	act_merge	기본·빠름·안정적
VQ-BeT	vqbet	vqbet_merge	멀티모달
Diffusion	diffusion	diffusion_merge	멀티모달·느림·모델 큼, diffusers 필요

• 모듈명(0.5.x): lerobot.scripts.lerobot_train (구버전 ...train 아님)
• --dataset.repo_id : dataset repo JSHNSL/ffw_sg2_ltable_merge → HF에서 자동 다운로드·캐시 (온라인·로그인 필요)
• ⚠️ model repo(JSHNSL/humanoid-imitation-learning)를 넣으면 dataset 조회 404 → 반드시 dataset repo만
• 로컬 폴더로 쓰려면 → --dataset.root=<meta/info.json 있는 폴더> 추가 (예: 직접 변환한 ./datasets/lerobot/<타임스탬프>)
• --num_workers=8 --dataset.video_backend=pyav : 워커 세그폴트 회피. (안전빵은 --num_workers=0, 대신 느림)
• --policy.push_to_hub=false : 업로드는 2단계에서 humanoid로 수동
• diffusion ModuleNotFoundError: diffusers → lerobot-pip install diffusers
• 하나씩 돌리기 (동시 실행 시 GPU OOM). 데이터셋은 v3.0 필요 (v2.1이면 3.5로 변환)

학습 결과 확인

• 학습 중(터미널): step:200 ... loss:0.12 grdn:0.30 updt_s:0.01 ... → loss가 꾸준히 내려가면 정상
• 체크포인트: outputs/train/<NAME>/checkpoints/ (020000/, last/ ...)
• 최종 정책 파일: outputs/train/<NAME>/checkpoints/last/pretrained_model/ (config.json + model.safetensors)
• 실제 성능(성공률): 4단계 시뮬 롤아웃으로 측정 (진짜 평가는 이것)
• 확인 끝나면 → 2단계로 models/<NAME> 업로드

---

3.2 하이퍼파라미터 튜닝 — Optuna (hpo_optuna.py)

정책 이름 + 데이터셋만 주면 → 탐색 → best 저장 → 그 값으로 전체 학습 → HF 업로드까지.

lerobot-pip install optuna        # 최초 1회

파일 2개 필요: hpo_optuna.py + hpo_train_shim.py (같은 폴더에). shim은 trial 학습을 실행하는 런처다.

---

한 방에: 탐색 → 학습 → 배포

lerobot-hf auth login          # 업로드하려면 먼저 (1회)

lerobot-python hpo_optuna.py \
    --policy diffusion \
    --repo_id JSHNSL/ffw_sg2_ltable_merge \
    --n_trials 12 \
    --steps 5000 \
    --num_workers 8 \
    --then_train \
    --full_steps 100000 \
    --push_to_hub \
    --hub_name diffusion_tuned \
    --fresh

--policy: act | vqbet | diffusion

결과물

• best 파라미터 → outputs/hpo/<policy>/best_params.json
• 학습 결과 → outputs/train/<policy>_tuned/checkpoints/last/pretrained_model/
• 업로드 → JSHNSL/humanoid-imitation-learning 의 models/<hub_name>/ (가중치 + hpo_best_params.json)

---

나눠서 실행

하고 싶은 것	명령
탐색만	hpo_optuna.py --policy act --n_trials 12 --steps 5000
저장된 best로 학습만	hpo_optuna.py --policy act --train_best
저장된 best로 학습 + 배포	hpo_optuna.py --policy act --train_best --push_to_hub
결과 보기	hpo_optuna.py --policy act --report_only
처음부터 다시	위 명령에 --fresh 추가

--then_train = "학습까지", --push_to_hub = "배포까지". 둘 다 없으면 탐색만 한다. --fresh 없이 재실행하면 기존 study에 trial이 누적된다.

---

주요 옵션

인자	기본값	설명
--n_trials	20	시도할 조합 수. core 공간(45차원)이면 **1015로 충분**
--steps	8000	trial당 학습 스텝. 너무 줄이지 말 것 (아래 참고)
--num_workers	8	dataloader 워커. 8이면 GPU가 이미 포화 — 더 늘려도 이득 없다
--val_ratio	0.2	에피소드의 20%를 val로 분리
--fresh	—	기존 study를 버리고 처음부터
--space	core	아래 참고
전체 학습
--full_steps	100000	전체 학습 스텝
--save_freq	full_steps/5	체크포인트 주기
--full_batch_size	튜닝된 값	OOM 날 때 덮어쓰기
--full_num_workers	--num_workers	전체 학습용 워커
--hub_name / --hub_repo_id	<policy>_tuned / humanoid repo	업로드 위치
--train_extra	—	나머지를 lerobot_train에 그대로 전달 (맨 뒤에)

---

무엇을 튜닝하는가 — --space core (기본)

정책	탐색 대상
ACT	optimizer_lr, optimizer_lr_backbone, optimizer_weight_decay, dropout, batch_size
VQ-BeT	optimizer_lr, optimizer_vqvae_lr, optimizer_weight_decay, dropout, batch_size
Diffusion	optimizer_lr, optimizer_weight_decay, scheduler_warmup_steps, batch_size

chunk_size · horizon · n_action_steps · kl_weight · offset_loss_weight 등은 탐색하지 않고 lerobot 기본값으로 고정한다. 이유:

목적함수가 val loss인데, 이 값들은 손실의 정의 자체를 바꾼다.

• 예측 길이(horizon/chunk_size): 8스텝 앞 예측이 32스텝 앞보다 쉬우니 loss가 낮다 → 탐색이 무조건 짧은 chunk를 고른다. 정작 긴 chunk가 태스크 성공엔 더 좋은 경우가 많다.
• 손실 가중치(kl_weight, offset_loss_weight): 손실 항에 곱해지는 값이라 작을수록 숫자가 작아진다. 품질과 무관하게 최솟값이 뽑힌다.

즉 이것들을 넣으면 탐색이 목적함수를 속인다. 남은 것(학습률·weight decay·dropout·batch)은 같은 목적함수를 얼마나 잘 최적화하는지만 바꾸므로 공정하다.

--space full 로 전부 탐색할 수도 있지만, 위 편향 경고가 출력된다.

---

목적함수 = held-out validation loss

lerobot엔 validation split이 없고 내장 eval_freq는 gym 환경 전용이라, 에피소드를 나눠(--dataset.episodes) val을 직접 만든다. 각 trial은 train 에피소드로 짧게 학습 → 그 체크포인트를 val 에피소드에서 채점(lerobot과 동일한 preprocessor) → Optuna가 val loss를 최소화한다.

⚠️ val loss는 순위를 매기는 프록시일 뿐, 태스크 성공을 보장하지 않는다. 최종 선택은 4단계 시뮬 롤아웃 성공률로 할 것.

---

예산 정하기

diffusion 실측 5.7 step/s (RTX PRO 5000, batch 16):

설정	총 연산	탐색 시간
--n_trials 12 --steps 5000 (권장)	60k 스텝	~3시간
--n_trials 20 --steps 8000	160k 스텝	~8시간

여기에 --full_steps 100000 전체 학습이 ~5시간 추가된다. (pruning이 가망 없는 trial을 조기 종료하므로 실제로는 더 짧다)

⚠️ 시간을 줄이려면 --n_trials를 낮출 것. --steps는 건드리지 말 것. 짧게 학습하면 초반에만 빠른 높은 학습률이 유리해 보인다 → 정작 전체 학습에선 나쁜 값을 고르게 된다.

⚠️ 병렬(--n_jobs)은 이 GPU에선 이득이 없다. 학습 1개가 이미 GPU 100% / 10.5GB를 쓴다.

---

긴 학습은 tmux 안에서 (특히 EC2)

SSH가 끊기면 학습이 같이 죽는다 (connection reset by peer).

tmux new -s hpo
# ... 컨테이너 진입 후 위 명령 실행 ...
# 빠져나오기: Ctrl+B 누르고 D   (학습은 계속 돌아감)

tmux attach -t hpo      # 재접속 후 이어서 보기

---

3.5 기존 v2.1 데이터셋 → v3.0 변환 (lerobot-python)

예전에 만든 standalone v2.1 데이터셋 repo가 있을 때만 필요. (이 repo의 데이터는 이미 v3.0이라 불필요)

lerobot-python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id <예전-v2.1-데이터셋-repo> \
    --push-to-hub true

• HF 로그인·온라인 필요 (HF_HUB_OFFLINE 설정돼 있으면 해제)
• 이미 v3.0이면 --force-conversion
• 새로 뽑는 데이터는 (0.5.2 변환기라) 처음부터 v3.0 → 변환 불필요

---

4. 시뮬 롤아웃 평가 (python = isaac)

왜 변환이 필요한가: 롤아웃은 Isaac Sim(py3.11 / lerobot 0.3.3) 안에서 정책을 로드함. Isaac Sim이 3.11이라 0.5.2(≥3.12)를 못 넣음 → 0.5.2로 학습한 정책은 0.3.3용으로 변환 후 롤아웃. (예전 0.3.3 정책은 변환 없이 바로 repo_id 사용)

4-a. isaac python 환경 세팅 (1회)

$ISAACLAB_PATH/_isaac_sim/python.sh -m pip install --no-deps lerobot==0.3.3
$ISAACLAB_PATH/_isaac_sim/python.sh -m pip install \
    draccus deepdiff jsonlines termcolor packaging imageio datasets \
    einops safetensors huggingface_hub
# diffusion 쓸 때만 추가:  diffusers
$ISAACLAB_PATH/_isaac_sim/python.sh -m pip install diffusers

# ⚠️ 마지막에 반드시 numpy를 되돌린다 (아래 참고)
$ISAACLAB_PATH/_isaac_sim/python.sh -m pip install "numpy==1.26.0"

⚠️ (필수) numpy는 반드시 1.x — 안 그러면 롤아웃이 Segmentation fault 로 죽는다.

datasets 를 설치하면 numpy가 2.x로 딸려 올라간다. 그런데 Isaac Sim의 컴파일된 모듈들은 numpy 1.x에 맞춰 빌드돼 있다 (isaaclab, isaaclab-tasks, nvidia-srl-usd 가 전부 numpy<2 를 요구). numpy 2.x와 1.x는 C ABI가 호환되지 않아 임포트/실행 중 segfault 가 난다. (ModuleNotFoundError 가 아니라 아무 메시지 없이 죽는다 — 그래서 원인 찾기가 어렵다.)

설치 후 반드시 확인 — 정상 값:

$ISAACLAB_PATH/_isaac_sim/python.sh -c "
import numpy, lerobot, torch
print('numpy  :', numpy.__version__)     # 1.26.0   ← 2.x면 segfault!
print('lerobot:', lerobot.__version__)   # 0.3.3
print('torch  :', torch.__version__)     # 2.7.0+cu128
"

2.x면 되돌린다:

$ISAACLAB_PATH/_isaac_sim/python.sh -m pip install "numpy==1.26.0"

packaging 도 26.x로 올라가 있으면 lerobot과 충돌하니 되돌린다:

$ISAACLAB_PATH/_isaac_sim/python.sh -m pip install "packaging>=24.2,<26"

⚠️ ModuleNotFoundError: No module named 'pip._vendor.packaging._structures' 가 나면 Isaac Sim 내장 pip 자체가 손상된 것이다. -m pip 로는 못 고치니 표준 모듈 ensurepip 으로 복구한다:

$ISAACLAB_PATH/_isaac_sim/python.sh -m ensurepip --upgrade
$ISAACLAB_PATH/_isaac_sim/python.sh -m pip --version     # 복구 확인

그래도 안 되면 get-pip.py 로 복구한다 (pip 없이도 동작 — 자기 안에 pip wheel을 품고 있음):

curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
$ISAACLAB_PATH/_isaac_sim/python.sh /tmp/get-pip.py --ignore-installed
$ISAACLAB_PATH/_isaac_sim/python.sh -m pip --version

⚠️ --force-reinstall 은 쓰지 말 것. 그건 기존 pip을 제거한 뒤 재설치하는데, 제거 과정에서 이미 사라진 _structures.py 를 옮기려다 또 죽는다:

ERROR: Could not install packages due to an OSError: [Errno 2] No such file or directory:
  '.../pip/_vendor/packaging/_structures.py'

--ignore-installed 는 제거 없이 덮어쓰므로 이 문제를 피한다.

그것마저 안 되면 깨진 pip을 통째로 지우고 새로 설치:

SP=$ISAACLAB_PATH/_isaac_sim/kit/python/lib/python3.11/site-packages
rm -rf "$SP/pip" "$SP"/pip-*.dist-info
$ISAACLAB_PATH/_isaac_sim/python.sh /tmp/get-pip.py
$ISAACLAB_PATH/_isaac_sim/python.sh -m pip --version

복구 후 위 설치 명령을 다시 실행하면 된다.

4-b. 0.5.2 정책 → 0.3.3 변환 (직접 학습한 정책만, lerobot-python)

이 repo의 models/*_v03는 이미 변환본 → 이 단계 건너뛰고 4-c로 바로. (직접 학습했을 때만 필요)

# --policy: 직접 학습 출력 폴더 (또는 repo_id / 받은 폴더)
lerobot-python scripts/sim2real/imitation_learning/inference/convert_policy_v05_to_v03.py \
    --policy ./outputs/train/vqbet_merge/checkpoints/last/pretrained_model \
    --out ./models/vqbet_merge_v03

• config 정리 + 정규화 통계 주입 → 0.3.3가 로드 가능하게 (아키텍처 weight는 그대로라 문제없음)
• 새 config 필드 에러 나면 스크립트 _STRIP_KEYS에 그 필드 추가 (diffusion 대응처럼)
• 변환 후 shape mismatch면 아키텍처가 바뀐 것 → DDS 필요 (ACT/VQ-BeT/Diffusion은 OK 확인됨)
• 변환본을 humanoid에 두려면 → models/<이름>_v03로 업로드(2단계 방식)

4-c. 롤아웃 실행 (python = isaac)

HF_HUB_OFFLINE=1 python scripts/sim2real/imitation_learning/inference/eval_policy_sim.py \
    --task Cyclo-Real-Pick-Place-LTable-FFW-SG2-v0 \
    --robot_type FFW_SG2 \
    --policy ./models/vqbet_merge_v03 --policy_type vqbet \
    --num_rollouts 10 --enable_cameras \
    --scripted_l_motion

• --policy : 이 repo의 ./models/<이름>_v03 (또는 직접 변환한 폴더) / repo_id(예전 0.3.3 정책)
• 정책 바꾸기: --policy_type act | vqbet | diffusion + --policy 폴더도 그 정책 것으로 (예: ./models/diffusion_merge_v03 --policy_type diffusion)
• --scripted_l_motion: L-Table은 이동이 스크립트라 필수 (정책은 파지/놓기만 학습)
• 강제 종료: 다른 터미널에서 pkill -9 -f eval_policy_sim.py

4-d. (대안) 변환 없이 0.5.2 그대로 — DDS 2-프로세스

0.5.2 정책을 그대로 쓰려면 정책을 별도 3.12 프로세스로 서빙 + Isaac Sim(3.11)과 DDS 통신 (cyclo_intelligence 방식). 변환 불필요하나 셋업이 무거움 → 실물/정식 배포용. 빠른 시뮬 확인은 4-b(변환) 방식이 실용적.

---

최초 1회만 필요했던 환경 수정 (참고)

문제	해결 (어디서, 전부 lerobot venv)
lerobot 0.5.2(v3.0)로 업그레이드	lerobot-pip install "lerobot @ git+https://github.com/ROBOTIS-GIT/lerobot-cyclo.git"
0.5.2 av 충돌 (av.option)	lerobot-pip install "av>=15.0.0,<16.0.0"
0.5.2 학습에 accelerate 필요	lerobot-pip install "lerobot[training] @ git+https://github.com/ROBOTIS-GIT/lerobot-cyclo.git"
Blackwell GPU(sm_120) torch	0.5.2는 cu128 기본이라 자동 해결. (구버전 0.3.3: lerobot-pip install --index-url https://download.pytorch.org/whl/cu128 --force-reinstall "torch==2.7.1" "torchvision==0.22.1")
학습 시 영상 디코딩 세그폴트	--num_workers=0 (또는 apt install ffmpeg)
isaac python 에 lerobot 의존성 없음	위 4-a (롤아웃용 0.3.3)

---

정책 종류

act (기본, 무난) · vqbet (멀티모달) · diffusion (멀티모달, 추론 느림) 어느 단계든 --policy.type / --policy_type 만 바꾸면 동일하게 동작.

한 줄 요약: 변환(lerobot-python) → 업로드(lerobot-python) → 학습(lerobot-python) → 롤아웃(python + HF_HUB_OFFLINE=1)