docs/pcm.md

# PCM (Phased Consistency Model) 蒸留

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

> ❌ **重要: PCM の生成品質は低く、実用非推奨**
>
> 5000 step 完走 + 数値的に安定収束したが、**visual 品質が公式 Civitai Anima Turbo や DMDX に劣る**。
> cold-start の strategy が Anima では機能しなかったと推定。実用は **公式 Civitai Anima Turbo** を推奨。
> 本ドキュメントは失敗事例の記録 + 改善方向の参照用。

## 概要

[Wang et al. NeurIPS 2024](https://arxiv.org/abs/2405.18407)、G-U-N/Phased-Consistency-Model SD3 流派を Anima v1.0 base に移植。**FlowMatch + v-pred** で Anima の rectified flow と math 一致、ε↔v 変換不要。

**実装**: `scripts/distill/{pcm_scheduler,train_pcm}.py`
**Modal**: `modal_app.py::train_pcm_distill`

## 設計の鍵

- num_euler_timesteps **N=50** を K=4 phase に均等分割 → 4-step inference に最適化
- ランダム index sampling → phase 終端まで Euler 1 step 進める
- pseudo-Huber loss (`c=1e-3`) で stable convergence
- 1 grad-through + 3 no_grad forward / step → ~60-80 GB on B200 (LoRA-only)
- CFG-augmentation: `w ∈ [4.0, 5.0]` を訓練に embed → 推論 CFG=1.0 で teacher CFG=4.5 効果

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

| 項目 | 値 |
|---|---|
| Base | `anima-base-v1.0.safetensors` |
| Method | Phased Consistency Model |
| LoRA target | wide (AdaLN + attn + MLP の全 Linear、980 keys) |
| LoRA rank | 32 |
| Total steps | 5000 (sample_every=500) |
| Batch / grad accum | 1 / 4 |
| Resolution | 768 |
| Euler N / Phases K | 50 / 4 |
| sigma_shift | 3.0 |
| CFG-aug w range | [4.0, 5.0] |
| Huber c | 1e-3 |
| LR | 5e-6 |
| Optimizer | AdamW (wd 0.01) |
| Warm-start | **無し** (cold-start on v1.0 base) |
| GPU | B200 |
| 訓練時間 | **~3.4h** (1.72s/step、想定 6.5h の半分) |
| コスト | **~$22** (B200 $6.25/h) |

## Loss 推移

- 早期 (step 0-100): 0.001-0.14 範囲、warm-start 無しでも安定
- 中盤 (step 1000-3500): 0.001-0.007 で healthy plateau
- 後半 (step 4000-5000): 同水準維持、divergence なし

```
step 20  loss=0.0013  (初期 random spike 後すぐ低下)
step 130 loss=0.4468  (single spike、shifted sampling の hard spot)
step 500-4500 loss=0.001-0.007 範囲で平均化
```

mean collapse・NaN・OOM の発生 **なし**。

## 検証結果 (4-step 生成、user 評価で品質不足)

同 prompt × seed=42、Anima v1.0 base、er_sde / simple / sigma_shift=3.0:

| ckpt | sampler / scheduler | 時間 | 評価 |
|---|---|---|---|
| step 3500 | er_sde + simple | 8.8s | 2 キャラは描けるが、Turbo / DMDX より明らかに品質低い |
| step 4000 | res_multistep + beta | 11.2s | 同等の品質劣化 (sampler 差で改善せず) |
| final (step 5000) | — | — | 同上、user 判定で **実用不可** |

両 sampler とも 4-step CFG=1.0 で動作はするが、Civitai Turbo や DMDX の出力と比較すると
細部のシャープさ・色彩・ディテール表現が劣る。**numerical 収束したが visual 品質が伸びなかった失敗例**。

## 配布

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

- `pcm_final_peft.safetensors` (diffusers / peft 用)
- `pcm_final_comfy.safetensors` (ComfyUI 用、980 keys)
- README.md (使い方 + 訓練詳細)
- samples/ (step 3500 / 4000 検証画像)

## ComfyUI 推奨設定

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

ModelSamplingAuraFlow:
  shift: 3.0

KSampler:
  steps: 4
  cfg: 1.0
  sampler_name: er_sde  (or res_multistep)
  scheduler: simple     (or beta with res_multistep)
```

## 知見 (失敗分析含む)

### 数値上は成功した

- **cold-start でも数値的に安定** — phase consistency が numerical anchor となり divergence なし
- **rate 想定より速い** — README 試算 4.7s/step → 実測 1.72s/step (B200 sageattention 効果含む)
- **single grad-through で memory 余裕** — DMD2 の dual adapter 構成より軽量

### しかし visual 品質は低い (実用非推奨)

5000 step 完走 + loss 健全に推移したが、生成画像の品質が Civitai Anima Turbo / DMDX より明らかに劣る。
推測される原因:

| 原因候補 | 詳細 |
|---|---|
| **cold-start の限界** | warm-start (公式 Turbo の既存 4-step 知識) なしで Anima 系の蒸留は厳しい可能性 |
| **phase consistency が style anchor として弱い** | data 分布の mean に向かう gradient はあるが、anime style の鋭さを保つ adversarial signal がない |
| **CFG-augmentation embed が不完全** | w∈[4.0, 5.0] の embed が teacher CFG=4.5 を完全再現していない可能性 |
| **データセット規模** | 5000 sample は cold-start には不十分の可能性 (公式 Turbo は数万-数十万規模) |

### 教訓 (重要)

- **loss が健全でも visual 品質を保証しない** — [distillation.md §4.1 Layer 4-5](distillation.md#41-phase-a-の詳細-postmortem5-層因果分析) の Phase A ステルス失敗と同根
- **中間 ckpt の visual 検証が必須** — quick_check_ckpt で 500 step ごとに見るべきだった
- **Anima 系 distill の cold-start は警戒**: 公式 Turbo の warm-start が事実上必須

### 改善方向

- warm-start (Civitai Turbo) を導入して semi-fine-tune に切り替え
- dataset 規模拡大 (5000 → 20000+)
- LADD 流の Smooth-L1 anchor 追加 (PCM では消えるが phase loss と組合せ可能)
- 他の蒸留手法 (DMD2 + R3GAN、Hyper-SD 系) に切り替え検討