@@ -4,7 +4,7 @@ created: 2026-07-20
44updated : 2026-08-23
55type : rule
66tags : [vllm-omni, components, diffusion]
7- sources : ["PR # 4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", "PR #6094", "PR #6385", "PR #6445", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py]
7+ sources : ["PR # 4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", "PR #5543", "PR #5848", "PR #5872", "PR #5981", "PR # 6094", "PR #6102", "PR #6279 ", "PR #6385", "PR #6445", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py]
88confidence : high
99---
1010
@@ -20,23 +20,23 @@ confidence: high
2020
2121| PR 描述在做什么 | 精确规则组 | 第一批 live 源码 |
2222| ---| ---| ---|
23- | CUDA Graph、compile、fused scheduler/ solver、cache path、 eager parity | ` execution-parity ` ：` DIFF-1a ` | ` compile.py::regionally_compile ` → ` diffusion_model_runner.py::{execute_model,execute_model_batch} ` → model denoise/solver |
23+ | CUDA Graph、compile、fused solver、eager parity、tensor dtype/device | ` execution-parity ` ：` DIFF-1a ` – ` 1c ` | ` compile.py::regionally_compile ` → runner batch → model denoise/solver |
2424| seed、request-local generator、guidance=0、并发 RNG、batched generators | ` execution-parity ` ：` DIFF-1b ` | ` inputs/data.py::OmniDiffusionSamplingParams ` → runner ` _initialize_generator ` → request-batch generator collate |
2525| ModelOpt/checkpoint adapter、weight/scale remap、unknown tensor、resolution path | ` checkpoint-distributed ` ：` DIFF-2a ` | ` diffusers_loader.py::{_get_checkpoint_adapter,load_weights} ` → ` modelopt.py::{_resolve_target_and_output_names,adapt} ` |
2626| host-weight artifact、source identity、layout/dtype、warm restore | ` checkpoint-distributed ` ：` DIFF-2d ` | ` model_loader/host_weights/{source_identity,contracts,identity_adapter}.py ` → policy/restorer |
2727| HSDP/FSDP、` fully_shard ` 、DeviceMesh、packed/scalar parameter、FP8 | ` checkpoint-distributed ` ：` DIFF-2b ` | ` distributed/hsdp.py::{apply_hsdp_to_model,shard_model} ` → loader ` _load_model_with_hsdp ` → ` hsdp_fp8.py ` |
2828| component quantization、text encoder/transformer/VAE 独立配置、owner prefix、meta/offload | ` checkpoint-distributed ` ：` DIFF-2c ` | ` data.py::_propagate_quantization_from_tf_config ` → loader weight sources/post-load → component linear consumer |
2929| LPIPS/PSNR/相似度阈值、CPU offload、量化质量证据 | ` quality-evidence ` ：` DIFF-3a ` | changed exact case → runner ` execute_model ` → model pipeline；A/B 同路径 |
30- | paged KV/cache、block manager、显存预算、warmup/profile、scheduler admission | ` system-runtime ` ：` DIFF-4a ` , ` DIFF-4b ` , ` DIFF-4c ` | engine init → ` diffusion_kv/initialization.py ` → worker memory probe → native allocator → scheduler lifecycle |
30+ | paged KV/cache、backend/platform、GQA/layout、预算与 admission | ` system-runtime ` ：` DIFF-4a ` – ` 4f ` | engine init → ` diffusion_kv/{ initialization,paged_attention_adapter} .py ` → platform hook → scheduler |
3131| worker/RPC 异常、rank-status、traceback/device cache 清理 | ` system-runtime ` ：` DIFF-4d ` | ` diffusion_worker.py::{_execute_rpc,_worker_busy_loop} ` 的 raise/reply/status 路径 |
3232
3333| 审查组 | 什么时候触发 | 规则 ID |
3434| ---| ---| ---|
35- | ` core ` | 每次共享 diffusion 审查 | ` DIFF-1a ` , ` DIFF-1b ` |
36- | ` execution-parity ` | graph/eager、solver、RNG、generator、zero/default | ` DIFF-1a ` , ` DIFF-1b ` |
35+ | ` core ` | 每次共享 diffusion 审查 | ` DIFF-1a ` , ` DIFF-1b ` , ` DIFF-1c ` |
36+ | ` execution-parity ` | graph/eager、solver、RNG、generator、tensor dtype/device | ` DIFF-1a ` , ` DIFF-1b ` , ` DIFF-1c ` |
3737| ` checkpoint-distributed ` | checkpoint、quantization、HSDP/FSDP、artifact identity | ` DIFF-2a ` , ` DIFF-2b ` , ` DIFF-2c ` , ` DIFF-2d ` |
3838| ` quality-evidence ` | 质量阈值、offload、A/B case | ` DIFF-3a ` |
39- | ` system-runtime ` | cache/资源预算 、native 边界、feature gate、异常或并发调度 | ` DIFF-4a ` , ` DIFF-4b ` , ` DIFF-4c ` , ` DIFF-4d ` |
39+ | ` system-runtime ` | cache/预算 、native/backend/platform、attention layout、异常与并发 | ` DIFF-4a ` – ` 4f ` |
4040| ` author-routing ` | 只供 Direct reviewer 导航，不作为 finding 规则 | ` DIFF-0a ` , ` DIFF-0b ` |
4141
4242## 优化路径与 eager 的等价合同
@@ -61,6 +61,15 @@ confidence: high
6161 到达 consumer。Cosmos3 的落地约束见
6262 [ Cosmos3 规则] ( ../../models/cosmos3/rules.md ) 。 ^[ PR #5001 ]
6363
64+ ### DIFF-1c — 新 tensor 从真实 consumer 派生 dtype 和 device
65+
66+ - 触发：mixed precision pipeline 中新建 mask、index、constant、buffer 或预计算 tensor。
67+ - 强制：从输入或目标权重派生 device/dtype，整数 index 显式使用 consumer 要求的类型；
68+ graph/eager 与 batch 重排后保持 shape、alias 和数值语义。
69+ - 禁止：依赖 process 默认 fp32/CPU 或隐式 cast/move；只测 shape 而不执行 BF16 consumer。
70+ - 验收：BF16、错长、batch reorder 和 graph/eager 用例断言 consumer 收到相同 device/dtype、
71+ alias 与结果。 ^[ PR #5067 ] ^[ PR #5068 ] ^[ PR #5174 ] ^[ PR #5981 ]
72+
6473## Checkpoint 与分布式加载
6574
6675### DIFF-2a — checkpoint remap 必须追到已注册且真实消费的目标
@@ -71,15 +80,17 @@ confidence: high
7180- 禁止：把 producer 有而当前 consumer 不支持的 tensor 静默过滤；必须 fold/map 或
7281 fail fast，并在错误中标明依赖的 upstream 版本边界。
7382- 验收：测试覆盖已消费 key、未知 key、当前版本不支持的 scale 以及两条 resolution
74- path 的输出名。ModelOpt ` pre_quant_scale ` 是该规则的原始触发。 ^[ PR #5087 ]
83+ path 的输出名；fused mixed-FP8 还须覆盖 weight/scale/shard、gate/up 顺序、nested serialized
84+ FP8 和 combined projection，缺 shard 不得默认 0。 ^[ PR #5087 ] ^[ PR #5848 ]
7585
7686### DIFF-2b — HSDP/FSDP 修复必须执行真实 fully_shard
7787
7888- 触发：改动 diffusion HSDP/FSDP 参数过滤、packed/scalar parameter 或 DeviceMesh。
7989- 强制：至少用单 rank Gloo + CPU DeviceMesh 执行一次真实 ` fully_shard ` 。
8090- 禁止：只断言传给 mock 的 kwargs 后声称分布式语义已覆盖。
8191- 验收：普通 float parameter 变为 DTensor；packed uint8/scalar parameter 保持本地
82- identity，并覆盖 loader 的真实调用边界。 ^[ PR #5088 ]
92+ identity，并覆盖 loader 的真实调用边界；replicate size 非正值拒绝，1 用 1D、>1 用 2D
93+ DeviceMesh，测试 world size 与参数一致。 ^[ PR #5088 ] ^[ PR #5872 ]
8394
8495### DIFF-2c — component quantization 独立解析且保留完整 owner 前缀
8596
@@ -91,7 +102,8 @@ confidence: high
91102 隐式覆盖其他组件；因为同属一个模型就量化全部 linear。
92103- 验收：至少覆盖“只量化一个组件、其他组件保持 BF16”的真实构造与加载，逐层断言
93104 命中/排除集合，并验证 meta-device parameter 不会被提前 move。FLUX.2 的具体边界见
94- [ FLUX.2 规则] ( ../../models/flux2/rules.md ) 。 ^[ PR #5136 ]
105+ [ FLUX.2 规则] ( ../../models/flux2/rules.md ) ；新增 quantization×offload 组合需给兼容矩阵，
106+ 未验证 quantizer fail-closed，并核对 dtype/shape/stride。 ^[ PR #5136 ] ^[ PR #6279 ]
95107
96108### DIFF-2d — Artifact identity 只信任已验证的不可变来源
97109
@@ -115,7 +127,8 @@ confidence: high
115127- 禁止：用 50-step A/B 数字为 10-step 测试阈值背书；只写“需要 offload”而不说明
116128 是资源前提还是功能行为。
117129- 验收：运行测试文件中的 exact case，并在规则/配置旁保留最短资源原因；对称 baseline
118- 证明质量差异来自目标量化变量。 ^[ PR #5136 ]
130+ 证明质量差异来自目标量化变量。低 steps smoke 只能证明 runtime compatibility，不得声称
131+ BF16 quality parity。 ^[ PR #5136 ] ^[ PR #6279 ]
119132
120133## Paged cache、资源预算与系统运行时
121134
@@ -165,5 +178,25 @@ confidence: high
165178- 验收：测试分别覆盖 ` collect_rank_status=true ` 与抛出/错误回复路径，断言错误文本仍可见、
166179 ` exc.__traceback__ is None ` 、cache cleanup 被调用，后续健康 RPC 仍成功。 ^[ PR #6385 ]
167180
181+ ### DIFF-4e — paged backend 在启动时按平台和逐层能力闭环
182+
183+ - 触发：启用 paged scheduler、增加 diffusion attention backend 或平台 override。
184+ - 强制：启动阶段解析并验证每层实际 backend 与当前平台；走 Omni platform hook，保留
185+ piecewise/SP 等能力。尚无生产 caller 的模式必须明确告警并文档化。
186+ - 禁止：未知平台继承 GPU 默认；分配 cache 后到首次 dispatch 才失败；静默占用 paged KV
187+ 却继续 dense；直接换用 upstream backend 丢失 Omni 能力。
188+ - 验收：unsupported platform/backend fail-fast；CUDA/NPU 对应 lane 和正式模型 E2E 证明
189+ resolved backend；mixed-mask piecewise/SP 回归通过。 ^[ PR #5543 ] ^[ PR #6102 ]
190+
191+ ### DIFF-4f — paged attention metadata 不从 padding 猜逻辑布局
192+
193+ - 触发：paged adapter 修改 GQA、prefix/current-token packing、LSE layout 或二维特例。
194+ - 强制：显式传递 Q/KV head 数、每请求 prefix/current span 和 layout；保持压缩 GQA 与 packed
195+ current-token 语义，单 token/单 head 二维输入仍使用同一合同。
196+ - 禁止：从 padding 长度推断逻辑跨度；在 ` sequence == heads ` 时猜 LSE 维度；fallback 静默换
197+ backend 或把 KV heads 扩成 Q heads。
198+ - 验收：32Q/8KV、异构 prefix、单 token/单 head、非对称等维 LSE 和 batch compaction 精确
199+ 对照 dense/reference 输出。 ^[ PR #5543 ] ^[ PR #6102 ]
200+
168201相关执行流见 [ Diffusion architecture] ( architecture.md ) ；benchmark 证据合同见
169202[ performance evidence] ( ../../benchmark/guides/performance-evidence.md ) 。
0 commit comments