README.md

# rapid_anima — Anima 生成速度向上 on Modal

CircleStone Labs の [Anima](https://huggingface.co/circlestone-labs/Anima)
(2B パラメータの DiT)の **生成速度を改善** するための一式。
旧名 `darask_anima`、2026-05 にスコープを「fine-tune + 蒸留」から「速度向上特化」に転換。

> ⚠️ **ライセンス**: Anima は CircleStone Labs Non-Commercial License +
> NVIDIA Open Model License (Derivative Model 条項) で **非商用のみ**。
> 派生モデルも非商用縛り。詳細は [末尾のライセンス節](#ライセンス) 参照。

## 主な高速化レバー

- **B200 sageattention 実 engage** — sm_100 patched wheel で silent fallback 回避
  ([darask0/modal_B200_sageattetion_comfyUI](https://huggingface.co/darask0/modal_B200_sageattetion_comfyUI))
- **batch=8 並列生成** — ComfyUI EmptyLatentImage 経由で 1 submit に 8 枚
- **蒸留 LoRA** — Civitai 公式 Anima Turbo merge / 自前蒸留 (PCM, Z-Image traj, LADD, Reflow)
- **ComfyUI 推論最適化** — CapitanFlowMatch scheduler, sageattention, DPM-Solver++ 等

### 実測 (B200, 1024² / 30 step)

| 構成 | per-image | 5000 枚 cost |
|---|---|---|
| 旧 batch=1 (no sage) | ~3.3s | ~$44 |
| **新 batch=8 + sage** | **~3.05s** | **~$26** |
| 4-step 蒸留 LoRA + sage | ~0.5-1s | (推論時のみ) |

## 配布中の LoRA

[**huggingface.co/darask0/anima-distill-loras**](https://huggingface.co/darask0/anima-distill-loras)
に Anima v1.0 base 用の蒸留 LoRA を集約 (PEFT + ComfyUI 両形式)。

> ⚠️ **重要**: 以下 LoRA はすべて **実用品質が公式 Civitai Anima Turbo に及ばず**、
> 研究 / 学習目的での配布。実用は **公式 [Civitai Anima Turbo](https://civitai.com/models/2560840)** を推奨。

| サブディレクトリ | 手法 | step / CFG | ステータス | 詳細 |
|---|---|---|---|---|
| [`pcm/`](https://huggingface.co/darask0/anima-distill-loras/tree/main/pcm) | Phased Consistency Model | 4-step / CFG=1.0 | ❌ **非推奨** (cold-start、生成品質が低い) | [docs/pcm.md](docs/pcm.md) |
| [`dmdx/`](https://huggingface.co/darask0/anima-distill-loras/tree/main/dmdx) | DMDX (ADM) | 4-step / CFG=1.0 | ⚠️ 配布中 (warm-start dominance、Turbo と視覚同等、独自性なし) | [docs/dmdx.md](docs/dmdx.md) |
| [`dmd2/`](https://huggingface.co/darask0/anima-distill-loras/tree/main/dmd2) | DMD2 + TrigFlow | 4-step / CFG=1.0 | ⚠️ 配布中 (DMDX 同様の warm-start dominance) | [docs/dmd2.md](docs/dmd2.md) |

将来追加検討: LADD / Reflow / Z-Image trajectory / SiD2 など。

**ComfyUI 使い方の最短手順**:

1. `*_comfy.safetensors` を `ComfyUI/models/loras/` に配置
2. Anima v1.0 base workflow に `LoraLoaderModelOnly` を挿入、`strength_model: 1.0`
3. KSampler を **steps=4 / cfg=1.0**、推奨 sampler / scheduler を選択

詳細な使い方・訓練詳細は各 LoRA の HF model card / docs/{pcm,dmd2,dmdx}.md を参照。

### サンプル画像 (4-step / CFG=1.0 / er_sde + simple)

同 prompt (`2girls, flandre scarlet, remilia scarlet, touhou, ...`)、同 seed=42、Anima v1.0 base。

| Civitai Anima Turbo (baseline) | DMD2 final | DMDX final |
|---|---|---|
| ![turbo](samples/turbo_baseline.png) | ![dmd2_final](samples/dmd2_final.png) | ![dmdx_final](samples/dmdx_final.png) |

**主要な発見**:
- **DMD2 / DMDX いずれも warm-start (Civitai Turbo) からほぼ移動せず**、視覚的に Turbo と同等。手法による差なし
- **PCM** (cold-start) は別 trajectory に乗っているが **生成品質が低い** — Anima Turbo / DMD2 / DMDX に劣る ❌ 非推奨
- 教訓: **「numerical 収束 ≠ 生成品質」**。loss が健全でも visual で要検証 ([distillation.md §4](docs/distillation.md) の Phase A 失敗と同根)
- 核心の結論: 本データセット規模 (5000 サンプル) + 標準ハイパラでは Civitai Anima Turbo を超えるのは困難、**実用は公式 Turbo 推奨**

## ディレクトリ構成 (簡略)

```
rapid_anima/
├── modal_app.py                  # Modal アプリ本体 (全 function 定義)
├── configs/                      # diffusion-pipe 設定 (Phase 1 fine-tune 用)
├── scripts/
│   ├── generate_dataset.py       # ComfyUI 経由 self-distill 生成
│   ├── clean_captions.py         # quality/meta タグ除去
│   ├── *_workflow.json           # Anima ComfyUI workflow テンプレ
│   ├── *_prompts.txt             # 各種 prompt セット
│   └── distill/                  # 蒸留実装 (PCM / DMD2 / DMDX / LADD / Reflow / Z-Image 等)
├── docs/                         # 詳細ドキュメント (下記参照)
├── samples/                      # README 用検証サンプル画像
├── requirements.txt
└── README.md (このファイル)
```

> **重要**: `modal_app.py` は `configs/` と `scripts/` をそのままの構造で
> image に同梱する。ファイルをルート直下にフラット配置すると `add_local_dir`
> で失敗するので注意。

## ドキュメント

**手法別** (本日 v1.0 base での新規試行):

| ドキュメント | 内容 |
|---|---|
| [docs/pcm.md](docs/pcm.md) | PCM 蒸留 (5000 step 完走、HF 配布済、$22) |
| [docs/dmd2.md](docs/dmd2.md) | DMD2 + TrigFlow 蒸留 (resume 進行中、~$50) |
| [docs/dmdx.md](docs/dmdx.md) | DMDX (ADM、新規実装、arxiv 2507.18569v1 移植、進行中、$30) |

**インフラ / セットアップ**:

| ドキュメント | 内容 |
|---|---|
| [docs/setup.md](docs/setup.md) | Modal セットアップ、HF シークレット、データセット用意 |
| [docs/workflow.md](docs/workflow.md) | Step 0-5 (モデル DL / dataset / Phase 1 / 検証 / 蒸留)、GPU 選び、コスト概算 |
| [docs/distillation.md](docs/distillation.md) | Anima 蒸留 — R3GAN 5 連続失敗の deep dive、設計理由、教訓 |
| [docs/migration_log.md](docs/migration_log.md) | 2026-05 既存実装移植 (Z-Image / DMD2 / LADD / Reflow / PCM)、比較結果、reward hacking 実証 |
| [docs/operations.md](docs/operations.md) | Modal CLI / diffusion-pipe 罠、実測コスト、トラブルシューティング |

## 参考資料

- 公式モデルカード: https://huggingface.co/circlestone-labs/Anima
- diffusion-pipe: https://github.com/tdrussell/diffusion-pipe
- DMD2 論文 (Z-Image): https://arxiv.org/abs/2511.22677
- LCM 論文: https://arxiv.org/abs/2310.04378
- Hyper-SD: https://github.com/bytedance/hyper-sd
- RDBT-Anima (Anima 蒸留先行例): https://civitai.com/models/2364703
- PCM 元論文: [Wang et al. NeurIPS 2024](https://arxiv.org/abs/2405.18407) / [G-U-N/Phased-Consistency-Model](https://github.com/G-U-N/Phased-Consistency-Model)

## ライセンス

このリポジトリ自体のコードは MIT で公開。生成される派生モデル(蒸留 LoRA や
fine-tune 結果)は **Anima のライセンス** に従う必要があり、**非商用のみ**:

- CircleStone Labs Non-Commercial License
- NVIDIA Open Model License(Derivative Model 条項)

詳細・商用利用問い合わせは Anima 公式ページを参照:
https://huggingface.co/circlestone-labs/Anima