v8 VQ Methodology Rescue Design¶
0. 배경¶
v7 단계 0.5 smoke (9 runs) + 진단 4 cells (A1/A2/A4/V1~V3) 결과:
| Cell | Components | PAPE | HR | rel_decrease |
|---|---|---|---|---|
| B0 Local | — | 52.3 | 0.68 | +0.018~0.030 |
| A1 (peak + DLinear, no VQ) | ✓ + ✓ | 47.1 ⭐ | 0.68 | +0.004 |
| A2 (no peak) | VQ + DLinear | 56.2 | 0.52 | −0.016 |
| A3 full | peak + VQ + DLinear | 54.3~55.6 | 0.51 | −0.013~−0.019 |
| A4 (no DLinear) | peak + VQ | 57.9 | 0.54 | −0.013 |
| V1 (+EMA) | A3 + EMA γ=0.95 | 53.9 | 0.52 | −0.019 |
| V2 (+K-means) | A3 + K-means warmup | 54.2 | 0.52 | −0.019 |
| V3 (EMA+K-means) | A3 + 둘 | 53.4 | 0.52 | −0.013 |
v6 R1b 동일 구조 원본: PAPE 38.40 (exp-expert memory exp6_fedpm_results_snapshot.md)
원인: src/fed_learning/fedpm.py 의 MemoryAlignmentServer (line 350) + RESET 기법이 v7_runner 에 미통합. FedPM 논문 ablation 시 해당 2 기법 누락이 7~9% MAE 악화 유발.
1. 목표 (pre-registered)¶
1a. Primary¶
V4 또는 V5 cell 이 PAPE < 50 달성 (A1 47.1 이하 초과, baseline 52 보다 개선). 동시에 rel_decrease ≥ 0 (수렴 방향).
1b. Stretch¶
V4 또는 V5 PAPE ≤ 45, v6 R1b 38.40 에 근접 (±5 tolerance).
1c. Rollback (primary 실패 시)¶
파라미터 튜닝 금지. VQ 방법론 재설계: - (a) Gumbel-softmax VQ — soft relaxation - (b) Product Quantization — codebook 분해 - (c) RQ-VAE — Residual quantization - (d) VQ 대체 — shared linear adapter / low-rank projection
exp-expert 가 원인 분석 후 옵션 선정 → 새 cycle.
2. v7 계승 (변경 없음)¶
- 단계 0 사전 등록 (Golden tensor G1~G5, definition_hash=
8be2bd2f691deed0, Apt_max_load=Apt88) - Fail-fast threshold (val ratio > 1.5, train > 3.0)
- 데이터 split (v6 시계열 순서 계승, Tin=96, Tout=24)
- 5-seed set {42, 123, 456, 789, 2024}
- 공용 모듈
src/peak_analysis/v7/metrics.py(compute_pape_v7,compute_hr_v7,definition_hash()) - v7_runner CLI (mode, phase, cells, seeds, households flags)
- smoke_analysis 6 Gates + rel_decrease (v6 P10=0.0017 empirical cutoff)
- MLflow 로깅 의무 (per-epoch loss, best ckpt, y_true/pred artifact, 가구별 PAPE/HR/MSE/MAE, 7-metric fail-fast)
- 155+ test suite
3. v8 신규 사항¶
3.1 CELL_REGISTRY 확장¶
| ID | peak_loss | use_vq | use_dlinear | vq_init | vq_update | vq_alignment | vq_reset |
|---|---|---|---|---|---|---|---|
| V1 (기존) | ✓ | ✓ | ✓ | random | EMA γ=0.95 | ✗ | ✗ |
| V2 (기존) | ✓ | ✓ | ✓ | K-means warmup=5 | gradient | ✗ | ✗ |
| V3 (기존) | ✓ | ✓ | ✓ | K-means warmup=5 | EMA γ=0.95 | ✗ | ✗ |
| V4 (신규) | ✓ | ✓ | ✓ | random | gradient | ✓ | ✗ |
| V5 (신규) | ✓ | ✓ | ✓ | random | gradient | ✓ | ✓ |
선택 이유: V4 는 MemoryAlignmentServer 단독 효과 분리, V5 는 RESET 추가 기여 분리. 기존 V1/V2/V3 는 backward-compat 로 실험 재비교 가능.
3.2 MemoryAlignmentServer 통합¶
기법 (FedPM §3.2): 각 round 끝에 모든 client codebook concat → cosine similarity matrix → BFS connected components → 상위 γ 비율은 공유 prototype 으로 할당, 나머지는 personal 유지. 각 client 는 aligned codebook 반환.
파라미터: memory_size=256, shared_ratio=0.95, sim_threshold=0.6 (FedPM default 동일).
MLflow 로깅 (per-round):
- codebook_alignment_sim_mean: client codebook 간 평균 cosine similarity
- codebook_n_components: BFS 연결 컴포넌트 수 (낮을수록 codebook 간 통일성 ↑)
3.3 RESET mechanism (SoundStream §III-C)¶
기법: batch 별 codebook entry 사용 여부 추적. dead_threshold=2 batch 연속 미사용 entry → 현 batch 의 random encoder output embedding 으로 교체. codebook collapse 방지.
구현: v7_runner.py 내 VectorQuantizerWithReset(VectorQuantizer) subclass (v6 파일 수정 금지 원칙). spec.vq_reset=True cell 에서만 사용.
4. 실험 단계¶
단계 V8.1 — 1-seed 검증 smoke (D+0, ~5분)¶
uv run python -m experiments.federated.v7_runner \
--mode=main --phase=vq_improvement \
--cells=V4,V5 --seeds=42 --households=Apt6,Apt88 --golden-tensor-check
판정: | V4 PAPE | V5 PAPE | 의미 | 행동 | |---|---|---|---| | < 50 | < V4 | RESET 효과 확인 | V5 = "full proposed", 단계 V8.2 진입 | | < 50 | ≥ V4 | Alignment 단독 충분 | V4 = "full proposed", 단계 V8.2 진입 | | ≥ 50 | ≥ 50 | 2 기법 조합 부족 | 파라미터 튜닝 금지, VQ 재설계 단계 |
단계 V8.2 — 5-seed 통계 (D+1, ~1.5h)¶
V4 또는 V5 (위 판정) × seeds {42, 123, 456, 789, 2024} × Apt6/Apt88 2-가구. 결과: 평균 ± std, paired Wilcoxon vs A1/B0.
통과 기준: PAPE 평균 ≤ A1 (47.1), rel_decrease ≥ 0 on ≥ 4/5 seeds.
단계 V8.3 — 단계 1 재진입 (D+1~2)¶
기존 v7 TODO Task #5 (Baseline 25 runs) + "full proposed" (V4 or V5) 5-seed 재실행. Paired 구조로 claim C2~C6 검증.
5. 실패 경로 (user 지정 프로토콜)¶
단계 V8.1 에서 V4/V5 모두 PAPE ≥ 50 이면:
- 엔지니어 dispatch 금지 (파라미터 튜닝 방지)
- exp-expert cycle 1 호출:
- V4 alignment_sim_mean 시계열 분석 (codebook이 수렴하는지)
- V5 dead_replacement 빈도 분석
- v6 R1b 학습 로그 재확인 (동일 구조에서 실제로 무엇이 달랐는지)
- 4 옵션 (Gumbel / PQ / RQ-VAE / adapter) 중 선정
- critic review (cycle 1/2)
- 선정 옵션으로 v9 phase 개시 (새 ADR)
6. Workload¶
| 단계 | 시간 |
|---|---|
| 문서 작성 (orchestrator 병렬) | 0.5h |
| engineer 구현 (MemoryAlignmentServer + RESET + 테스트) | 2~4h |
| V8.1 1-seed smoke | 5분 |
| V8.2 5-seed (V4 또는 V5, 10 runs) | 1.5h |
| V8.3 단계 1 재진입 (25+10 runs) | 3.5h |
| v8 소계 | ~7~9h |
| 실패 경로 추가 (옵션 4 중 하나 구현) | +8~16h |
v7 남은 workload (단계 2 ablation + 단계 5 통계 + 단계 6 TSFM + 발표자료) 는 v8 단계 V8.3 완료 후 진행.
7. 성공 지표 (pre-registered)¶
- V4/V5 중 최소 하나 PAPE < 50 (1-seed 단계 V8.1)
- 5-seed 평균 PAPE ≤ A1 (47.1) with std < 3.0 (단계 V8.2)
- rel_decrease ≥ 0 on ≥ 4/5 seeds (단계 V8.2)
- codebook_alignment_sim_mean 증가 추세 (round 진행에 따라) 관찰
8. track-e v3 와의 관계¶
track-e v3 (2026-04-19 superseded) 의 Tier 1a/1b/2 실험 계획 중 v8 은 다음을 실질 실행: - Tier 1a (미실시): EMA/K-means/EMA+K-means → v7 V1/V2/V3 에 이미 scaffold, 별도 5-seed 실행은 옵션 - Tier 1b (미실시): RESET + EMA+RESET + KMEANS+RESET → v8 V5 + 추가 조합 가능 - 미명시: MemoryAlignmentServer 자체 통합 (track-e 에도 없었음, v8 신규 기여)
docs/reference/project_state/track_e_vq_codebook_research.md status: superseded → partially-adopted-into-v8.
연계 문서¶
- ADR:
docs/decisions/ADR-008_v7_to_v8.md - TODO:
todos/track-v8_vq_rescue.md - v7 design:
docs/reference/project_state/track_v7_design.md(계승) - track-e v3 계획:
docs/reference/project_state/track_e_vq_codebook_research.md(참조) - v6 R1b 근거:
.claude/agent-memory/exp-expert/exp6_fedpm_results_snapshot.md - FedPM 수치:
.claude/agent-memory/exp-expert/fedpm_paper_util_numbers.md