docs/workflow.md

# 実行手順 + GPU + コスト概算

[← README に戻る](../README.md) — 前提: [setup.md](setup.md)

## Step 0: モデルダウンロード(初回のみ)

```bash
cd anima_modal
modal run modal_app.py::download_models
```

`anima-preview3-base.safetensors` (4.18GB) + Qwen3 + VAE が
`anima-models` Volume に保存される。

## Step 1: データセットを用意

### 1a. self-distillation で自動生成(おすすめ、約 11h / $28)

Anima base 自身に生成させて quality タグ依存性を消す pair を作る。
[scripts/gen_prompts.txt](../scripts/gen_prompts.txt) の 100 プロンプト × 50 seed で
5,000 枚生成。クライアント側でデータ用意不要。

```bash
# 試走: ComfyUI 起動 + 10 枚生成 (~10分, $0.10)
modal run modal_app.py::generate_dataset --max-images 10

# 本番(シリアル A100): 5,000 枚 (12.5h, $31)
modal run --detach modal_app.py::generate_dataset

# 本番(B200 × 10 並列): 5,000 枚 (~40分, $44)  ← 速度優先
modal run --detach modal_app.py::generate_dataset_parallel

# パラメータ調整可
modal run --detach modal_app.py::generate_dataset \
    --seeds-per-prompt 80 --max-images 8000

# 途中から再開 (既存 .png はスキップ)
modal run --detach modal_app.py::generate_dataset --start-from 50
```

ワークフローは [scripts/anima_workflow.json](../scripts/anima_workflow.json)、
**Anima 公式 README の推奨設定**:
- Sampler: `er_sde` / Scheduler: `simple` / Steps: 30 / CFG: 4.5
- ModelSamplingAuraFlow shift: 3.0 (公式 `anima_comparison.json` 由来)
- Positive prefix: `masterpiece, best quality, score_7, safe`
- Negative: `worst quality, low quality, score_1, score_2, score_3, artist name`
- タグ順: `[quality/meta/safety] [1girl/1boy] [character] [series] [artist] [general]`

### 1b. ローカル画像を持ち込み

```bash
modal volume put anima-dataset ./my_images /raw
```

`/dataset/raw/` 以下に展開される。

## Step 2: キャプションを掃除

このプロジェクトの Phase 1 は審美シフトではないので **artist タグは残す**:

```bash
modal run modal_app.py::clean_captions
```

artist タグを drop するオプションは「Anima 平均スタイル化」用で、
今回の目的(タグ依存性除去のみ)では基本不要:

```bash
# 必要なら確率 drop / 完全 drop も可能
modal run modal_app.py::clean_captions --drop-artist-prob 0.5
modal run modal_app.py::clean_captions --keep-artist false
```

`/dataset/cleaned/` に処理後の画像と .txt が出る。中を確認:

```bash
modal volume get anima-dataset cleaned/0001.txt
```

`masterpiece, best quality, score_9, year 2025, newest, highres, safe`
が綺麗に消えていればOK。

## Step 3: Phase 1 学習(quality タグ依存性除去)

```bash
modal run --detach modal_app.py::train_phase1
```

`--detach` で**バックグラウンド実行**(数時間続くため)。
Modal ダッシュボード(modal.com/apps)で進捗確認できる。

**目安時間 (A100-80GB)**:
| データセット | 1 epoch | 2 epoch | コスト |
|---|---|---|---|
| 3,000 枚 | 2 h | 4 h | **$10** |
| 5,000 枚 | 3 h | 6-7 h | **$15-18** |
| 10,000 枚 | 6-7 h | 12-14 h | **$30-35** |

デフォルトは `epochs = 2`(prior shift には十分)。H100 にすれば 1.4-1.6x 速い。

**設定変更したい時**: `configs/phase1_anima.toml` を編集して
`modal run` を再実行(Modal が image を rebuild する)。

主な調整点:
- `epochs`: 試走 1、デフォルト 2、念のため 3 まで
  (それ以上は base 性能を損なうリスク)
- `[optimizer].lr`: 1e-5 → 効きが弱ければ 2e-5
- `[adapter].rank`: 32-64 で十分(概念追加でないので大きくしても無駄)
- `gradient_accumulation_steps`: 5k 枚以下なら 2 で十分

## Step 4: Phase 1 結果の検証

```bash
modal run modal_app.py::generate_samples
```

`scripts/eval_prompts.txt` の短い「品質タグなし」プロンプトで生成して
`/output/phase1_samples/` に保存。
※ 現状は ComfyUI ベースで生成するスケルトンなので、本番では
ComfyUI を Modal の別 function で立てて API 経由で呼ぶ構成を別途追加することを想定。

## Step 5: Phase 2 蒸留

**数万円予算なら 5a (merge) を強く推奨**。5b/5c は数十時間の試行錯誤前提。

### 5a. Turbo LoRA との weight merge (即動く、$0.5、10分)

```bash
# Civitai の Turbo LoRA URL を指定して 1 ファイルに合成
modal run modal_app.py::merge_turbo_lora \
    --turbo-url "https://civitai.com/api/download/models/<id>"

# alpha 調整 (デフォルトはどちらも 1.0)
modal run modal_app.py::merge_turbo_lora \
    --turbo-url "..." --alpha-phase1 1.0 --alpha-turbo 0.8
```

候補の Turbo LoRA:
- 公式 Anima Turbo: https://civitai.com/models/2560840 (CFG=1, 8-12 step)
- RDBT-Anima (DMD2 蒸留先行例): https://civitai.com/models/2364703

出力は `/output/merged/anima_phase1_plus_turbo.safetensors` (LoRA だけの
ファイル)。ComfyUI で base + この LoRA を組めば即推論可能。

### 5b. SOTA 自前蒸留(Decoupled DMD2 + TSCD + R3GAN、B200 — **未完成、要追加開発**)

`scripts/distill/` に実装あり。**ただし 5 回試行して全て失敗**。詳細は
[distillation.md](distillation.md) を参照。これから取り組む人は、まず
そのドキュメントの §1.1 / §4 / §5 を読むことを強く推奨。

```bash
# (動くが収束しない) 我々が試したコマンド:
modal run --detach modal_app.py::generate_dataset_parallel  # データ生成 $44
modal run --detach modal_app.py::train_sota_distill --phase b --total-steps 2000  # 失敗
```

> **強い推奨**: 商用要件なしなら 5a で十分。Anima の Turbo LoRA は **CircleStone
> Labs 公式** が **遥かに多い計算資源と試行錯誤** で作っており、数万円の予算で
> これを超える自前蒸留は現実的に困難。

## GPU の選び方

| GPU | Modal 料金 | 速度 | 推奨用途 |
|---|---|---|---|
| A100-40GB | $2.10/hr | 遅 | OOM のリスク。非推奨 |
| **A100-80GB** | **$2.50/hr** | 標準 | **Phase 1 デフォルト** |
| L40S 48GB | $1.95/hr | やや遅 | Phase 1 試走に使える |
| H100 80GB | $3.95/hr | 1.4-1.6x 速 | 時間最優先 / Phase 2 DMD2 |
| H200 | H100 と同額 | さらに速 | Modal が自動で割り当てる場合あり |

`modal_app.py` の `gpu="A100-80GB"` を書き換えるだけで切替可能。

## コスト概算 (1USD ≒ 150円換算)

### プラン A: ミニマム検証 (約 5,000円 / $33)

| 項目 | 想定 | コスト |
|---|---|---|
| Modal Volume | 10GB × 1ヶ月 | $0.90 |
| モデル DL (CPU 並列) | 5-10 分 | $0.01 |
| キャプション掃除 (CPU) | 5 分 | ~$0.00 |
| Phase 1 学習 (A100-80GB, 2,000枚 × 3 epoch) | 8 時間 | $20 |
| 検証生成 (L40S) | 10 分 | $0.30 |
| Phase 2 merge | 10 分 | $0.50 |
| 余裕枠 (失敗 retry 1 回ぶん) | | ~$10 |
| **合計** | | **~$32** |

### プラン B: スタンダード (約 1〜1.2万円 / $70-80)

| 項目 | 想定 | コスト |
|---|---|---|
| Modal Volume | 20GB × 1ヶ月 | $1.80 |
| **Phase 1 (A100-80GB, 10,000枚 × 3 epoch)** | 18-21 時間 | **$45-53** |
| 検証 + merge + 試行 retry | | ~$5 |
| 余裕 | | ~$15 |
| **合計** | | **~$70** |

### プラン C: 余裕プラン / 蒸留も自前 (約 3〜4万円 / $200-270)

| 項目 | 想定 | コスト |
|---|---|---|
| Phase 1 (A100-80GB, 10k × 5 epoch) | 30-35 時間 | $75-88 |
| Phase 2 LCM 自前蒸留 (A100, 試行2回) | 20 時間 | $50 |
| ↑ DMD2 にする場合 (H100, 試行1回) | 15 時間 | $60 |
| Volume + 検証 + 余裕 | | ~$30 |
| **合計** | | **$200-270** |

> ⚠️ `--detach` で背景実行中も課金は続く。`modal app stop rapid-anima` で
> 即停止できるので、想定時間を超えたら必ず確認。`cleanup_checkpoints` で
> Volume 課金 ($0.15/GB/月) も適時間引き。