9. MoE 안정성과 검증

MoE 전략(mixture_lora, moe_expert_lora)을 안전하게 사용하기 위한 가이드입니다. dense_lora, native_moe_expert_lora는 이 가이드의 대상이 아닙니다.

1. 왜 MoE 안정성 설정이 필요한가

Mixture-of-Experts는 Dense 모델보다 훈련이 불안정합니다. 주요 위험:

위험	원인	결과
라우터 logit overflow	softmax 입력이 매우 커짐	NaN loss, 훈련 발산
라우팅 붕괴	소수 전문가만 토큰을 받음	나머지 전문가가 학습되지 않음
토큰 드롭	전문가 처리량 초과	정보 손실
수치 불안정	저정밀 라우터 연산	비정상적 라우팅 결정

EulerForge의 validator는 이 위험을 설정 시점에서 차단합니다.

2. 필수 설정: `moe` 섹션

MoE 전략 사용 시 YAML에 moe 섹션이 반드시 필요합니다:

moe:
  router_z_loss_coef: 0.001        # (A) 라우터 안정화
  load_balance:                     # (B) 부하 분산
    type: aux_loss
    aux_loss_coef: 0.01

누락 시 에러:

MoE Config: MoE strategy requires 'moe' section with stability parameters (router_z_loss_coef, load_balance).
Fix: Add 'moe:' section with router_z_loss_coef: 0.001 and load_balance: {type: aux_loss, aux_loss_coef: 0.01}
See: docs/tutorials/09_moe_stability_and_validation.md

3. 핵심 파라미터 해설

(A) `router_z_loss_coef` — 라우터 logit 안정화

역할: 라우터의 softmax 입력(logit)이 지나치게 커지는 것을 방지합니다. z-loss는 logit의 제곱합에 비례하는 패널티를 추가하여 값을 적정 범위에 유지합니다.

근거: ST-MoE (Zoph et al., 2022)에서 z-loss 0.001이 훈련 안정성을 크게 향상시킴을 확인.

값	효과
`0.001`	권장. ST-MoE 기본값
`0`	z-loss 비활성화 (경고). 소규모 실험에서만
`> 0.1`	경고. 라우터 logit이 과도하게 제약됨
음수	에러

moe:
  router_z_loss_coef: 0.001  # 권장

(B) `load_balance` — 부하 분산 정책

역할: 토큰이 소수 전문가에 집중되는 "라우팅 붕괴"를 방지합니다.

type 옵션:

type	설명	추가 파라미터
`aux_loss`	보조 손실로 균형 유도	`aux_loss_coef` (필수)
`aux_loss_free`	bias 조정으로 균형 유도 (DeepSeek-V3)	`bias_update_speed` (필수)
`none`	부하 분산 없음 (경고)	—

aux_loss_coef 가이드:

값	효과
`0.01`	권장. 적절한 균형
`< 0.001`	느슨한 균형 — 부분적 붕괴 가능
`> 0.1`	과도한 균형 강제 — 전문가 특화 저하
`0`	실질적 비활성화 (경고)

moe:
  load_balance:
    type: aux_loss
    aux_loss_coef: 0.01  # 권장

(C) `capacity_factor` — 전문가 처리량 상한 (선택)

역할: 각 전문가가 한 배치에서 처리할 수 있는 최대 토큰 비율을 제한합니다.

키	권장값	근거
`capacity_factor_train`	`1.25`	ST-MoE: 훈련 시 약간의 여유
`capacity_factor_eval`	`2.0`	ST-MoE: 평가 시 토큰 드롭 최소화

주의: capacity_factor_eval < capacity_factor_train이면 경고가 발생합니다. 평가 시에는 훈련보다 넓은 여유를 두는 것이 일반적입니다.

moe:
  capacity_factor_train: 1.25
  capacity_factor_eval: 2.0

(D) `router_dtype` — 라우터 연산 정밀도 (선택)

역할: 라우터의 softmax/exp 연산 정밀도를 지정합니다.

값	안정성	속도
`float32`	높음 (권장)	기준
`bfloat16`	낮음 (경고)	빠름
`float16`	낮음 (경고)	빠름

ST-MoE는 라우터 연산에 float32를 사용하여 수치 안정성을 확보합니다.

moe:
  router_dtype: float32  # 기본값이자 권장값

4. 전체 예시: mixture_lora 프리셋

backbone: qwen3
model_name: Qwen/Qwen3.5-0.8B-Base

injection:
  strategy: mixture_lora
  lora_r: 16
  lora_alpha: 32
  num_experts: 4
  top_k: 2

training:
  type: sft
  lr: 2e-5
  max_train_steps: 10000
  phases:
    - step: 0
      trainable: [router]          # Phase 1: 라우터만
    - step: 1000
      trainable: [lora, router]    # Phase 2: LoRA + 라우터

moe:
  router_z_loss_coef: 0.001
  load_balance:
    type: aux_loss
    aux_loss_coef: 0.01
  router_dtype: float32            # 선택 (기본값)

5. Preflight: 모델 로드 후 검증

--preflight는 설정 검증 후 모델을 실제로 로드하여 런타임 검사를 수행합니다:

eulerforge train --preset configs/presets/qwen3.5_0.8b_mixture_lora_sft.yml --preflight

Preflight가 확인하는 항목:

검사	설명
그룹 파라미터 수	페이즈가 참조하는 그룹(lora, router 등)에 실제 파라미터가 있는지
target_layers 범위	target_layers 인덱스가 모델의 실제 레이어 수 이내인지

Preflight는 훈련 없이 설정·모델·인젝션·페이즈의 정합성을 빠르게 확인하는 용도입니다.

6. 자주 발생하는 에러와 해결

`moe` 섹션 누락

MoE Config: MoE strategy requires 'moe' section ...
Fix: Add 'moe:' section with router_z_loss_coef: 0.001 and ...

→ YAML에 moe: 블록을 추가하세요. 위 섹션 2 참조.

`router_z_loss_coef` 누락

MoE Config: moe.router_z_loss_coef is required ...
Fix: Set moe.router_z_loss_coef: 0.001 (ST-MoE recommended)

→ moe: 아래에 router_z_loss_coef: 0.001을 추가하세요.

`load_balance` 누락

MoE Config: moe.load_balance is required ...
Fix: Add moe.load_balance: {type: aux_loss, aux_loss_coef: 0.01}

→ moe: 아래에 load_balance: 블록을 추가하세요.

라우터가 어떤 페이즈에도 없음 (경고)

[Validator] MoE strategy 'mixture_lora' is used but 'router' never appears in any training phase.

→ 최소 하나의 페이즈에 router를 trainable에 포함하세요.

router_dtype 수치 불안정 (경고)

[Validator] moe.router_dtype='bfloat16' may cause numerical instability ...

→ 안정성이 우선이면 router_dtype: float32로 변경하세요.

7. 오타 자동 감지

validator는 흔한 오타를 감지하여 올바른 키를 제안합니다:

오타 입력	교정 제안
`router_zloss_coef`	`router_z_loss_coef`
`router_z_loss`	`router_z_loss_coef`
`zloss`	`router_z_loss_coef`
`aux_coef`	`aux_loss_coef`
`balance_type`	`type`

8. 관련 문서

CLI 레퍼런스 — 전체 CLI 옵션
LoRA MoE 튜토리얼 — mixture_lora 전략 실습
FFN MoE 튜토리얼 — moe_expert_lora 전략 실습
검증 규칙 정본 — 모든 검증 규칙

← 이전 8. PPO (RLHF) 훈련 10. 메트릭 모니터링 다음 →

9. MoE 안정성과 검증

1. 왜 MoE 안정성 설정이 필요한가

2. 필수 설정: moe 섹션

3. 핵심 파라미터 해설

(A) router_z_loss_coef — 라우터 logit 안정화

(B) load_balance — 부하 분산 정책

(C) capacity_factor — 전문가 처리량 상한 (선택)

(D) router_dtype — 라우터 연산 정밀도 (선택)