rldx1-mt-multigroup-20260918

RLDX-1 multi-group mid-train → finetune 가이드

2026-09-18 multi-group mid-train 체크포인트에서 finetune 을 시작하는 사람/에이전트용 진입 문서다. mid-train 이 어떻게 이루어졌는지(그룹·데이터·action 타깃·토크나이저·cog loss)와, 그 위에서 finetune 을 어떻게 해야 하는지를 적는다. 문서는 요약이다. 숫자·규약은 반드시 아래 표의 코드와 contract 파일을 직접 열어 확인한다(§0).

• GitHub: https://github.com/jungwook235/RLDX-1-egopi
  • feat/multigroup-finetune ← finetune 은 이 브랜치로 한다 (이 문서, finetune 런처, 코드 패치 §6)
  • feat/multigroup-midtrain-20260918 @ 9295a11 ← mid-train 을 실제로 돌린 코드(기록용, 손대지 않음)
• 로컬: ~/HERIT/mt_multigroup/RLDX-1-egopi-finetune (finetune 브랜치 worktree), ~/HERIT/mt_multigroup/RLDX-1-egopi (mid-train 브랜치; mid-train 잡이 이 트리의 코드를 import 중이므로 수정 금지)
• 런 루트 $ROOT = /rlwrld-unified-checkpoints/jungwook/rldx1/mt_multigroup_20260918

0. 에이전트에게 — 무엇을 어떤 순서로 읽는가

체크포인트의 config.json 에 있는 mt_groups_record 에도 그룹별 tag·슬롯·전처리·데이터셋·토크나이저 contract 전문·cogalign 설정이 들어 있다. 레포 없이 체크포인트만 받았을 때는 이것이 1차 자료다.

에이전트 지시문 예시:

https://github.com/jungwook235/RLDX-1-egopi 의 feat/multigroup-finetune 브랜치에서 docs/mt_multigroup_finetune_guide.md 를 먼저 읽고, §0 표의 파일을 순서대로 코드까지 직접 열어 확인해라. 그 다음 내 데이터가 §4(openarm, tag 재사용 + 같은 토크나이저)인지 §5(새 그룹, tag 추가)인지 판단해서 groups JSON 과 필요한 캐시를 만들고, run_scripts/train/mt_multigroup/mt_multigroup_finetune.sbatch 를 SMOKE_ONLY=1 로 먼저 통과시켜라. action 전처리는 그룹마다 다르니 문서의 요약을 믿지 말고 contract JSON 과 modality config 로 대조해라.

1. mid-train 은 어떻게 이루어졌나

• 베이스 RLDX-1-PT-IMG(Qwen3-VL 기반 VTC 백본, embodiment 행 36개) → 행 5개를 from scratch 로 추가(36→41, --extra-embodiment-slots 5), 기존 722개 텐서는 bit-exact 로드 검증.
• 그룹 = embodiment tag = 전용 행: state encoder / action encoder / action decoder 의 CategorySpecificMLP 행 + 전용 modality config + 전용 정규화 통계. 백본·DiT·cog 토큰·cog adapter 는 전 그룹 공유.
• flow-matching 타깃은 그룹마다 다르다: 토크나이저 latent z [16,64](A, B) 또는 정규화된 native action(C, D, E). 한 배치 안에 섞인다(actlat_mixed, 샘플 단위 라우팅).
• 보조 loss CogAlign: cog 토큰 → residual cog adapter → 공유 48D linear head 가 현재 프레임의 FP48(손끝+손목 기하)을 맞춘다. weight 0.2, smooth-L1, detach 0.
• 샘플링은 naive(데이터셋 가중치 = 로더가 실제로 내는 프레임 수). 그룹 weight 없음.

학습 설정(job 196537, 2×H100): 글로벌 배치 128(GPU당 64, accum 1; groups JSON 의 training_overrides 로 고정), 200k step, save 10k, lr 1e-4 constant(warmup 없음), weight decay 1e-5, LLM 상위 4층(14~17)만 tune + projector + diffusion model(tune_llm=False, tune_visual=False), n_cog_tokens 64, action_horizon 16, video_length 1, state dropout 0.3, color jitter 0.6/0.6/0.6/0.16, physics_loss_weight 0.1, workers 12, data seed 42, --override-pretraining-statistics, --dataset-mode standard. cog adapter hid 256 / SiLU. (런 기록 문서의 "4 GPU" 는 계획 당시 값이다. 실제로는 같은 sbatch 를 NUM_GPUS=2 GLOBAL_BATCH_SIZE=128 로 돌렸다.)

2. 토크나이저 — finetune 에서 같은 것을 써야 하는 이유와 그 정체

토크나이저 그룹의 행(action encoder/decoder)은 z 공간에서 학습됐다. 그 행을 재사용하는 finetune 은 같은 토크나이저의 z 를 타깃으로 써야 하고, z 를 만들 때 쓰는 정규화 숫자(min/max)도 토크나이저 학습 때의 것 그대로여야 한다. 새 데이터로 통계를 다시 계산하면 같은 action 이 다른 z 가 된다. 배포 시에도 정책 출력 z → 이 토크나이저의 robot 디코더 → 역정규화 → 15D action 순서로 풀어야 한다.

2.1 공통 학습 세팅 (두 토크나이저 동일)

action-only(DINO 스트림 없음), 입력 = action chunk [16, D], latent = [16, 64](token_dim 64), encoder/decoder depth 4, decoder self-attention, VAE(KL 1e-6; z-cache 는 posterior mean, vae_sample=False), recon L1, 인코더 공유 + recon 디코더 robot / human 2개(human 은 robot 에서 copy-init), robot↔human VICReg 정렬(weight 0.03, pool=tokens, gather, var 1.0 / std 1.75 / cov 0.004), 2 GPU × 256 = 글로벌 512, 100k step, lr 5e-5 constant, 소스 weight 없음(프레임 비례).

2.2 openarm 15D 토크나이저 (r6h5) — openarm finetune 이 쓰는 것

human 매핑 상수(rldx/data/egopi/prq_mapping.py 와 contract 가 일치해야 verify 통과): EGOPI_HEAD_PITCH 1.2, EGOPI_HEAD_YAW −0.3, P_OFFSET [0.116, 0.117, −0.017], R_CONV(3×3), P_SCALE/Q_SCALE = 1, Q_DELTA = 0. chunking: 행 t..t+15, 에피소드 끝에서는 마지막 행 반복.

2.3 ALLEX 50D 토크나이저 (참고 — ALLEX finetune 은 이번 범위 밖)

semantics allex-abs-eef50-leftfirst-rot6drows-v1, 코드 jungwook235/action-tokenizer master a9fb113, 런처 tokenizer_side/allex_eef50/allex_tokenizer_robot_human_100k.sbatch, 정규화 q99 clamp(2(x−q01)/(q99−q01)−1, −1, 1)(세 소스 합친 통계, sha 65dc3f16dcec), val 0.03, job 194443. 산출물 /rlwrld-unified-checkpoints/jungwook/action_tokenizer/checkpoints_action_tokenizer/allex_eef50_robot_hmd_umi_q99_split_w0p03_actiononly_bs512_h16_100k/, 번들 $ROOT/allex_eef50/tokenizer_bundle/.

2.4 일치 보장 장치

• 토크나이저 런은 체크포인트 옆에 action_preproc_contract.json 을 쓴다(키·순서·레이아웃, 절대/상대, 프레임·rot6d 규약, horizon/fps, 정규화 식과 차원별 숫자, 통계 sha, 소스와 해시, 코드 커밋).
• z-cache 는 토크나이저 자신의 학습 데이터셋 클래스를 재생해서 만든다 → 필터·사람 변환·정규화가 구조적으로 동일.
• RLDX 는 시작할 때 그룹의 tokenizer.verify 명령을 실행하고, 실패하면 학습에 들어가지 않는다.

3. 체크포인트

• 위치: $ROOT/train_top4_2gpu_b128_200k/mt_multigroup_A50z_B15z_C30_D30v2_E30_top4_constlr_2gpu_b128_200000/checkpoint-<step>/ (10k 간격; 이 문서 작성 시점 100k 까지. finetune 은 checkpoint-100000 에서 시작한다 (HF 에는 checkpoint-100000 과 이전 checkpoint-90000). 런은 200k 목표로 진행 중. 2일 제한에 걸리면 ALLOW_RESUME=1 로 이어서 돌린다.)
• finetune 에 필요한 것: config.json, model-0000{1,2,3}-of-00003.safetensors(≈14 GB), model.safetensors.index.json, experiment_cfg/, processor/. global_step*/(DeepSpeed optimizer, ≈48 GB)는 resume 전용이라 필요 없다.
• config.json: max_num_embodiments 41, base_num_embodiments 36, extra_embodiment_slots 5, actlat_mixed true, cog_adapter_activation silu, mt_groups_record {...}.
• HF(public): 체크포인트 jungwook2358/rldx1-mt-multigroup-20260918, 토크나이저 jungwook2358/action-tokenizer-openarm-prq15-r6h5 — §8.

4. finetune 경우 1 — openarm (tag 재사용, 같은 토크나이저)

대상: mid-train 의 B 그룹과 같은 action 표현(오른손 15D {p,r,q})으로 만들 수 있는 openarm 데이터.

규칙

1. tag 는 mt_openarm_prq15(슬롯 37) 그대로. 행을 추가하지 않는다 → --extra-embodiment-slots 를 주지 않는다(CASE=openarm, EXTRA_SLOTS=0).
2. flow 타깃은 같은 15D 토크나이저의 z. groups JSON 의 tokenizer 블록(contract·bundle·verify)은 mid-train 것을 그대로 복사한다.
3. action 전처리는 §1 표 B 와 contract 그대로: robot 은 FK(명령 관절) → ZED 프레임(고정 head) → rot6d 열 → action[22:28] 의 Inspire q6, 20 Hz(원본이 30 Hz 면 nearest 로 20 Hz), h16. 사본 구현: tokenizer_side/openarm_prq15/build_egopi15_extra_robot.py(28D 정리 + PointsFK FK 캐시, v3 캐시 재현 오차 0), …_videos.py(같은 프레임만 뽑아 20 fps 재인코딩).
4. 정규화 숫자를 다시 계산하지 않는다. z-cache 는 토크나이저의 frozen egopi_prq_stats.json(sha 44eac480a54f…)으로 만들고, RLDX state 정규화도 같은 파일을 쓴다(dataset entry 의 egopi_stats_path). scripts/build_egopi_prq_stats.py 를 새 데이터에 돌리지 말 것. 새 데이터가 기존 min/max 밖으로 나가면 clip(−1,1) 로 잘린다 → z-cache 를 만들 때 차원별 clip 비율을 찍어 보고, 크면 그건 "같은 토크나이저로 finetune" 이 아니라 토크나이저 재학습 사안이다.
5. cog loss: mid-train 과 같은 설정으로 켠다(groups JSON 의 cogalign 블록, weight 0.2 / dim 48 / linear / adapter_hid 256 / detach 0). 타깃은 scripts/mt_multigroup/build_prq15_fp48_cache.py 로 만든 오른손 FP24 → FP48 오른쪽 절반, 왼쪽 mask 0. cogalign.enabled=true 면 모든 dataset 에 READY 인 latal_cache 가 있어야 한다. cog loss 없이 하려면 블록을 빼면 된다(그래도 런처가 cog adapter 는 켠다 — §7-1).
6. 카메라는 camera_ego_right 1대, 언어는 annotation.human.task_description.

순서

FT=<finetune 루트>;  TOK=/rlwrld-unified-checkpoints/jungwook/action_tokenizer/openarm_prq15_r6h5
# (1) 데이터를 B 그룹 형식으로: 28D + FK 캐시 + 20 Hz + keep-list(filter JSON)
python scripts/mt_multigroup/tokenizer_side/openarm_prq15/build_egopi15_extra_robot.py --out $FT ...        # 코드를 읽고 소스에 맞게
python scripts/mt_multigroup/tokenizer_side/openarm_prq15/build_egopi15_extra_robot_videos.py --out $FT
# (2) 새 소스만 나열한 embodiments.runtime.json 을 만든다. prq_stats 는 $TOK/input_artifacts/egopi_prq_stats.json 을 가리키게(재계산 X).
# (3) frozen 토크나이저로 z-cache
python scripts/mt_multigroup/tokenizer_side/openarm_prq15/build_prq15_actlat_cache.py \
    --tokenizer-repo ~/HERIT/action-tokenizer --builder-repo ~/HERIT/allex_eef/action-tokenizer \
    --pt $TOK/checkpoints_action_tokenizer/openarm_prq15_r6h5_actiononly_w0p03_splitdec_g2_100k/multiemb_full.pt \
    --runtime-config $FT/embodiments.runtime.json --bundle-out $FT/tokenizer_bundle --cache-root $FT/actlat_cache
#     -> $FT/tokenizer_bundle/model.safetensors 의 sha256 이 mid-train 번들(8914f284…)과 같은지 확인
# (4) cog loss 타깃
python -m scripts.mt_multigroup.build_prq15_fp48_cache --groups-config $FT/mt_groups_finetune.json --out $FT/fp48_cache
# (5) groups JSON: docs/mt_multigroup_finetune_groups_openarm_example.json 의 <...> 를 채운다
# (6) 스모크 -> 학습
CASE=openarm BASE_MODEL_PATH=<…/checkpoint-100000> GROUPS_JSON=$FT/mt_groups_finetune.json MODEL_OUTPUT_DIR=<out> SMOKE_ONLY=1 \
    bash run_scripts/train/mt_multigroup/mt_multigroup_finetune.sbatch

스모크가 확인하는 것: contract verify OK, tag=mt_openarm_prq15 slot=37 target=actlat, [ACTLAT-MIXED] ON, [COG-ADAPTER] … ON, shape mismatch 로 버려진 텐서 없음.

human 데이터도 같이 넣는 경우: egopi_source: "human", legacy affine 이면 task_filter, retargeted 면 egopi_retargeted_human: true + egopi_retarget_head_calib_path + retargeted human stats (형태는 docs/mt_multigroup_groups_example.json 의 B 그룹 human entry 참고). robot/human 은 같은 tag·같은 슬롯을 쓴다.

5. finetune 경우 2 — 새 그룹 (tag 추가)

대상: openarm 15D 가 아닌 모든 것(다른 로봇, 다른 action 표현, 시뮬레이터 …). 기존 그룹의 행을 빌려 쓰지 않는다. 행은 (state dim, action dim, 정규화, 의미)가 그 그룹에 맞춰 학습된 것이라 다른 embodiment 를 얹으면 그 행을 망가뜨릴 뿐 얻는 게 없다. 공유되는 것은 백본·DiT·cog adapter 다.

규칙

1. 새 tag + 새 슬롯을 추가한다.
   • rldx/data/embodiment_tags.py 의 EmbodimentTag 에 항목 추가, rldx/model/core/processing_rldx.py 의 EMBODIMENT_TAG_TO_PROJECTOR_INDEX 에 "<tag>": <slot> 추가.
   • 슬롯 번호: 36~40 = mid-train 그룹, 새 그룹은 그 다음 행인 41 에 추가한다(finetune 은 모델마다 따로 돌리므로 각자 41 을 쓴다). 한 런 안에서 두 그룹이 한 슬롯을 쓰면 mt_groups.py 가 거부한다.
2. --extra-embodiment-slots 1(체크포인트가 41행이므로 슬롯 41 = 행 1개 추가). 런처에서는 CASE=newgroup(기본 EXTRA_SLOTS=1). 체크포인트의 41행 전부(사전학습 36 + mid-train 5)가 [:41] 에 복사되고 bit-exact 검증된다([EMB-EXPAND] … grown 41 -> 42 rows, VERIFIED). 새 행은 from scratch(0.02·randn, bias 0). (mid-train 브랜치 코드는 이미 확장된 체크포인트에 이 플래그를 주면 에러로 막는다 → §6 패치가 필요한 이유.)
3. modality config 는 레포 밖 파일로 만들어 --modality-config-path(런처의 MODALITY_CONFIG)로 넘긴다. 키·순서, ABSOLUTE/RELATIVE, EEF 여부, horizon 16, 카메라를 여기서 정의한다. 동작하는 실례: ~/HERIT/dexverse_rldx/dexverse_modality_config.py + dexverse_v0_bimanual_groups.json + train_dexverse_v0_bimanual_base.sbatch(이쪽은 PT-IMG 에서 시작하는 버전).
4. flow 타깃은 둘 중 하나.
   • native("target": "native", 기본): 그 그룹 데이터셋의 meta/stats.json q01/q99 로 RLDX 가 정규화. RLDX_PRQ30_STRICT 는 unset(런처가 처리). action dim ≤ 64(max_action_dim).
   • 자체 토크나이저("target": "actlat"): §2.1 세팅으로 그 embodiment 의 토크나이저를 새로 학습하고(기존 15D/50D 토크나이저를 다른 action 공간에 쓰지 말 것), action_preproc_contract.json + verify 명령 + z-cache([L,16,64], READY)를 갖춘다. tokenizer.verify 가 없으면 mt_groups.py 가 거부한다.
5. cog loss 는 선택. 쓰려면 그 그룹의 현재 프레임 FP48([left24|right24], 손마다 [손끝 5개 wrist-local 15 | wrist pos 3 | rot6d 열 6], format fp48_only_v1, 없는 손은 dim mask 0)을 만들어 latal_cache 로 건다. 손이 없는/손끝이 정의되지 않는 embodiment 면 cogalign 블록을 빼고 native loss 만으로 간다.
6. 통계: --override-pretraining-statistics 로 그룹 자신의 통계를 쓴다(런처 기본).

순서: tag/슬롯 추가 → modality config → (LeRobot 변환, meta/stats.json) → groups JSON(docs/mt_multigroup_finetune_groups_newgroup_example.json) → CASE=newgroup MODALITY_CONFIG=<py> … SMOKE_ONLY=1 bash …/mt_multigroup_finetune.sbatch → 본 학습. 스모크가 확인하는 것: [EMB-EXPAND] VERIFIED, grown 41 -> 41+N rows, [COG-ADAPTER] … ON, shape mismatch 없음.

openarm 데이터와 새 그룹을 한 런에 같이 넣는 것도 된다: groups JSON 에 두 그룹을 다 적고 CASE=newgroup 으로 돌린다(openarm 그룹은 슬롯 37 재사용, 새 그룹만 행 추가).

6. 이 브랜치가 mid-train 브랜치(9295a11)와 다른 점

검증한 것: _expand_embodiment_rows 41→42 CPU 단위 확인(앞 41행 bit-exact, 새 행 std≈0.02, base 를 36 으로 잘못 주면 거부), _checkpoint_rows(PT-IMG 36 / 확장 체크포인트 41). 아직 안 한 것: mid-train 체크포인트로 실제 GPU 스모크. 첫 사용 시 SMOKE_ONLY=1 을 반드시 먼저 통과시킬 것.

7. 함정

1. cog adapter 는 env 로만 만들어진다(RLDX_COG_ADAPTER=1, _HID=256, _ACT=silu). mid-train 에서 학습된 residual 로 DiT 가 읽는 cog 를 바꾼다. cogalign 블록 없이, env 도 없이 finetune 하면 adapter 가중치가 조용히 버려지고 DiT 는 학습 때와 다른 cog 분포를 본다. finetune 런처는 항상 켠다. 배포/추론 서버에서도 같은 env 가 필요하다.
2. --actlat-mode(전체 latent, 단일 토크나이저)는 이 체크포인트와 같이 쓸 수 없다(config 의 actlat_mixed=true 와 배타). 토크나이저 그룹도 --mt-groups-config 경로로만.
3. B 그룹 재사용 시 min/max 재계산 금지(§4-4). contract verify 는 파일 sha 를 보므로 다른 stats 를 주면 시작에서 막힌다 — 막혔다고 contract 를 고치지 말 것.
4. rot6d 규약이 그룹마다 다르다: ALLEX = 회전행렬 앞 두 행, openarm 15D / PRQ30 / FP48 = 앞 두 열.
5. fps 가 다르다: ALLEX 30 Hz, 나머지 20 Hz. h16 은 각각 0.53 s / 0.8 s.
6. teleop_v3 원본은 meta/relative_stats.json 읽기 권한이 없다 → $ROOT/openarm_prq15/dataset_views/<tag>(symlink view)를 데이터 경로로 쓴다.
7. 글로벌 배치: 80 GB GPU 에서 GPU당 64 는 mid-train 5그룹 구성에서 OOM 직전이었다(피크 71.8 GB @ 32). groups JSON 의 training_overrides.global_batch_size 가 CLI 를 덮어쓴다.
8. DeepSpeed 0.17.6 + ZeRO-2 + multi-GPU + accum>1 은 DeepSpeed #7718 에 걸린다 → accum 1 고정.
9. latent 그룹 배포에는 정책 뒤에 해당 토크나이저의 robot 디코더 + 역정규화가 필요하다(tokenizer_config.json 의 note: loader.py 포팅 필요).

8. HF 업로드 (public)

hf repo create jungwook2358/action-tokenizer-openarm-prq15-r6h5 --repo-type model
hf upload jungwook2358/action-tokenizer-openarm-prq15-r6h5 $ROOT/openarm_prq15/tokenizer_bundle bundle
hf upload jungwook2358/action-tokenizer-openarm-prq15-r6h5 $TOK/checkpoints_action_tokenizer/openarm_prq15_r6h5_actiononly_w0p03_splitdec_g2_100k/action_preproc_contract.json train/action_preproc_contract.json
hf upload jungwook2358/action-tokenizer-openarm-prq15-r6h5 $TOK/checkpoints_action_tokenizer/openarm_prq15_r6h5_actiononly_w0p03_splitdec_g2_100k/multiemb_full.pt train/multiemb_full.pt
hf upload jungwook2358/action-tokenizer-openarm-prq15-r6h5 $TOK/input_artifacts train/input_artifacts

hf repo create jungwook2358/rldx1-mt-multigroup-20260918 --repo-type model
hf upload jungwook2358/rldx1-mt-multigroup-20260918 <run dir>/checkpoint-100000 checkpoint-100000 \
    --include "config.json" --include "model-*.safetensors" --include "model.safetensors.index.json" --include "experiment_cfg/*" --include "processor/*"

받는 쪽: hf download <repo> --local-dir <dir> (체크포인트 레포는 --include "checkpoint-100000/*" 로 100k 만 받으면 된다) 후 BASE_MODEL_PATH=<dir>/checkpoint-100000. groups JSON 의 tokenizer.contract / bundle / --prq-stats 경로를 받은 위치로 바꾼다(sha 는 그대로여야 verify 통과).