docs/migration_log.md

# 既存実装の移植 — 2026-05 試行ログ

[← README に戻る](../README.md) — 前章: [distillation.md](distillation.md)

> ⚠️ 本ドキュメントは **2026-05-17 時点のスナップショット**を含む。Modal volume の
> 状態 (LoRA path、cache 内容など) は時間とともに変動するので、最新状態は
> `modal volume ls` で確認すること。配布済 LoRA は HF の
> [darask0/anima-distill-loras](https://huggingface.co/darask0/anima-distill-loras) に集約。

[§4 失敗分析](distillation.md#4-実際の失敗全-5-件詳細) の 5 回失敗を受け、「自前で書き下す」のを諦めて **既存の動く実装を最小改造で
Anima に移植する** 方針に転換。survey と smoke test を経て **5 手法** を実装、
本リポジトリに収録 (`scripts/distill/`)。

## 5.0 全体マップ

```
                         ┌── Z-Image trajectory imitation (DiffSynth-Studio 由来)
                         ├── DMD2 + TrigFlow      (NVIDIA cosmos-predict2.5 公式)
        蒸留 5 候補 ────┼── LADD                 (AMD Nitro-1 移植、PixArt 由来)
                         ├── Reflow / InstaFlow   (rfpp NeurIPS 2024 知見適用)
                         └── PCM                  (G-U-N/Phased-Consistency-Model、SD3 変種)
        
        無料補完  ────── ComfyUI-CapitanFlowMatch / ZiT-Scheduler (推論側 scheduler)
        
        survey で却下 ── DMDR / Hyper-SD / NitroFusion / ADD (訓練コード非公開)
```

## 5.1 採用 5 手法の概要

| # | 手法 | カテゴリ | 中核ファイル | 設計の鍵 |
|---|---|---|---|---|
| ① | Z-Image trajectory imitation | trajectory matching | `scripts/distill/{traj_scheduler,traj_loss,train_traj}.py` | critic なし、teacher 50-step CFG=2 trajectory を student 8-step に align |
| ② | DMD2 + TrigFlow (cosmos-predict2.5) | score matching | `scripts/distill/{dmd2_official_loss,train_dmd2_official}.py` | **同じ base に 2 LoRA adapter** (student + fake_score)、`set_adapter()` 切替、alt 5:1 |
| ③ | LADD (AMD Nitro-1) | adversarial + recon | `scripts/distill/{anima_ladd_disc,train_ladd}.py` + `precompute_teacher_x0.py` | D backbone = teacher MiniTrainDIT (frozen)、5 spectral-norm head、Smooth-L1 recon anchor |
| ④ | Reflow / InstaFlow | flow alignment | `scripts/distill/train_reflow.py` (cache は `--save-noise` 必須) | Anima は元から RF、U-shape t + Huber + 間欠 LPIPS、1 grad-through で最安 |
| ⑤ | PCM (Phased Consistency Model) | consistency | `scripts/distill/{pcm_scheduler,train_pcm}.py` | SD3-PCM 流派 (FlowMatch + v-pred)、Anima RF と math 一致、N=50 を K=4 phase に分割 |

全手法に共通の前提:
- **wide LoRA** (`attach_wide_lora()` で AdaLN + attn + MLP 全 Linear、454 modules、~72M trainable)
- **warm-start = Civitai 公式 Anima Turbo LoRA** (matched 968/1016 keys、x_embedder/t_embedder の 12 keys のみ skip)
- **B200 GPU** + dataset は `/dataset/raw` (5000 caption、品質タグは未掃除でも蒸留には影響なし)

## 5.2 R3GAN との決定的な違い (なぜ LADD は動く可能性が高いか)

| 失敗パターン | R3GAN | LADD |
|---|---|---|
| D が無信号 → mean collapse | CNN を一から学習、16ch latent prior なし | D backbone = **teacher MiniTrainDIT (frozen)**、Anima latent を既に理解 |
| D 爆発 | γ (gradient penalty) calibration 困難 | **spectral norm + BatchNormLocal** で D の Lipschitz 制約 |
| anchor 不在で発散 | DMD2 単独だと mean に潰れる | **Smooth-L1 recon loss** (vs teacher x0) で「絶対に teacher から離れない」床を作る |

LADD smoke (5 step、`l_g_adv ≈ ln(2) ≈ 0.69`, `l_d_total ≈ 2·ln(2) ≈ 1.39`) — R3GAN 試行で
1 度も達成できなかった「**stable initialization**」が初手で出る。

## 5.3 LoRA-only + warm-start + precompute cache の三位一体

3 つを組み合わせて実コストを大幅圧縮:

1. **LoRA-only (~72M trainable / 2B base)** — gen と D backbone は frozen、optimizer state も小さい
2. **warm-start (Civitai Turbo LoRA)** — cold-start より convergence が早く、品質下限が保証される
3. **precompute teacher x0 cache** — teacher の 20-step CFG=4.5 rollout を 1 度だけ実行 (~$11 / 5000 サンプル)、
   その後の蒸留で **複数手法が同じ cache を共有** (LADD / PCM が利用)

```
                  precompute_teacher_x0_cache  (1回, $11)
                          │
                          ├── LADD train     (cache の x0 を real として使用)
                          └── PCM train      (cache の emb を流用、x0 は teacher rollout source)
        
        precompute_for_reflow  (--save-noise 付き、別 cache, $11)
                          │
                          └── Reflow train   (noise + x0 + emb triplet)
```

## 5.4 採用しなかった手法 (survey 結果)

| 手法 | 却下理由 |
|---|---|
| **DMDR** (vvvvvjdy/dmdr) | ImageNet/SiT のクラス条件 toy のみ公開、T2I (Z-Image, SD3.5) パイプラインは未公開 |
| **Hyper-SD / Hyper-FLUX** (ByteDance) | 訓練コード非公開 (HF model card のみ)、コミュニティ port なし |
| **NitroFusion / NitroSD-Vibrant** (ChenDarYen) | 訓練コード "Coming Soon" のまま停滞、リポジトリは 6 commit で凍結 |
| **ADD / LADD-DINOv2** (StabilityAI) | 訓練コード非公開 (issues wontfix)、AMD 版で代替 |

## 5.5 inference 側補完: AYS / TeaCache / GGUF / sageattention の適用可否

| 手法 | Anima 適用可否 | 理由 |
|---|---|---|
| **AYS** (NVIDIA Align Your Steps) | ❌ | ComfyUI 公式実装は **SD1/SDXL/SVD の sigma schedule を hardcode** で rectified flow 未対応 |
| **TeaCache** (timestep 残差 cache) | ⚠️ **base 高 step 用のみ** | 4-8 step 蒸留 LoRA とは**構造的に non-compatible** (連続 step の差分が大きすぎてスキップ不可)。base 28-50 step での **2x 速** には使える、porting ~250 LoC |
| **ComfyUI-GGUF** Q8/Q4 量子化 | ⚠️ Anima 未対応 | FLUX/SD3/Hunyuan 系のみ。Anima loader 追加 + GGUF 変換が必要 |
| **CapitanFlowMatch / CapitanZiT-Scheduler** | ✅ | rectified flow / Cosmos-Predict2 兄弟向け scheduler、ComfyUI ノード追加だけ |
| **sageattention** | ✅ | torch SDPA 置換で 1.2-1.5x 推論速、`pip install sageattention` で `_base_image` に同梱済 |
| **DPM-Solver++ 高次** / **UniPC** | ✅ | sampler ノード切替のみ、Anima 標準 `er_sde` の代替 |

**実用推奨**: 蒸留 LoRA + sageattention + CapitanFlowMatch scheduler のスタックが最も効率的。
TeaCache は「LoRA 使わず base 高品質モード」用の補完として将来 porting する価値あり (~250 LoC, ~$10 calibration)。

## 5.6 これから挑む人へ

- **survey をサボらない**: 4 つの「有名手法」が実は訓練コード非公開で詰む。GitHub の README を見るだけでなく `train.py` / `run.sh` を実際に開いて確認
- **`scripts/distill/anima_loader.py` は再利用** — `build_anima()` + `AnimaBundle` で diffusion-pipe の罠 (namespace shadow、`padding_mask` 必須、dtype object vs str など) を全部吸収済
- **smoke test を必ず 1 step 走らせる** — sign / dtype / 配線ミスを **$1-2 で発見**、本番 $30-50 をドブに捨てるリスク回避
- **`MSYS_NO_PATHCONV=1 PYTHONIOENCODING=utf-8 PYTHONUTF8=1` を modal CLI に毎回つける** (Windows JP locale 必須)

## 5.7 実画像比較 (2026-05、同 prompt × seed)

5 prompt × 2 seed × {8 step, 4 step} × {base CFG=4.5, Civitai 公式 Turbo CFG=1, ① Z-Image
trajectory imitation CFG=1, ② DMD2 CFG=1} = **80 枚** を Modal `compare_distill_loras` で
生成 + v1.0 base 上で **13 条件 1 prompt 1 seed** を `verify_completed_loras` で生成。
同 noise seed なので 1:1 で比較可能 (実装: [modal_app.py](../modal_app.py))。

**観察された明確な順位** (8-step CFG=1、preview3 base、5 prompt × 2 seed = 80 枚):

| Rank | 手法 | 評価 |
|---|---|---|
| 🥇 | **Civitai 公式 Anima Turbo** | シャープ、彩度高、盾の紋章/松明の光まで完備、キャラ識別正確 |
| 🥈 | ① Z-Image traj imitation (本 repo) | 鮮明・安定、ディテール OK |
| 🥉 | ② DMD2 (本 repo) | 絵画調シフト、やや洗色傾向 |
| ❌ | base 30step→8step | 暗め・シンプル、品質劣化大 |

**4-step での頑健性順位**:

| Rank | 手法 | 評価 |
|---|---|---|
| 🥇 | **Civitai 公式 Anima Turbo** | 8-step とほぼ同等品質を維持 |
| 🥈 | ① Z-Image | エッジ甘くなる (8-step 訓練だったため) |
| ❌ | ② DMD2 | シルエットのみ、ボケすぎ |
| ❌ | base | ほぼ崩壊、使用不可 |

**v1.0 base での生成時間 (sageattention 有効、1024×1024、er_sde/simple/shift=3)**:

| step / 条件 | 時間 | 備考 |
|---|---|---|
| 4-step LoRA (全 6 LoRA) | **3.5-4.0s** | 公式 Turbo / ① Z-Image / ② DMD2 / ④ Reflow / ⑩ DRaFT+ 系すべて |
| 8-step LoRA (全 6 LoRA) | **4.0-4.7s** | 同上 |
| 30-step base CFG=4.5 | **10.7s** | LoRA 無効、品質基準 |

→ **4-step LoRA = base 30 step の 3 倍速**、sageattention 効果込み。Modal B200 のコスト換算で
1 画像 ~$0.006 (4-step LoRA) vs ~$0.018 (base 30 step)。

**正直な結論**: **CircleStone Labs 公式 Turbo (Civitai) に予算 ~$300 で勝つのは現状困難**。
公式は遥かに多い GPU 時間と専門知見を投入した結果。本 repo の自前蒸留は:

- base からの **品質向上は明白** (8-step CFG=1 が実用レベル)
- 公式 Turbo に **代替/補完** できる位置 (ライセンス遵守、自前カスタマイズ可)
- **学習目的・特定スタイル特化・蒸留パイプライン理解** には十分価値

### 5.7.1 v1.0 base 切替で観察された style drift

2026-05-17 に base を `anima-preview3-base.safetensors` → `anima-base-v1.0.safetensors` に
切替。**既存 LoRA はすべて preview3 で訓練済だが v1.0 でも動作する** (アーキ互換)。ただし:

- **出力 style がデフォルメ寄りに変化** — verify_v1_sage の 13 条件すべてで chibi/SD 風が強く
  出た。preview3 base での同じ LoRA の出力 (compare_z_vs_dmd2) は比較的写実寄り
- 原因仮説: v1.0 base が「young girl appearance」prompt を v1.0 の aesthetic prior でより
  強く解釈する。preview3 とは prior 分布が異なる
- LoRA を再訓練するなら v1.0 base 上で行うのが筋。preview3 ベース LoRA を v1.0 で使う場合は
  style ドリフトを受け入れる前提

## 5.8 まだ試せる方向 (諦める理由はない)

公式 Turbo に勝てないと判明しても、以下は試す価値がある:

1. **訓練 step を増やす** — ① Z-Image を 2000 → 8000 step に延長 (+$54)、loss はまだ
   plateau の手前で振動していた
2. ~~**蒸留 LoRA に DRaFT+ HPSv2 reward を追加学習**~~ — **検証済、推奨せず** (§5.10 参照)。
   HPSv2 score は +13 上昇したが視覚的には **reward hacking で劣化** (anime → 西洋イラスト
   風にドリフト、キャラ固有要素曖昧化、prompt adherence 落下)
3. **より高解像度 teacher rollout** — 768 → 1024 で precompute (+$22 / cache、+$20 / train)
4. **スタイル/キャラ特化蒸留** — 公式 Turbo は汎用向け、特定ドメイン (例: 単一キャラ、
   特定 artist style) なら自前のほうが優位の可能性
5. **LoRA rank を上げる** — 32 → 64 / 128 (`--lora-rank 64`)、より大きな容量で
   teacher の細部を学べる可能性
6. **既存実装 (LADD/Reflow/PCM/SiD2/Shortcut) の本番結果を待つ** — 進行中、Z-Image を
   超える手法が出る可能性は残る
7. **8 手法の **アンサンブル** — 複数 LoRA を runtime で blend (`ComfyUI` で
   `LoraLoaderModelOnly` を 2 個直列に挟むだけ)、相補的に効くケースあり
8. **v1.0 base で再訓練** — 既存 LoRA は preview3 起点、v1.0 で訓練し直すと aesthetic
   一致でさらに伸びる可能性 (§5.7.1 参照)

「公式に勝つ」のではなく「**公式とは違う強みを持つ自前 LoRA**」を作る方が現実解。
本 repo の 7 実装は **どれもライセンス上自由に派生可能** で、warm-start の柔軟性が
あるのが公式 Turbo にはない利点。

### 5.8.1 ファインチューニング dataset 生成 (進行中、2026-05-17)

**目的**: hakushiMixAnima_v02 base + anima-highres-aesthetic-boost LoRA を組み合わせて、
**特定 4 artist のスタイル mix LoRA** を fine-tune するための合成 dataset を生成。

**Artist tags (固定 4 名、本 repo では秘匿 ♥)**:

```
@artist_1, @artist_2, @artist_3, @artist_4
```

- **本ドキュメントではセキュリティ / プライバシーの観点から具体的 artist 名を伏せる**
- 実 artist tag は `scripts/finetune_prompts*.txt` (Modal volume の private prompts ファイル) と
  user の脳内にのみ存在する
- **Claude (AI assistant) が処理上 artist tag の実値が必要になった場合は、必ず user に質問**
  して聞き出すこと。推測や前回会話履歴からの引用で済まそうとしない (privacy 保護)
- 4 artist は毎 prompt 必ず含まれる (artist drop なし、style mix を強固に学習させる狙い)

**Dataset 構成**:

| subdir | safety | themes | seeds | 想定枚数 | 内容 |
|---|---|---|---|---|---|
| `/dataset/finetune_raw/` | `safe` | 60 | 16 | 960 | SFW v1: 単体キャラ + couple + group + 環境 |
| `/dataset/finetune_raw_v2/` | `safe` | 60 | 16 | 960 | SFW v2: animal/mytho/sports/cyberpunk/etc |
| `/dataset/finetune_raw_v3/` | `safe` | 60 | 16 | 960 | SFW v3: 職業/世界観 (idol/detective/scholar/etc) |
| `/dataset/finetune_raw_nsfw/` | `nsfw` | 30 | 16 | 480 | suggestive (bath/lingerie/bedroom/etc) |
| `/dataset/finetune_raw_explicit/` | `explicit` | 30 | 16 | 480 | explicit sex acts #1-30 |
| `/dataset/finetune_raw_explicit_v2/` | `explicit` | 60 | 16 | 960 | explicit sex acts #31-90、consensual framing 8 件修正 |
| **合計** | | **300 themes** | | **~4800** | |

訓練時は AnimaImageCaptionDataset の rglob で全 subdir 自動取り込み (親 `/dataset/` を指定)。

### 5.8.2 ファインチューニング訓練計画

完成後 `train_finetune_4variants` で 4 hyperparam 並列実行 (各 B200):

| variant | rank | lr | epochs | drop_artist | 狙い |
|---|---|---|---|---|---|
| A baseline | 32 | 2e-5 | 3 | 0.0 | Anima 公式推奨そのまま |
| B higher capacity | 64 | 2e-5 | 3 | 0.0 | rank 倍で細部表現↑ |
| C safer LR | 32 | 1e-5 | 4 | 0.0 | 過学習回避 + step ↑ |
| D artist focus | 32 | 3e-5 | 3 | 0.0 | lr 強めで style 強化 |

**`llm_adapter_lr = 0` 必須** (Anima 公式既知識保護、本 repo `configs/phase1_anima.toml` 既設定)。

## 5.9 実走中の状態スナップショット (2026-05-17 時点)

> ⚠️ このセクションは **2026-05-17 時点のスナップショット**。実際の Modal volume 上の
> path / 中身は時間と共に変わる。最新は `modal volume ls anima-outputs` で確認。
> 現在配布済の LoRA は HF [darask0/anima-distill-loras](https://huggingface.co/darask0/anima-distill-loras) に集約。

このリポジトリで現在 Modal 上に保存されている / 訓練中の LoRA とその想定用途。
中断/再開時の参照用:

| LoRA | path on `anima-outputs` volume | source method | 状態 (当時) | コスト |
|---|---|---|---|---|
| **traj_final** | `/output/traj_full/traj_final.safetensors` | ① Z-Image trajectory imitation | ✅ 完走 (2000 step) | $18 |
| **traj_extended** | `/output/traj_extended_8000/traj_final.safetensors` | ① Z-Image 延長 (6000 step 追加) | 🟢 進行中 | ~$54 |
| **traj_rank128** | `/output/traj_rank128/traj_final.safetensors` | ① rank 32→128 cold-start | 🟢 進行中 | ~$50 |
| **dmd2_student_final** | `/output/dmd2_full/dmd2_student_final.safetensors` | ② DMD2 + TrigFlow | ✅ 完走 (3000 outer) | $19 |
| **ladd_v2_fast** | `/output/ladd_v2_fast/ladd_student_final.safetensors` | ③ LADD-v2 (bug 修正版) | 🟢 進行中 | ~$17 |
| **reflow_final** | `/output/reflow_full/reflow_final.safetensors` | ④ Reflow (rfpp) | 🟢 進行中 (~7000 step) | ~$8 |
| **pcm_final** | `/output/pcm_full/pcm_final.safetensors` | ⑤ PCM (SD3 流派) | 🟢 進行中 | ~$36 |
| **sid_student_final** | `/output/sid_full/sid_student_final.safetensors` | ⑥ SiD2 (data-free) | 🟢 進行中 | ~$18 |
| **shortcut_final** | `/output/shortcut_full/shortcut_final.safetensors` | ⑦ Shortcut Models (d-head) | 🟢 進行中 | ~$25 |
| **draftp_final** (Z-Image warm) | `/output/draftp_full/draftp_final.safetensors` | ⑧ DRaFT+ HPSv2 on ① | ✅ 完走 | $3 |
| **draftp_on_turbo** | `/output/draftp_on_turbo/draftp_final.safetensors` | ⑧ DRaFT+ HPSv2 on Civitai Turbo | ✅ 完走 | $3 |

中間 cache:
- `/dataset/teacher_x0_cache/` — 5000 サンプル、teacher 20-step CFG=4.5 の x0 + Qwen3 emb
- `/dataset/reflow_cache/` — 同上 + `noise` も保存 (Reflow / Shortcut 用)
- `/dataset/teacher_x0_smoke/` — 50 サンプル smoke 用
- `/models/loras/anima_turbo.safetensors` — Civitai 公式 (warm-start 用)
- `/models/hpsv2/HPS_v2_compressed.pt` — DRaFT+ 用 reward model

比較生成: `compare_distill_loras` (4 条件) と `compare_all_methods` (全 9-11 条件、final LoRA
存在を自動判定) の 2 種を `modal_app.py` に実装済。後者は 5 残り手法の本番完了後に走らせる。

実コスト累計 (2026-05-17 時点): **~$200** (smoke + 失敗 + 完走 + 進行中の使用済分込み)、
予算 $300 の 67%。

### 5.9.2 Modal volume 構成 (4 volumes)

本リポジトリは **4 つの Modal volume** を使い分けて状態を持つ。volume mount は
`modal_app.py::VOLUMES` で定義。

#### A. `anima-models` (~30 GB) — base モデル + 全 LoRA + reward weights

mount: `/models`、create_if_missing=True

```
checkpoints/
  anima-base-v1.0.safetensors          ← 現用 base (4.18 GB)
  hakushiMixAnima_v02.safetensors      ← (symlink, comfyui-anima-models から)
  qwen_3_06b_base.safetensors          ← text encoder
  qwen_image_vae.safetensors           ← VAE
  phase_a_distilled.safetensors        ← 旧 Phase A 失敗 ckpt (~$70 で失敗、残ってる)
  phase_a_step1000.safetensors         ← 旧 Phase A 中間
  anima-preview3-base.safetensors      ← ❌ 削除済 (v1.0 切替時)

loras/
  anima_turbo.safetensors               ← Civitai 公式 (warm-start のデファクト)
  z_image_traj_final.safetensors        ← ① Z-Image 蒸留 (preview3 起点、完走 LoRA)
  dmd2_student_final.safetensors        ← ② DMD2 (preview3 起点、完走 LoRA)
  reflow_final.safetensors              ← ④ Reflow (preview3 起点、完走 LoRA)
  draftp_on_zimage.safetensors          ← ⑩ DRaFT+ on Z-Image (品質追加学習)
  draftp_on_turbo.safetensors           ← B: DRaFT+ on Civitai Turbo (reward hacking 検証済、品質劣化)
  ladd_v2_step500.safetensors           ← ③ LADD v2 部分 (停止前 step 500)
  pcm_step500.safetensors               ← ⑤ PCM 部分 (停止前 step 500)
  anima-highres-aesthetic-boost.safetensors ← (symlink, comfyui-anima-models から)
  phase_b/d/f_4step_lora.safetensors    ← 旧 R3GAN 試行の残骸 LoRA

hpsv2/
  HPS_v2_compressed.pt                  ← DRaFT+ 用 reward model (1.97 GB)

torchhub/                                ← torch.hub cache
cache/                                   ← misc cache (sageattention 等)
```

#### B. `anima-dataset` (~40 GB) — 全データセット + 比較生成出力

mount: `/dataset`、create_if_missing=True

**A. 元データ / self-distillation**:
- `raw/` — Anima base 自己生成 5000 (.png + .txt)、初期 distill 用
- `samples/`, `turbo_test/`, `compare/` — 過去の動作確認生成

**B. 蒸留用 precompute cache**:
- `teacher_x0_smoke/` — 50 サンプル smoke 用
- `teacher_x0_cache/` — 5000 サンプル × (x0 + emb)、LADD/PCM/SiD2 用
- `reflow_cache/` — 同上 + noise 保存、Reflow / Shortcut 用

**C. 比較 / 検証生成**:
- `compare_z_vs_dmd2/` — 80 PNG (base / turbo / ① / ② × 8/4 step)
- `verify_completed/` — 旧 verify (workflow bug で 0 images、失敗)
- `verify_v1_sage/` — v1.0 + sageattention で 13 条件 verify (1 prompt × 13)
- `ckpt_health_check/` — quick_check_ckpt 出力 (PCM step 500 等)

**D. ファインチューニング dataset (現在進行中、~4800 枚予定)**:
- `finetune_raw/` — SFW v1 (60 themes × 16 seeds = 960)
- `finetune_raw_v2/` — SFW v2 (animal/mytho/sports 60×16 = 960)
- `finetune_raw_v3/` — SFW v3 (職業/世界観 60×16 = 960)
- `finetune_raw_nsfw/` — NSFW suggestive (30×16 = 480)
- `finetune_raw_explicit/` — EXPLICIT v1 (30×16 = 480)
- `finetune_raw_explicit_v2/` — EXPLICIT v2 #31-90 (60×16 = 960)

#### C. `anima-outputs` (~30 GB) — 訓練 LoRA / ckpt の保存先

mount: `/output`、create_if_missing=True

**完走 (preview3 起点)**:
- `traj_full/` — ① Z-Image final ($18)
- `dmd2_full/` — ② DMD2 final ($19)
- `reflow_full/` — ④ Reflow final ($13)
- `draftp_full/` — ⑩ DRaFT+ on Z final ($3)
- `draftp_on_turbo/` — B: DRaFT+ on Turbo final ($3)

**中断 / 部分 (preview3、~$80-100 浪費)**:
- `ladd_v2_fast/` — ③ LADD v2 step 500 ckpt まで
- `pcm_full/` — ⑤ PCM step 500 ckpt まで
- `sid_full/` — ⑦ SiD2 outer ~4200 まで (停止時)
- `traj_extended_8000/` — A: Z-Image extend (停止)
- `traj_rank128/` — E: rank 128 (停止)
- `shortcut_full/` — ⑦ Shortcut 異常遅延 step 500 まで ($63 損)

**旧 R3GAN 試行 (5 連続失敗の残骸)**:
- `distill/`, `distill_e/`, `distill_f/`, `distill_f_full/` — Phase A/B/C 試行

**smoke 各種**:
- `*_smoke/` — 各手法の smoke test 出力 (1-5 step、debug 用)

#### D. `comfyui-anima-models` (~5 GB) — user アップロード外部モデル

mount: `/comfyui_anima_models`、create_if_missing=**False** (user が事前アップロード)

```
diffusion_models/
  hakushiMixAnima_v02.safetensors      ← ファインチューニング用 base
loras/
  anima-highres-aesthetic-boost.safetensors ← ファインチューニング用 quality boost LoRA
text_encoders/, vae/                    ← 空 (将来用 placeholder)
```

ファインチューニング用 dataset 生成時に `/models/{checkpoints,loras}` へ symlink される
(`generate_finetune_chunk` 内で自動)。

#### 累計サイズ + コスト

| volume | 概算サイズ | 月額保管料 (Modal $0.15/GB/月) |
|---|---|---|
| anima-models | ~30 GB | ~$4.5 |
| anima-dataset | ~40 GB | ~$6 |
| anima-outputs | ~30 GB | ~$4.5 |
| comfyui-anima-models | ~5 GB | ~$0.75 |
| **合計** | **~105 GB** | **~$16/月** |

不要 dir は `cleanup_checkpoints` Modal function 等で適時間引きが推奨 (古い phase_a/b/c 系、
shortcut_full、放置 smoke 各種、要らない finetune subdir は数十 GB 占有してる)。

### 5.9.1 Anima 公式推奨 prompt / 推論設定 / ファインチューニング設定

[CircleStone Labs/Anima HF README](https://huggingface.co/circlestone-labs/Anima) から
抜粋した推奨設定。本リポジトリの全 workflow / generate_dataset / fine-tune script は
この推奨に準拠している。

**Prompt format**:

```
[quality/meta/year/safety] [1girl/1boy/etc] [character] [series] [@artist] [general]
```

- Quality prefix (positive 先頭): `masterpiece, best quality, score_7, safe`
- Negative: `worst quality, low quality, score_1, score_2, score_3, artist name`
- tag は **lowercase + space 区切り** (underscore は score タグだけ: `score_7`)
- Danbooru タグより **Gelbooru タグを優先**
- artist tag は **`@` プレフィックス必須** (なしだと効果激減)、`[artist]` 位置に置く
  - 多語 artist は半角 space (例: `@nnn yryr`)
  - 別解釈 disambiguator がある場合は paren escape (例: `@artist_name \(circle_name\)`)
  - 複数 artist を `,` 区切りで列挙可

**Recommended sampler / scheduler / CFG / steps**:

| 推奨 | 値 / 説明 |
|---|---|
| sampler | **`er_sde`** (中立、フラット彩色、シャープライン)、`euler_a` (柔らかめ、2.5D 傾向)、`dpmpp_2m_sde_gpu` (バラエティ豊か、暴走しがち) |
| scheduler | **`simple`** (デフォルト)、`beta57` (RES4LYF custom node、リアル系・絵画調用) |
| sigma_shift | **`3.0`** (`ModelSamplingAuraFlow` で必須、本リポジトリ全 workflow で設定済) |
| CFG | **4-5** |
| step | **30-50** |
| resolution | **512² から 1536²** までサポート (1024² 中心が無難) |
| VAE | `qwen_image_vae.safetensors` |
| Text encoder | `qwen_3_06b_base.safetensors` |
| Diffusion model | `anima-base-v1.0.safetensors` |

**Fine-tuning best practices** (Anima 公式抜粋):

- **`llm_adapter_lr = 0` 必須** — adapter は影響力が強く既知識を多く持つため訓練すると壊れる
  (本 repo `configs/phase1_anima.toml` で設定済)
- 低 LR start: rank 32 LoRA で **`lr = 2e-5`** から
- light touch training — モデルが既に多様な visual concept を持っているので無理に押し込まない
- captioning は **Danbooru tag + 自然言語の併用** OK
- 例: 公式 [style LoRA on Civitai](https://civitai.com/models/2536147) (dataset + config 公開)

**Content policy / restrictions**:

- safety tag: `safe / sensitive / nsfw / explicit` を positive / negative 両方で使い分ける
- text rendering は弱い (長文を画像に書かせない)
- 複数キャラ: character 名 → 基本属性の順で書くと混同回避
- prompt weighting は SDXL より強めに必要 (例: `(chibi:2)`)
- 自然言語 prompt は **最低 2 文以上** が安定 (極端に短いと予測不能)
- **非商用ライセンス縛り**、商用問い合わせ `tdrussell@circlestone.ai`

## 5.10 品質評価の方法論 (reward hacking 実証あり)

**「ディテール多い・彩度高い」≠「良い」**。蒸留 LoRA や reward fine-tuning の出力を評価
する際は、必ず以下の軸で分解して判断する:

| 評価軸 | 確認内容 |
|---|---|
| (a) **target style 維持** | anime 系を期待しているなら anime のままか? 西洋イラスト / リアル系にドリフトしていないか? |
| (b) **キャラクター固有要素の精度** | 例: Touhou Flandre Scarlet なら金髪+赤目+クリスタル翼、Remilia なら青髪+赤目+コウモリ翼 が正確か? |
| (c) **prompt adherence** | 指示したポーズ (例: hands raised pointing toward viewer with open palms)、構図、背景要素を反映しているか? |
| (d) **破綻ポイント** | 手指の本数・関節・方向、複数キャラの顔混じり、関節破綻、bad anatomy |
| (e) **生成時間** | per-image gen_time (`_summary.json` から)、step 数 × sampler × LoRA 構成で比較 |

**DRaFT+ HPSv2 reward fine-tuning の reward hacking 実証 (2026-05-17)**:

- 仮説: 公式 Anima Turbo に HPSv2 reward fine-tuning (DRaFT+ K=1 LV、kl_coeff=0.2、1500 step、
  $3) を後付けすれば品質が公式超えできる?
- 結果: HPSv2 score は **25.78 → 38.99 (+13.21)** と大幅向上 (loss 順調、KL 0.2-0.3 安定)
- **しかし視覚的には劣化** (ユーザー評価): 西洋イラスト風にドリフト、Flandre/Remilia の固有
  翼が曖昧化、両キャラの衣装がほぼ同じに、prompt の手のポーズが崩れる、装飾過多 (シャンデリア
  + ランプ + 飾り) でゴチャゴチャ
- 原因: HPSv2 は「人間が好きそうな generic な見栄え」preference を学習しており、Touhou anime
  style や character accuracy を直接最適化していない。reward が指す方向と用途が乖離した

教訓:
- **reward score 上昇 ≠ 品質向上**。reward 系は必ず視覚検証
- HPSv2 / PickScore / ImageReward 等は「平均的に綺麗」を上げるだけ、特定 niche style には不向き
- 蒸留 LoRA の評価では、必ず **「複数の評価軸を分解」して判定**。1 軸だけ (例: ディテール量)
  で判断しない
- 「score が上がった」「ディテールが増えた」を理由に勝者宣言しない、視覚的に必ず確認する

**verify 用 prompt の設計指針** ([scripts/verify_prompts.txt](../scripts/verify_prompts.txt)):

単純な single-character prompt では LoRA の差が出ない。**「壊れにくいもの」より「壊れやすい
もの」をテストする**:

- 複数キャラクター (face mix / 属性入れ替えが起きやすい)
- キャラ毎に異なる属性 (髪色、目色、翼種別)
- 手・指の特定ポーズ (open palms、pointing)
- 詳細背景 + foreground キャラ両立
- target style の制約 (anime style 維持を強制)

これで初めて LoRA 間の優劣が顕在化する。

## 5.11 次セッション引き継ぎ (2026-05-17 23:xx 中断時点)

> ⚠️ 2026-05-17 時点のスナップショット。**現在は v1.0 base で PCM が cold-start 完走済**
> ([darask0/anima-distill-loras/pcm](https://huggingface.co/darask0/anima-distill-loras/tree/main/pcm))。
> 本セクションは当時の状態を歴史記録として保持。

### 1. 完走済 (Anima preview3 base 起点、すべて使用可)

| LoRA | 出力 path | コスト |
|---|---|---|
| ① Z-Image traj imitation | `/output/traj_full/traj_final.safetensors` | $18 |
| ② DMD2 + TrigFlow | `/output/dmd2_full/dmd2_student_final.safetensors` | $19 |
| ④ Reflow rfpp | `/output/reflow_full/reflow_final.safetensors` | $13 |
| ⑩ DRaFT+ on ① Z-Image | `/output/draftp_full/draftp_final.safetensors` | $3 |
| B: DRaFT+ on Civitai Turbo | `/output/draftp_on_turbo/draftp_final.safetensors` | $3 ⚠️ reward hacking 検証で **品質劣化** 確認 |

### 2. 中断 (preview3 起点、user が「古いから止めて」と判断し全停止 2026-05-17)

| 手法 | 部分 ckpt | 中断時 step | 浪費コスト |
|---|---|---|---|
| ③ LADD v2 | `/output/ladd_v2_fast/ladd_student_step00500.safetensors` | ~500/5000 | ~$5 |
| ⑤ PCM | `/output/pcm_full/pcm_step00500.safetensors` | ~760/5000 | ~$30 |
| ⑦ SiD2 | `/output/sid_full/` (sample_every=500 で step ~4000 までの ckpt) | ~4200/5000 | ~$15 |
| ⑧ Shortcut | `/output/shortcut_full/shortcut_step00500.safetensors` | ~560/4000 (64s/step 異常遅延で abort) | $63 |
| A: Z-Image extend | `/output/traj_extended_8000/` (step ~1360 までの ckpt) | ~1360/6000 | ~$13 |
| E: rank 128 | `/output/traj_rank128/` (step ~1440 までの ckpt) | ~1440/2000 | ~$13 |

中断合計浪費: **~$139**。**ファイルは残してある**、user 判断で再開 or 削除。

### 3. ファインチューニング dataset (新規、hakushi base、ほぼ完成)

| subdir | safety | 完了状況 |
|---|---|---|
| `/dataset/finetune_raw/` | safe | ✅ 960 |
| `/dataset/finetune_raw_v2/` | safe | ✅ 960 |
| `/dataset/finetune_raw_v3/` | safe | ✅ 960 |
| `/dataset/finetune_raw_nsfw/` | nsfw | ✅ 480 |
| `/dataset/finetune_raw_explicit/` | explicit | ✅ 480 |
| `/dataset/finetune_raw_explicit_v2/` | explicit | ✅ 960 |
| **合計** | | ✅ **4800 / 4800 完成** |

訓練 prompt: `scripts/finetune_prompts*.txt`、artist tag は **秘密 ♥** (§5.8.1 参照)。

### 4. 次セッションで user 判断待ちのこと (最重要)

ファインチューニング dataset 完成後、**どちらに進むか user 判断**:

**Path A (推奨): ファインチューニング集中**
- `train_finetune_4variants` で 4 hyperparam 並列 (A: rank 32 lr 2e-5 / B: rank 64 lr 2e-5 / C: rank 32 lr 1e-5 epochs 4 / D: rank 32 lr 3e-5)
- 各 ~3-4h、計 ~$120
- 蒸留は公式 Anima Turbo に任せる (compare_z_vs_dmd2 で Turbo 圧勝が実証済)
- 自前 fine-tune LoRA × 公式 Turbo の **スタック** が現実解

**Path B: v1.0 base で蒸留 LoRA を再訓練**
- 既存の `/dataset/raw/` (preview3 self-distill) は base 違いで不適
- v1.0 base で self-distillation dataset 新規生成必要 (~$25)
- その後 5 蒸留手法を v1.0 で再訓練 (~$80-120)
- 計 ~$120-145
- 公式 Turbo に勝てる見込み低 (前回比較で実証)

**Path C: 両方やる**
- Path A 先行で完成見て、余力あれば Path B
- 計 ~$250-280

> **2026-05-18 update**: PCM を Path B 流に v1.0 base で cold-start 完走、
> HF 配布まで完了 ([詳細は HF model card](https://huggingface.co/darask0/anima-distill-loras/tree/main/pcm))。

### 5. 次 Claude が必ず守るルール

- **Artist tag は秘密** (§5.8.1)。Claude が prompt 生成で必要な場合、user に直接質問する。
  推測 / 履歴引用しない。`scripts/finetune_prompts*.txt` には実 tag が入ってるが README / chat
  出力では具体名を引用しない
- **Modal CLI on Windows 必須 prefix**: `MSYS_NO_PATHCONV=1 PYTHONIOENCODING=utf-8 PYTHONUTF8=1`
- **画像品質評価**: 「ディテール多い ≠ 良い」、必ず user judgment を仰ぐ (§5.10 reward hacking 実証)
- **workflow JSON node ID**: positive=5, latent=7, KSampler=8 (`generate_dataset.py::patch_workflow` が hardcode)
- **base 切替の影響**: preview3 LoRA を v1.0 で使うと style drift する (§5.7.1)
- **rank 違いの LoRA は warm-start 不可** (`load_warm_lora` で 0 keys matched エラー)、cold-start 必要
- **LADD discriminator bug fix**: `gradient_to_input` フラグ追加済、G phase は True、D phase は False
- **Modal function param は lowercase**: 大文字 `K: int` は Modal CLI で `k=1` に変換され抹消、`k_grad` などに
- **sageattention 有効**: `_base_image` に同梱、`generate_dataset.py` で auto-enable

### 6. 現コスト累計 + 予算

- 完走 LoRA + smoke + 失敗 retry + dataset: **~$200**
- 中断蒸留訓練の浪費: **~$139**
- 当初予算 $300 → **~$339 で +$39 超過**
- 推定 ファインチューニング 4 並列: +$120 → 完成時総額 ~$460
- user が「金は OK」と承認 (実コストは全部 Modal dashboard で監視可能)

### 7. 中断時 Modal で active な task

セッション終了時に bash background は全部止めてよい (Modal cloud は無影響)。
ただし Modal app は **app_stop コマンドで明示停止が必要** (止めないと課金続行):

```bash
modal app list                      # 全 app 確認
modal app stop <ap-xxxxx> --yes     # 個別停止
```

次セッション開始時は `modal app list` で再確認して、無駄に残った app が無いか確認推奨。
本セッション中断時には:
- 6 訓練 (LADD v2 / PCM / SiD2 / A / E / Shortcut) はすべて停止済
- dataset 生成: ✅ **全 6 subdir 4800 枚完成** (SFW v3 も 2026-05-17 終わり際で完了)
- 残 active task なし、Modal 課金は volume 保管料 ($16/月) のみ