diff --git a/docs/index.md b/docs/index.md index 2e5b7596..4666779c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,7 +37,8 @@ reproducible. ## Supported models -Each model name links to its recipe page. +Each model name links to its recipe page. Every documented recipe is labeled with a +[recipe verification level](/user-guide/recipe-verification). | Model | Task | Canonical recipes | @@ -54,8 +55,8 @@ Each model name links to its recipe page. ## Feature support matrix -- ✅ **Verified** — exercised by a canonical recipe in `scripts/` or a CI test. -- 🟡 **Supported** — the code path exists, but no shipped recipe or test covers this combination yet. +- ✅ **Recipe-backed** — exercised by a canonical recipe in `scripts/` or a CI test. +- 🟡 **Implemented** — the code path exists, but no shipped recipe or test covers this combination yet. - ❌ **Not supported** — no working code path for this combination today. @@ -67,7 +68,7 @@ Each model name links to its recipe page. | LoRA + IPC weight sync | ✅ | ✅ | ✅ | 🟡 | ✅ | | Single-prompt multi-gen (microgroup > 1) | ✅ | ✅ | ✅ | ❌ | ❌ | | USP sequence parallelism | ❌ | ❌ | ✅ | ❌ | ❌ | -| Deterministic mode | ✅ | ✅ | ❌ | ✅ | ❌ | +| Deterministic mode | ✅ | ✅ | ✅ | ✅ | ❌ | diff --git a/docs/models/cosmos/cosmos3.md b/docs/models/cosmos/cosmos3.md index 422e12b7..726920e6 100644 --- a/docs/models/cosmos/cosmos3.md +++ b/docs/models/cosmos/cosmos3.md @@ -55,28 +55,33 @@ From `miles/backends/fsdp_utils/configs/cosmos3.py`: ## 4. Launch -Canonical recipe: `scripts/run_diffusion_grpo_cosmos3_pickscore_t2i_5gpu.py` — 4 colocate + 1 reward GPU, T2I (832×480, -1 frame), PickScore reward. +Canonical recipe: `scripts/run_diffusion_grpo_cosmos3_pickscore_t2i_4gpu.py` — train, rollout, +and PickScore colocated on 4 GPUs; T2I (832×480, 1 frame). + +**Status:** [📈 V — Verified](/user-guide/recipe-verification#v) ```bash export SGLANG_DISABLE_COSMOS3_GUARDRAILS=1 # RL scores raw samples; skip serving-side guardrail models -python3 scripts/run_diffusion_grpo_cosmos3_pickscore_t2i_5gpu.py +python3 scripts/run_diffusion_grpo_cosmos3_pickscore_t2i_4gpu.py ``` -## 5. Recipe Note -`epoch_global_window` draws a 2-step window per rollout from `--diffusion-sde-candidate-steps 4-15`. +## 5. Recipe notes + +`epoch_global_random_choice` draws two steps per epoch from +`--diffusion-sde-candidate-steps 8,9,10,11`. -The Cosmos3 checkpoint's Karras flow-sigma grid puts head steps 1–3 at `sigma > 0.96` with `|dt| < 0.02` — they -basically train nothing. Step numbers are **not transferable across sigma-grid families**: re-derive candidates from -`|dt|` when changing model or grid. +The Cosmos3 checkpoint's Karras flow-sigma grid puts head steps 1–7 at +`sigma > 0.96` with `|dt| < 0.02`; steps 8–11 are the useful high-noise segment. +Step numbers are **not transferable across sigma-grid families**: re-derive candidates +from `|dt|` when changing model or grid. ## 6. Reference results -Flow-GRPO + PickScore on Cosmos3-Nano, run with the native Cosmos3 recipe scripts in this repo. PickScore -(`rollout/reward/raw_mean`) climbs from ~0.77 to ~0.85 over 250 rollout steps: +The 4-GPU colocated Cosmos3-Nano recipe raises PickScore +(`rollout/reward/raw_mean`) from ~0.77 to ~0.85 over 250 rollouts: ![Cosmos3 PickScore reward mean](../../assets/images/cosmos3/reward_mean.png) diff --git a/docs/models/h3/h3.md b/docs/models/h3/h3.md index 986aea1d..a25863dd 100644 --- a/docs/models/h3/h3.md +++ b/docs/models/h3/h3.md @@ -60,6 +60,8 @@ The 2-GPU recipe lives on [PR #154](https://github.com/radixark/miles_diffusion/ (sglang pins `short_edge=768`, so the canvas is 1344×768 / 107 frames). Requires `--use-lora --lora-ipc-weight-sync` (the recipe already sets both). +**Status:** [📈 V — Verified](/user-guide/recipe-verification#v) + ```bash # alignment check (optimizer frozen) python3 scripts/run_diffusion_grpo_h3_t2va_2gpu.py \ diff --git a/docs/models/ltx/ltx2.md b/docs/models/ltx/ltx2.md index 1e905e37..21502ea3 100644 --- a/docs/models/ltx/ltx2.md +++ b/docs/models/ltx/ltx2.md @@ -48,6 +48,8 @@ Registered in `miles/backends/fsdp_utils/configs/ltx.py`: Canonical recipe: `scripts/run_diffusion_grpo_ltx23_sglang.py` — 4 colocate GPUs + 1 PickScore GPU, 57 frames @ 24 fps, 512×768, PickScore reward. +**Status:** [🛡️ FG — Fully gated](/user-guide/recipe-verification#fg) + ```bash python3 scripts/run_diffusion_grpo_ltx23_sglang.py ``` diff --git a/docs/models/qwen-image/qwen-image.md b/docs/models/qwen-image/qwen-image.md index e4fdcf2c..c0d084f5 100644 --- a/docs/models/qwen-image/qwen-image.md +++ b/docs/models/qwen-image/qwen-image.md @@ -48,6 +48,8 @@ Registered in `miles/backends/fsdp_utils/configs/qwen_image.py`: Canonical recipe: `scripts/run_diffusion_grpo_pickscore_5gpu_flowgrpo_aligned.py` — 4 colocate GPUs + 1 PickScore GPU, 512×512, PickScore reward. +**Status:** [📈 V — Verified](/user-guide/recipe-verification#v) + ```bash python3 scripts/run_diffusion_grpo_pickscore_5gpu_flowgrpo_aligned.py ``` diff --git a/docs/models/sd3/sd3.md b/docs/models/sd3/sd3.md index 56f11828..927ed97a 100644 --- a/docs/models/sd3/sd3.md +++ b/docs/models/sd3/sd3.md @@ -108,6 +108,8 @@ All recipes are Python modules under `scripts/`. Each exposes a Typer CLI Canonical script: `scripts/run_diffusion_grpo_sd3_ocr_sglang.py` +**Status:** [🛡️ FG — Fully gated](/user-guide/recipe-verification#fg) + ```bash export HF_TOKEN=... python3 scripts/run_diffusion_grpo_sd3_ocr_sglang.py \ @@ -125,6 +127,8 @@ E2E test: `tests/e2e/short/test_sd3_ocr_grpo_2xGPU.py`. Script: `scripts/run_diffusion_nft_sd3_pickscore.py` +**Status:** [📈 V — Verified](/user-guide/recipe-verification#v) + ```bash export HF_TOKEN=... python3 scripts/run_diffusion_nft_sd3_pickscore.py \ diff --git a/docs/models/wan/wan2-2.md b/docs/models/wan/wan2-2.md index 12e6e412..42437193 100644 --- a/docs/models/wan/wan2-2.md +++ b/docs/models/wan/wan2-2.md @@ -46,6 +46,8 @@ Registered in `miles/backends/fsdp_utils/configs/wan2_2.py`: Canonical recipe: `scripts/run_diffusion_grpo_wan22_pickscore_5gpu.py` +**Status:** [○ NV — Not verified](/user-guide/recipe-verification#nv) + ```bash python3 scripts/run_diffusion_grpo_wan22_pickscore_5gpu.py ``` @@ -57,6 +59,8 @@ Recipe: `scripts/run_diffusion_grpo_wan22_pickscore_17gpu_multinode.py` (full finetune, no LoRA, true on-policy). Start the [multi-node Ray cluster](/user-guide/launch-script#multi-node-training), then run on the head node: +**Status:** [🧩 PG — Proxy gated](/user-guide/recipe-verification#pg) + ```bash MILES_SCRIPT_EXTERNAL_RAY=1 python3 scripts/run_diffusion_grpo_wan22_pickscore_17gpu_multinode.py ``` @@ -67,6 +71,8 @@ MILES_SCRIPT_EXTERNAL_RAY=1 python3 scripts/run_diffusion_grpo_wan22_pickscore_1 Recipe: `scripts/run_diffusion_sft_wan22.py` +**Status:** [○ NV — Not verified](/user-guide/recipe-verification#nv) + ```bash MILES_SCRIPT_DATA_JSONL=/abs/data.jsonl python3 scripts/run_diffusion_sft_wan22.py ``` diff --git a/docs/user-guide/recipe-verification.md b/docs/user-guide/recipe-verification.md new file mode 100644 index 00000000..3e760ad5 --- /dev/null +++ b/docs/user-guide/recipe-verification.md @@ -0,0 +1,54 @@ +--- +title: Recipe Verification Levels +description: Evidence levels for documented training recipes. +--- +# Recipe verification levels + +Every recipe is assigned one evidence level. The level applies to the exact script and +topology named in the model guide, not to the model family as a whole. + + +## 🛡️ FG — Fully gated + +- A complete training curve has been run. +- Deterministic E2E CI runs the canonical recipe itself for two rollouts. +- Every registered metric matches the committed standard exactly. + + +## 🧩 PG — Proxy gated + +- A complete training curve has been run. +- Deterministic E2E CI runs a documented, scaled single-node proxy for two rollouts. +- Every registered metric matches the committed standard exactly. + + +## 📈 V — Verified + +A complete training curve has been run, but the recipe has no E2E CI gate. + + +## ○ NV — Not verified + +No complete training curve has been run. Smoke tests and short debugging runs do not +count as verification. + +## Current levels + +- **🛡️ FG** + - `run_diffusion_grpo_sd3_ocr_sglang.py` — SD3.5 Flow-GRPO + OCR. + - `run_diffusion_grpo_ltx23_sglang.py` — LTX-2.3 Flow-GRPO + PickScore. +- **🧩 PG** + - `run_diffusion_grpo_wan22_pickscore_17gpu_multinode.py` — Wan2.2 17-GPU + full-finetune Flow-GRPO + PickScore. +- **📈 V** + - `run_diffusion_nft_sd3_pickscore.py` — SD3.5 DiffusionNFT + PickScore. + - `run_diffusion_grpo_pickscore_5gpu_flowgrpo_aligned.py` — Qwen-Image + Flow-GRPO + PickScore. + - `run_diffusion_grpo_cosmos3_pickscore_t2i_4gpu.py` — Cosmos3-Nano + Flow-GRPO + PickScore. + - `run_diffusion_grpo_h3_t2va_2gpu.py` — MiniMax H3 Flow-GRPO + PickScore + ([implementation PR #154](https://github.com/radixark/miles_diffusion/pull/154)). +- **○ NV** + - `run_diffusion_grpo_wan22_pickscore_5gpu.py` — Wan2.2 5-GPU LoRA + Flow-GRPO + PickScore. + - `run_diffusion_sft_wan22.py` — Wan2.2 4-GPU LoRA SFT.