code/SPATIAL_RUN_README.md

SpatialDiffuseSlot — 새 서버에서 돌리는 법 (2026-07-15 완성, GPU batch-1 검증됨)

무엇: Semanticist DiT-L/ViT (tok_L pretrained init) + 우리 85 multi-res attn-pool 토큰 + 우리 spatial-align attention mask. DiT trunk freeze로 warmup(Phase-1) 후 unfreeze(Phase-2). 설계 배경/비교분석: new_eval_spatial_reasoning0430/_worklog/SEMANTICIST_DIT_SPATIAL_SETUP.md, OURS_VS_SEMANTICIST.md.

파일 (전부 semanticist repo 안)

파일	역할
semanticist/stage1/spatial_diffuse_slot.py	본체: SpatialAttnPool(85토큰) + DiTSpatial(mask 플러밍+CFG) + SpatialDiffuseSlot(tok_L init/freeze)
spatial_mask.py	xa_mask→(149×149) self-attn mask (유닛테스트 내장: python spatial_mask.py)
configs/tokenizer_l_spatial.yaml	launch config (Phase-1: freeze_dit, warmup 100ep, batch eff 256)
train_spatial_l.sh	launch: GPUS=0,1,2,3 bash train_spatial_l.sh
smoke_full_spatial.py	CPU 통합 smoke (init/fwd/bwd/freeze)
smoke_gpu_batch1.py	GPU batch-1 pre-flight (3 optimizer steps) — 새 서버에서 launch 전 이것부터
viz_mask_compare.py / mask_compare.png	mask 시각화 (level별 토큰→담당부위 검증)
test_net.py (수정)	SEM_STEPS=50 env로 eval sampling step override
fid_L85_50step.py	tok_L@85@50step rFID 재계산 (recon 재활용)

새 서버 사전 준비 (순서대로)

1. venv: torch/accelerate/omegaconf/timm/diffusers/torch_fidelity (기존 MNIST_debug venv 사양).
2. weights: semanticist_tok_L.pkl(2.2GB) — ⚠️ 7/13 번들 eval_assets.tar에 없음(7/15 다운로드). delta rsync 또는 HF서 재다운: huggingface.co/tennant/semanticist/resolve/main/semanticist_tok_L.pkl → config의 init_from: 경로를 새 위치로 수정.
3. DINOv2 (REPA): TORCH_HOME에 dinov2_vitb14 캐시 (없으면 torch.hub가 자동 다운로드 — 오프라인이면 기존 torch_cache 복사).
4. dataset 심볼릭 (semanticist repo 루트에서):

   mkdir -p dataset/imagenet
   ln -sfn <ImageNet>/train dataset/imagenet/train         # 1000-class ImageFolder
   ln -sfn <balanced val 50k centercrop dir> dataset/imagenet/val/all   # flat pngs (val 아래 1클래스)
   ln -sfn <같은 dir> dataset/imagenet/val256               # trainer eval real_dir 하드코딩용
   

   (val = 우리 eval_assets/val_real50k_centercrop. adm_in256_stats.npz는 repo fid_stats/에 이미 있음.)

실행

# 0) 검증 (필수, 순서대로 — 전부 PASS 후 launch)
python spatial_mask.py                 # mask 유닛테스트
CUDA_VISIBLE_DEVICES="" python smoke_full_spatial.py    # CPU 통합
CUDA_VISIBLE_DEVICES=0 python smoke_gpu_batch1.py       # GPU batch-1 (mem ~5.5GiB)

# 1) Phase-1 launch (DiT trunk frozen, encoder/pool/cond 학습)
GPUS=0,1,2,3 bash train_spatial_l.sh   # detach는 setsid nohup ... & disown

# 2) Phase-2 (Phase-1 수렴 후): configs/tokenizer_l_spatial.yaml에서
#    freeze_dit: false + dit_lr_scale: 0.1 + ckpt_path: output/tokenizer/models_l_spatial/models/step<N>
#    (+ blr 낮추기 권장) 후 재launch.

검증된 수치 (이 서버, 2026-07-15)

• tok_L init: encoder 151/151, DiT trunk 전부 로드, drop=[null_cond(256→85 fresh)]
• trainable 134.8M / total 752.7M (frozen trunk)
• batch1 bf16: 5.5GiB, ~0.1s/step (1GPU) | mask routing 국소화 확인(perturb 실험 37×)
• 데이터: train 1,281,103 / test 50,000

잡아둔 버그 (재발 주의)

1. load_state_dict(strict=False)도 shape mismatch는 에러 → init_from 로더가 mismatch 키 자동 drop (null_cond).
2. encoder는 num_slots=256 유지해야 tok_L 100% 로드 (slot은 안 씀, patch만 사용 — patch는 slot을 안 봐서 오염 없음).
3. Semanticist DiT.forward는 mask를 블록에 안 넘김 → DiTSpatial이 플러밍 (forward/forward_with_cfg 둘 다).
4. mask 규칙: latent→latent full / latent→cond xa / cond→latent 차단 / cond→cond identity (all-False row = SDPA NaN 방지).
5. DiT out은 learn_sigma라 2×in_channels (loss에서 분리, diffusion lib가 처리).
6. trainer가 model.params.ckpt_path를 무조건 읽음 → config에 ckpt_path: null 필요 (init은 init_from).
7. eval 경로: trainer가 model.num_slots로 test_num_slots/drop_mask를 사이징 → 256이면 85 cond와 충돌(5000-iter eval crash). SpatialDiffuseSlot이 self.num_slots=85 재지정 + NestedSampler(85) 재생성으로 해결 (encoder 내부 num_slots=256은 유지되어 ckpt 로드 무관).