docs/dmd2.md

# DMD2 (NVIDIA cosmos-predict2.5 流派) 蒸留

[← README に戻る](../README.md) — 関連: [PCM](pcm.md) / [DMDX](dmdx.md) / [蒸留全般](distillation.md)

## 概要

NVIDIA cosmos-predict2.5 公式の **DMD2 + TrigFlow** 流派を Anima 移植。同 base に **2 つの独立 PEFT adapter** (student / fake_score) を attach し `set_adapter()` で runtime 切替、TTUR (alt 5 critic : 1 generator)。

**実装**: `scripts/distill/{dmd2_official_loss,train_dmd2_official}.py`
**Modal**: `modal_app.py::train_dmd2_official_distill`

## 設計の鍵

- **2 adapter / single base** → memory 効率 (teacher は別 deepcopy)
- **TrigFlow time sampling**: `s ∈ shifted_uniform(shift=3-5) → t = arctan(s/(1-s))`
- **DMD2 gradient trick** (逆 KL): `grad = (x0_fake - x0_teacher) / |x_hat - x0_teacher|.mean()`
  → `loss = ((x_hat - (x_hat - grad).detach())**2).mean()`
- **Critic phase**: weighted denoise with `1/sin(t)**2` factor
- **few-step rollout** (n=1..4)、grad は最終 step のみ (memory efficient)

## 訓練設定 (実走、2026-05-18 - 19)

| 項目 | 値 |
|---|---|
| Base | `anima-base-v1.0.safetensors` |
| Method | DMD2 + TrigFlow (cosmos-predict2.5) |
| LoRA target | wide (980 keys) × 2 (student + fake_score) |
| LoRA rank | 32 |
| Total outer | 5000 (1 outer = 5 critic + 1 generator) |
| n_student_steps | 4 |
| Teacher CFG | **4.5** (Anima 公式推奨に整合、過去 preview3 試行の 3.0 から変更) |
| Student CFG | 1.0 (CFG embedded) |
| Shift | **3.0** (Anima sigma_shift と一致、過去の 5.0 から変更) |
| LR (gen / critic) | 5e-6 / 1e-5 (TTUR) |
| Warm-start | **`/models/loras/anima_turbo.safetensors`** (Civitai 公式 Turbo、968/1016 keys 一致) |
| GPU | B200 |
| 訓練時間 | step 660 まで ~40 min、resume + 4500 outer ~7h |
| コスト | 累計 ~$48-55 想定 (rate 6.2s/outer parallel 時) |

## 試行履歴 (2026-05-18 - 19)

### 1st run (`/output/dmd2_v1/`)
- 設定: warm-start (Anima Turbo) + 5000 outer
- 経過: step 660/5000 で `KeyboardInterrupt`
- 原因: **Modal workspace billing cycle spend limit reached** (DMDX 並列起動で予算限度超過)
- 保存: step 500 ckpt のみ無事 (volume commit 済)

### Resume (`/output/dmd2_v1_resume/`)
- 設定: step 500 ckpt を warm-lora、残り 4500 outer
- warm-load: **980/980 keys 完全一致** (自前 LoRA 同 architecture)
- **完走済** (outer 4500/4500、累計 ~7.7h、~$48): `dmd2_student_final.safetensors` + 9 個の intermediate ckpt 保存
- 中断による rate slowdown あり (3.66s → 6.15s/outer、並列実行 + Modal capacity の影響)

### 結論: warm-start dominance (DMDX と同じ問題)

5000 outer 完走したが、student LoRA は **warm-start (Civitai Anima Turbo) からほぼ移動せず**、
視覚的に Turbo と区別困難。DMDX と全く同じ症状で、手法ではなく **warm-start anchor が支配的**。

## Loss 推移 (順調)

| outer | l_dmd_critic | l_dmd_gen | 評価 |
|---|---|---|---|
| 0 | 0.0364 | 1.5780 | warm-start 直後 |
| 100 | 0.07 | 1.18 | gen 急速降下中 |
| 500 | 0.06 | 1.30 | spike あるが healthy |
| 660 (中断) | 0.0471 | 0.16 | 健全な状態で中断 |
| resume 0 | 0.0364 | 1.5771 | warm-load から再開、原 outer 0 と類似 |
| resume 500 | 0.058 | 1.29 | 期待通り |
| resume 1000 | 0.054 | 0.89 | 順調収束 |

magnitude (x_hat / teacher / fake): ~0.3-0.5 範囲で揃って distill 方向収束。

## 検証結果

### step 500 (resume 開始時、4-step / er_sde+simple)

- 2 キャラ (Flandre / Remilia) 正確分離
- Civitai Turbo に近い品質 (warm-start 支配的、step 500 で大幅変化なし)
- 生成時間 10.95s

### final (5000 outer 完走、4-step / er_sde+simple)

- step 500 と視覚的にほぼ同一
- Civitai Anima Turbo baseline と区別困難
- 5000 outer 訓練を完走したが student LoRA の重みが warm-start からほぼ動かなかった

ローカル DL 済: `~/Downloads/anima_loras/dmd2/dmd2_v1_step00500.safetensors`

## 配布

[HF: darask0/anima-distill-loras/dmd2/](https://huggingface.co/darask0/anima-distill-loras/tree/main/dmd2)

PEFT + ComfyUI 両形式 + 専用 README + 比較サンプル画像 (Turbo vs DMD2 final) を upload 済。
実用としては Civitai Anima Turbo と差異なし、研究目的の配布。

## ComfyUI 推奨設定

```
LoraLoaderModelOnly:
  lora_name: dmd2_v1_step00500.safetensors
  strength_model: 1.0

ModelSamplingAuraFlow:
  shift: 3.0

KSampler:
  steps: 4
  cfg: 1.0
  sampler_name: er_sde
  scheduler: simple
```

## 過去の preview3 試行との対比

[migration_log.md §5.7](migration_log.md#57-実画像比較-2026-05同-prompt--seed) の preview3 DMD2 では:
- 8-step: 絵画調シフト、洗色傾向
- 4-step: シルエットのみ、ボケすぎ

→ 改善要因 (v1.0 試行):
- ✅ **warm-start (Civitai Turbo)** 必須化
- ✅ **teacher_cfg 3.0 → 4.5** (Anima 公式推奨)
- ✅ **shift 5.0 → 3.0** (Anima sigma_shift 整合、sampler 互換性向上)
- ✅ v1.0 base 直接 (preview3 ベース LoRA の style drift 回避)

## 知見

- **2 adapter peft set_adapter() で必須**: 毎 forward で明示切替しないと片方の重みが leak ([operations.md](operations.md) 参照)
- **`No module named 'modal'` の volume commit 失敗**: subprocess 内で modal lib 未参照、harmless warning (function 終了時に Modal 自動 commit)
- **billing limit による KeyboardInterrupt**: Modal の workspace spend limit に達すると **cloud function に SIGINT** が送られて停止する。ローカル CLI の interrupt とは別経路、Modal dashboard で billing を確認・上げる必要
- **parallel rate 低下**: 並列 (DMDX と) で 3.66s/outer → 6.2s/outer (~1.7x 遅い)、別 B200 アロケート時の混雑度に依存