Upload dmdx/README.md with huggingface_hub

dmdx/README.md

@@ -0,0 +1,134 @@
+---
+license: apache-2.0
+base_model: circlestone-labs/Anima
+tags:
+- lora
+- distillation
+- adversarial-distribution-matching
+- dmdx
+- adm
+- anime
+- text-to-image
+library_name: diffusers
+---
+
+# Anima v1.0 — DMDX (ADM) Distillation LoRA
+
+論文 [arxiv 2507.18569v1](https://arxiv.org/html/2507.18569v1) (ByteDance Seed Vision)
+の **ADM (Adversarial Distribution Matching)** を Anima v1.0 base に移植した蒸留 LoRA。
+
+DMD2 の逆 KL gradient trick を **学習可能 discriminator による hinge GAN (TVD 最小化)** に置換した手法。
+
+## ⚠ 重要な所見
+
+本実装は **warm-start (Civitai Anima Turbo) からほぼ移動しなかった**:
+- 5000 outer 訓練後の生成出力は warm-start Turbo とほぼ視覚的に同等
+- GAN dynamics は健全 (D vs G 振動、mean collapse なし)
+- ただし student LoRA の重みは保守的に推移、独自の蒸留方向を獲得できず
+
+**結論**: 本 LoRA は実質的に "Anima Turbo + 軽い ADM 訓練" の状態。Civitai Turbo を直接使うのと品質に有意差なし。研究目的・記録のため配布。
+
+詳細な技術解説は [docs/dmdx.md](https://huggingface.co/darask0/rapid-anima/blob/main/docs/dmdx.md)、warm-start dominance に至った推測原因は本ドキュメント末尾の「改善方向」参照。
+
+## Files
+
+| File | Format | Use |
+|---|---|---|
+| `dmdx_final_peft.safetensors` | PEFT (diffusers) | `peft` library / 自前推論スクリプト |
+| `dmdx_final_comfy.safetensors` | ComfyUI LoRA | ComfyUI で直接ロード |
+
+両者は同一の重み。
+
+## Usage (ComfyUI)
+
+1. `dmdx_final_comfy.safetensors` を `ComfyUI/models/loras/` に配置
+2. Anima v1.0 base workflow に `LoraLoaderModelOnly` を挿入、`strength_model: 1.0`
+3. `ModelSamplingAuraFlow` で `sigma_shift: 3.0`
+4. KSampler:
+   - **steps: 4**
+   - **cfg: 1.0**
+   - sampler: **`er_sde`**
+   - scheduler: **`simple`**
+
+## Training Details
+
+| 項目 | 値 |
+|---|---|
+| Base model | `anima-base-v1.0.safetensors` (circlestone-labs/Anima) |
+| Method | DMDX ADM-only (arxiv 2507.18569v1 移植、ADP 省略) |
+| Discriminator | LADD-style (teacher MiniTrainDIT frozen + spectral norm heads、5 hook) |
+| Student LoRA | wide (AdaLN + attn + MLP の全 Linear、980 keys、rank 32) |
+| Total outer | 5000 (1 outer = 2 disc + 1 generator) |
+| n_critic_per_gen | 2 (hinge GAN は 1:1〜2:1 が一般的) |
+| n_student_steps | 4 (deploy target に一致) |
+| dt_ratio (Δt) | 1/64 (paper default) |
+| Time schedule | **cubic high-noise bias** (`t = 1 - u**3`、u~U(0,1)) |
+| Teacher CFG | 4.5 (Anima 公式推奨) |
+| Student CFG | 1.0 (CFG embedded) |
+| recon_weight | 0.0 (pure ADM、Smooth-L1 anchor なし) |
+| LR (gen / disc) | 5e-6 / 1e-5 |
+| Warm-start | **Civitai Anima Turbo** (968/1016 keys match、x/t embedder skip) |
+| Hardware | NVIDIA B200 |
+| Training time | ~4.3h (3.59s/outer、並列 DMD2 と同時実行) |
+| Cost | ~$27 (Modal) |
+
+### GAN dynamics (loss 推移)
+
+```
+outer    0: l_d_real=0.72  l_d_fake=1.30  l_g_adv=-0.29  (初期)
+outer  500: 0.82  0.98  -0.15  (G slightly winning)
+outer 1500: 0.31  0.90  +0.08  (D dominant、l_g_adv +0.5 ピーク)
+outer 2500: 0.95  0.57  +0.47  (D dominance peak)
+outer 3500: 1.31  0.53  -0.46  (G recovers!)
+outer 4500: 1.12  0.52  +0.25  (mild D-favor)
+outer 5000: similar to 4500
+```
+
+典型的な GAN 振動。`l_d_total` は 1.21-2.02 範囲で healthy equilibrium、divergence なし。
+
+### Implementation files
+
+- `scripts/distill/dmdx_loss.py` — ADM loss、cubic time sampling、teacher Δt evolution
+- `scripts/distill/train_dmdx.py` — 訓練ループ (DMD2 風 outer / inner 構造)
+- `modal_app.py::train_dmdx_distill` — Modal entry
+
+ソースは [darask0/rapid-anima](https://huggingface.co/darask0/rapid-anima) / [github.com/daraskme/rapid-anima](https://github.com/daraskme/rapid-anima) 参照。
+
+## サンプル比較 (4-step / CFG=1.0 / er_sde + simple)
+
+同 prompt (Touhou Flandre + Remilia)、同 seed=42、Anima v1.0 base。
+
+| Civitai Anima Turbo (warm-start) | DMDX final (5000 outer) |
+|---|---|
+| ![turbo](samples/turbo_baseline.png) | ![dmdx_final](samples/dmdx_final.png) |
+
+→ **視覚的に同一**。DMDX 訓練の影響は微小、warm-start anchor が支配。
+
+## 推測される改善方向 (将来検討)
+
+1. **cold-start** — warm-start を外して DMDX 単独で蒸留 (リスク: 不安定化、ただし独自性は出る)
+2. **lr_gen 引き上げ** (5e-6 → 2e-5) — G の更新を加速
+3. **recon_weight=0.5** — LADD 流 Smooth-L1 anchor で teacher x0 に近づける軌道制御
+4. **lower n_critic** (2 → 1) — D の優勢を抑え G に更新機会
+5. **論文の ADP 移植** — SAM ベース pixel-space discriminator 追加 (実装重い、+$300-500、本 repo では省略)
+
+## License
+
+Apache-2.0
+
+Base model (Anima v1.0) のライセンスも適用:
+[circlestone-labs/Anima](https://huggingface.co/circlestone-labs/Anima)
+- CircleStone Labs Non-Commercial License
+- NVIDIA Open Model License (Derivative Model 条項)
+- **非商用利用のみ**
+
+## Citation
+
+```bibtex
+@article{lu2025adversarial,
+  title={Adversarial Distribution Matching for Diffusion Distillation Towards Efficient Image and Video Synthesis},
+  author={Lu, Yanzuo and Ren, Yuxi and Xia, Xin and others},
+  journal={arXiv preprint arXiv:2507.18569},
+  year={2025}
+}
+```