10. 메트릭 모니터링

2단계 메트릭 시스템과 TensorBoard 통합 가이드.

개요

EulerForge는 훈련 중 메트릭을 2단계(minimal/advanced)로 수집합니다. TensorBoard를 통해 시각적으로 모니터링할 수 있습니다.

메트릭 레벨

minimal (기본)

모든 훈련 타입에서 기록되는 기본 메트릭:

태그	설명
`train/main_loss`	주 손실
`train/total_loss`	총 손실 (main + aux)
`train/aux_loss`	MoE 보조 손실 (MoE 전략 시)
`train/learning_rate`	현재 학습률
`train/grad_norm`	Global L2 그래디언트 노름
`train/tokens_seen`	누적 학습 토큰 수 (labels != -100)
`train/samples_seen`	누적 샘플 수 (preference: 쌍 기준)
`train/optimizer_step`	누적 옵티마이저 스텝 수
`train/micro_step`	누적 마이크로 스텝 수
`train/effective_batch`	유효 배치 크기 (batch_size x grad_accum_steps)

훈련 타입별 추가 메트릭:

타입	추가 태그
DPO	`train/reward_margin`, `train/accuracy`
ORPO	`train/sft_loss`, `train/orpo_loss`, `train/log_odds_ratio`
RM	`train/reward_margin`
PPO	`train/kl`, `train/reward_mean`, `train/advantages_mean`

advanced (minimal + MoE 라우팅 통계)

MoE 전략(mixture_lora, moe_expert_lora)에서 추가 기록:

태그	설명	해석
`moe/token_frac_std`	토큰 비율 표준편차	높으면 전문가 불균형
`moe/entropy_mean`	라우터 엔트로피	낮으면 라우팅 붕괴 의심
`moe/importance_cv`	중요도 변동계수	>1이면 심각한 불균형
`moe/aux_loss_total`	보조 손실 합계	급등 시 학습률 조정 필요
`moe/router_logit_max`	라우터 logit 최대값	>10이면 수치 폭주 의심

설정

logging:
  metrics_level: minimal       # "minimal" | "advanced"
  tensorboard:
    enabled: true              # TensorBoard 기록 (기본: false)
    log_dir: "outputs/tb"      # TensorBoard 로그 디렉토리
  log_interval: 50             # N 스텝마다 TensorBoard 기록
  max_experts_log: 16          # advanced에서 상위 N 전문가 상세 로그

CLI 오버라이드:

# 설정 파일 값 무시하고 advanced 사용
eulerforge train --preset PRESET.yml --metrics-level advanced

# --set으로도 가능
eulerforge train --preset PRESET.yml --set logging.metrics_level=advanced

TensorBoard 설치 및 실행

# 설치
pip install eulerforge[tb]

# 훈련 실행
eulerforge train --preset configs/presets/qwen3.5_0.8b_moe_expert_lora_sft.yml \
    --set logging.tensorboard.enabled=true \
    --set logging.tensorboard.log_dir=outputs/tb \
    --metrics-level advanced

# TensorBoard 시작
tensorboard --logdir outputs/tb

tensorboard 미설치 시 경고만 출력하고 훈련은 정상 진행됩니다.

검증

logging 섹션은 config validation에서 검사됩니다:

Logging Config: Unknown metrics_level 'invalid'. Valid: minimal, advanced
Fix: Set logging.metrics_level to 'minimal' or 'advanced'
See: docs/tutorials/10_metrics_monitoring.md

10. 메트릭 모니터링

개요

메트릭 레벨

minimal (기본)

advanced (minimal + MoE 라우팅 통계)

설정

TensorBoard 설치 및 실행

검증

관련 문서