LaWAM-LIBERO_immigration

LaWAM LIBERO SFT 체크포인트 이관 패키지

이 디렉토리는 LaWAM stage3 LIBERO SFT 체크포인트로 LIBERO 벤치마크를 재현하기 위한 파일 묶음입니다. 학습은 필요 없고, 벤치마크 실행만 하면 됩니다.

• 학습 완료: 25,000 steps (45시간 1분), 2026-08-26 ~ 08-28
• 초기화: lawam_pretrain (stage2 pretrain) → LIBERO SFT
• 학습 데이터: libero mix (1,693 trajectories / 273,465 transitions)
• 실제 글로벌 배치: 64 (per_device 32 × 2 GPU) — run 이름의 batch256은 계획값이며 실제와 다릅니다

이 패키지 용량: 6.7GB (+ Hub에서 별도로 받는 7.1GB → 최종 13.8GB)

---

1. 이 패키지의 구조와 원칙

이 디렉토리 안의 레이아웃은 LaWAM repo root 기준 상대경로를 그대로 재현한 것입니다. 따라서 이관 작업은 "clone → Hub에서 공개 가중치 3개 다운로드 → 이 디렉토리 덮어쓰기" 순서입니다.

이 패키지에 들어있는 것 (여기서만 구할 수 있는 것)

immigration/
├── README.md                                                  ← 이 문서
├── results/Checkpoints/libero/20260826_133008+libero_sft_full_batch256/
│   ├── final_model/pytorch_model.pt                           6.7GB  SFT 가중치
│   ├── config.yaml                                            학습/추론 설정
│   └── dataset_statistics.json                                액션 역정규화 통계
└── latent_action_model/logs/dino_large_vae/lam_release/
    └── dino_large_vae.yaml                                    2KB   LAM 구조 설정 (아래 주의 참고)

dino_large_vae.yaml은 2KB짜리 설정 파일인데도 굳이 포함했습니다. LaWAM 공식 README가 경고하듯, Hub에서 받은 LAM YAML은 model.vision_model_id가 HF model id나 존재하지 않는 절대경로를 가리킬 수 있습니다. 이 패키지의 사본은 weights/dinov3-vitb16-pretrain-lvd1689m으로 맞춰진 검증된 버전이므로, Hub에서 받은 것 대신 이걸 쓰면 그 문제를 건너뛸 수 있습니다.

Hub에서 별도로 받아야 하는 것 (공개 가중치)

용량과 원본 재배포를 피하려고 제외했습니다. 2-3 단계에서 받습니다.

경로를 바꾸면 안 되는 이유

절대로 파일 위치를 임의로 바꾸지 마세요. 세 곳에서 경로가 하드코딩되어 있습니다.

1. starVLA/model/tools.py:232 — run_dir = checkpoint_pt.parents[1] 체크포인트 .pt 경로에서 두 단계 위를 run 디렉토리로 역산해서 config.yaml과 dataset_statistics.json을 찾습니다. 즉 <run_dir>/final_model/pytorch_model.pt 구조가 반드시 유지되어야 하고, .pt만 다른 곳으로 옮기면 assert에서 실패합니다.

2. config.yaml 안의 상대경로 — repo root(CWD) 기준으로 해석됩니다.

   framework.qwenvl.base_vlm:            results/Checkpoints/qwen3_weights
   framework.action_model.lam_ckpt_path:  latent_action_model/logs/dino_large_vae/lam_release/checkpoints/pytorch_model.pt
   framework.action_model.lam_yaml_path:  latent_action_model/logs/dino_large_vae/lam_release/dino_large_vae.yaml
   

3. dino_large_vae.yaml 안의 model.vision_model_id: weights/dinov3-vitb16-pretrain-lvd1689m — LAM 설정에 한 단계 중첩되어 숨어 있는 의존성입니다. 가장 놓치기 쉽습니다.

레이아웃을 바꾸고 싶다면 위 4개 경로 값을 직접 수정해야 합니다.

---

2. 설치

2-1. LaWAM repo clone

git clone https://github.com/RLinf/LaWAM.git LaWAM
cd LaWAM

# 이 패키지를 만든 시점의 커밋으로 맞추기 (권장)
git checkout 4ea6fdadce6c9b8746028307a246b79ee2c4fd55

원본 서버에는 학습 스크립트 쪽에 커밋되지 않은 수정이 몇 개 있었지만 (train_starvla.py, mixtures.py, train_libero.yaml 등), 모두 학습 경로 전용이라 벤치마크 실행에는 영향이 없습니다. clone 상태 그대로 벤치마크가 돌아갑니다.

2-2. 정책 실행 환경 (lawam)

conda create -n lawam python=3.10 -y
conda activate lawam

pip install -U pip
pip install -r requirements.txt
pip install flash-attn==2.8.3 --no-build-isolation
pip install -e .

flash-attn==2.8.3이 로컬 CUDA/PyTorch 빌드와 안 맞으면, 맞는 wheel을 수동으로 설치한 뒤 pip install -e .를 다시 실행하세요.

동작 확인:

python - <<'PY'
import torch, starVLA
print("torch", torch.__version__, "cuda", torch.version.cuda)
print("gpus", torch.cuda.device_count())
PY

2-3. Hub에서 공개 가중치 3개 다운로드

hf CLI가 필요합니다 (pip install -U huggingface_hub). 총 7.1GB.

cd /path/to/LaWAM

# 베이스 VLM (4.0GB)
hf download Qwen/Qwen3-VL-2B-Instruct \
  --local-dir results/Checkpoints/qwen3_weights

# LAM 비전 백본 (327MB)
hf download facebook/dinov3-vitb16-pretrain-lvd1689m \
  --local-dir weights/dinov3-vitb16-pretrain-lvd1689m

# LAM 체크포인트 (2.8GB)
hf download jialei02/lawam_lam \
  --local-dir latent_action_model/logs/dino_large_vae/lam_release

--local-dir 경로는 config.yaml과 LAM YAML에 기록된 값이라 정확히 그대로 써야 합니다.

2-4. 이 패키지의 파일 배치

repo root에서 이 디렉토리 내용을 덮어씁니다. (README.md는 제외)

cd /path/to/LaWAM

rsync -av --exclude='/README.md' /path/to/immigration/ ./

/README.md처럼 슬래시로 앵커링해야 repo root의 LaWAM README.md가 이 문서로 덮어써지지 않습니다.

순서가 중요합니다. 2-3(다운로드)을 먼저 하고 2-4(덮어쓰기)를 나중에 해야 합니다. 이 패키지의 dino_large_vae.yaml이 Hub에서 받은 것을 덮어써서, 위에서 설명한 vision_model_id 문제를 자동으로 해결합니다. 순서를 뒤집으면 Hub 버전이 남습니다.

배치 확인:

ls results/Checkpoints/qwen3_weights/model.safetensors
ls results/Checkpoints/libero/20260826_133008+libero_sft_full_batch256/final_model/pytorch_model.pt
ls results/Checkpoints/libero/20260826_133008+libero_sft_full_batch256/config.yaml
ls results/Checkpoints/libero/20260826_133008+libero_sft_full_batch256/dataset_statistics.json
ls latent_action_model/logs/dino_large_vae/lam_release/checkpoints/pytorch_model.pt
ls latent_action_model/logs/dino_large_vae/lam_release/dino_large_vae.yaml
ls weights/dinov3-vitb16-pretrain-lvd1689m/model.safetensors

7개가 모두 나와야 합니다. 추가로 LAM YAML이 로컬 DINOv3를 가리키는지 확인하세요:

grep vision_model_id latent_action_model/logs/dino_large_vae/lam_release/dino_large_vae.yaml
# 기대 출력:  vision_model_id: weights/dinov3-vitb16-pretrain-lvd1689m

다른 값이 나오면 (HF model id나 절대경로) 이 패키지의 dino_large_vae.yaml을 다시 덮어쓰거나, 해당 줄을 위 값으로 직접 수정하세요.

2-5. LIBERO 시뮬레이터 환경 (별도)

정책 서버와 시뮬레이터는 환경을 분리해서 씁니다.

git clone https://github.com/Lifelong-Robot-Learning/LIBERO.git ../LIBERO

conda create -n libero python=3.10 -y
conda activate libero
# LIBERO 공식 문서에 따라 설치한 뒤:
pip install mujoco==3.3.2

mujoco==3.3.2는 이 repo가 사용하는 버전이라 반드시 맞춰야 합니다.

---

3. 벤치마크 실행

cd /path/to/LaWAM
conda activate lawam

export CKPT_PATH=results/Checkpoints/libero/20260826_133008+libero_sft_full_batch256/final_model/pytorch_model.pt
export LIBERO_HOME=/path/to/LIBERO
export LIBERO_PYTHON=/path/to/miniconda3/envs/libero/bin/python
export STAR_VLA_PYTHON="$(which python)"

SUITES="libero_10 libero_goal libero_object libero_spatial" \
NUM_TRIALS_PER_TASK=50 \
NUM_WORKERS=4 \
GPU_IDS="0 1 2 3" \
OUTPUT_ROOT=results/eval_runs/libero \
LIBERO_CKPT_ALIAS=lawam_libero_sft_20260826 \
bash examples/LIBERO/eval_files/auto_eval_scripts/run_libero_benchmark.sh "$CKPT_PATH"

LIBERO_PYTHON과 STAR_VLA_PYTHON은 실행 가능한 python 바이너리 절대경로여야 합니다. 스크립트가 -x 체크를 하고 아니면 바로 종료합니다.

주요 환경변수

결과 위치

results/eval_runs/libero/<ckpt_alias>/<run_tag>/
  run_meta.json
  suites/<suite_name>/eval.log

먼저 스모크 테스트를 권장합니다

전체 4-suite × 50 trial은 오래 걸립니다. 배치가 제대로 됐는지부터 확인하세요.

SUITES="libero_10" NUM_TRIALS_PER_TASK=2 MAX_TASKS=2 NUM_WORKERS=2 GPU_IDS="0" \
bash examples/LIBERO/eval_files/auto_eval_scripts/run_libero_benchmark.sh "$CKPT_PATH"

---

4. 각 파일이 왜 필요한가

정책 서버는 다음 순서로 모델을 조립합니다.

deployment/model_server/server_policy.py:33   baseframework.from_pretrained(ckpt)
  └─ starVLA/model/tools.py:227                read_mode_config()
  │                                            → config.yaml + dataset_statistics.json
  └─ base_framework.py:177                     build_framework(cfg)
       └─ vlas/lawam.py:262                    _load_vlm_and_processor()
       │    └─ vlas/vlm_auto.py:108            AutoProcessor.from_pretrained(base_vlm)
       │    └─ vlas/vlm_auto.py:116+           Qwen3VL...from_pretrained(base_vlm)
       └─ vlas/lawam.py:267                    load_latent_action_model(lam_ckpt, lam_yaml)
            └─ lam_model.py:573                yaml → LatentLAMModel(**cfg)
            │    └─ vjepa_encoder.py:302       AutoModel.from_pretrained(dinov3)
            └─ lam_model.py:588                torch.load(lam_ckpt)
  └─ base_framework.py:204                     load_state_dict(SFT 가중치)   ← 마지막

핵심은 load_state_dict가 맨 마지막이라는 점입니다. SFT 체크포인트가 VLM/LAM/DINOv3 가중치를 전부 덮어쓰지만, 그 전에 모델을 "조립"해야 하고 조립 재료는 아래 4곳에 흩어져 있습니다. 즉 가중치가 덮어써질 파일들도 물리적으로 존재해야 합니다.

---

5. 이 패키지에 없는 것

Hub에서 받는 것 (필요하지만 여기 없음)

공개된 원본을 재배포하지 않으려고 제외했습니다. 2-3 단계에서 반드시 받아야 합니다.

아예 필요 없는 것

추가 SFT/재학습까지 하려는 경우에만 원본 서버에서 results/Checkpoints/pretrain/lawam_pretrain (stage2 체크포인트)과 dataset/lerobot (학습 데이터)을 별도로 받아야 합니다.

---

6. 트러블슈팅