Add vLLM-Omni daily review knowledge

knowledge/repos/vllm-omni/ci/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "vLLM-Omni CI"
 created: 2026-07-10
-updated: 2026-07-10
+updated: 2026-08-04
 type: index
 tags: [vllm-omni, ci]
 sources: []
@@ -21,5 +21,6 @@ sources: []
 
 | 遇到什么 | 查看哪里 |
 |---|---|
+| 修改 Buildkite 选择器、pytest marker、硬件队列、golden 或质量阈值 | [CI 规则](rules.md) |
 | 查看仓库特有 CI 陷阱 | [CI guides](guides/_index.md) |
 | 调查历史 CI 失败 | [CI incidents](incidents/_index.md) |

knowledge/repos/vllm-omni/ci/rules.md

@@ -0,0 +1,45 @@
+---
+title: "vLLM-Omni CI 规则"
+created: 2026-08-04
+updated: 2026-08-04
+type: rule
+tags: [vllm-omni, ci]
+sources: ["PR #5436", "PR #5695", "PR #5696", .buildkite/, tests/helpers/mark.py]
+confidence: high
+---
+
+# vLLM-Omni CI 规则
+
+只有 `VOMNI-CI-数字字母` 是可审计规则 ID。
+
+## Direct 代码快速入口
+
+| PR 描述信号 | 规则 | 第一批 live 源码 |
+|---|---|---|
+| Buildkite path、label、pytest selector、marker、队列、卡数或目标分支 | `VOMNI-CI-1a` | 命中 `.buildkite/` step → pytest 命令 → changed test 的 `pytestmark` / `hardware_test` |
+| 平台专有 golden、阈值、accuracy/performance lane | `VOMNI-CI-1b` | changed test case → golden selector → scorer/threshold → 实际 CI hardware marker |
+
+## VOMNI-CI-1a — 选择器改动必须闭合到实际收集的测试集合
+
+- 触发：新增、拆分、收窄或移动 Buildkite step，或修改 path、label、pytest `-m`、
+  hardware marker、队列、卡数及非默认目标分支。
+- 强制：冻结 PR 的真实 target base；分别在 base/head 收集测试，并把
+  `path/label → pytest selector → test marker → hardware/queue/card count` 逐项对齐；
+  每个被移除的平台或测试都必须有明确归类。
+- 禁止：从文件名推断收集集合；在 `main` 上验证一个目标为 release/challenge 分支的
+  diff；把未解释的掉测、平台移除或 label 变化当作纯 CI 重排。
+- 验收：保存 base/head 的 collection diff，head 中每个选中测试都能到达匹配的 runner，
+  每个掉测都有 `moved`、`intentionally removed` 或 `still covered elsewhere` 结论，并用
+  实际 target branch 跑一次选择器 smoke。 ^[PR #5695] ^[PR #5696]
+
+## VOMNI-CI-1b — 平台专有质量 oracle 必须来自同一硬件 case
+
+- 触发：按 CUDA/ROCm/NPU 或具体硬件选择 golden、评分器、阈值或质量 job。
+- 强制：golden provenance、测试输入、模型 revision、执行参数、marker、队列和实际硬件
+  属于同一个 case；平台分支必须显式选择 oracle，未命中的平台保持原合同。
+- 禁止：用另一硬件的本地输出生成 golden；用无法解释的阈值放宽吸收平台漂移；修改
+  一个平台时顺带改变其他平台的 baseline。
+- 验收：目标 CI runner 产出的 artifact 可复现提交 golden 的 digest 和评分，目标平台
+  命中专属 oracle，至少一个未改平台 control 仍选择原 oracle；阈值证据同时满足
+  [DIFF-3a](../components/diffusion/rules.md#diff-3a--质量阈值必须由完全相同的测试-case-产生)。
+  ^[PR #5436]

knowledge/repos/vllm-omni/components/diffusion/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "Diffusion"
 created: 2026-07-10
-updated: 2026-07-31
+updated: 2026-08-04
 type: index
 tags: [vllm-omni, components, diffusion]
 sources: []
@@ -16,7 +16,8 @@ sources: []
 ## 什么时候查这里
 
 - 根因位于共享 diffusion 代码，可能影响多个模型。
-- 调查 denoise loop、diffusion runner、scheduler 或共享 attention 执行机制。
+- 调查 denoise loop、diffusion runner、scheduler、attention backend 选择或 packed
+  sequence boundary。
 
 ## 不放什么
 
@@ -28,7 +29,7 @@ sources: []
 | 遇到什么 | 查看哪里 |
 |---|---|
 | 理解共享职责和数据流 | [architecture](architecture.md) |
-| 根据 PR 描述直达 execution parity、checkpoint/distributed 或 quality evidence 的规则组与第一批源码 | [rules 与代码地图](rules.md) |
+| 根据 PR 描述直达 execution parity、attention backend、checkpoint/distributed 或 quality evidence 的规则组与第一批源码 | [rules 与代码地图](rules.md) |
 | diffusion step 与 request/continuous batching | [step and batching](step-and-batching.md) |
 | Cache-DiT、TeaCache 和 prefix cache | [cache acceleration](cache-acceleration.md) |
 | TP/PP/SP/CFG/VAE/HSDP 等并行策略 | [parallelism](parallelism.md) |

knowledge/repos/vllm-omni/components/diffusion/rules.md

@@ -1,10 +1,10 @@
 ---
 title: "Diffusion 共享规则"
 created: 2026-07-20
-updated: 2026-07-31
+updated: 2026-08-04
 type: rule
 tags: [vllm-omni, components, diffusion]
-sources: ["PR #4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py]
+sources: ["PR #4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", "PR #5691", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py, vllm_omni/diffusion/attention/backends/flash_attn.py, vllm_omni/diffusion/attention/backends/ring/ring_selector.py]
 confidence: high
 ---
 
@@ -22,6 +22,8 @@ confidence: high
 |---|---|---|
 | CUDA Graph、compile、fused scheduler/solver、cache path、eager parity | `execution-parity`：`DIFF-1a` | `vllm_omni/diffusion/compile.py::regionally_compile` → `vllm_omni/diffusion/worker/diffusion_model_runner.py::{DiffusionModelRunner.execute_model,execute_model_batch}` → 命中模型的 denoise/solver consumer |
 | seed、request-local generator、guidance=0、并发 RNG、batched generators | `execution-parity`：`DIFF-1b` | `vllm_omni/inputs/data.py::OmniDiffusionSamplingParams` → `diffusion_model_runner.py::DiffusionModelRunner._initialize_generator` → `request_batch.py::DiffusionRequestBatch.collate_sampling_param_generators` |
+| FA4/FA3/FA2、optional import/ABI、CUDA capability、Ring LSE/window | `attention-backend`：`DIFF-1c` | `diffusion/attention/backends/utils/fa.py` → `ring/ring_selector.py::select_flash_attn_impl` → local/ring wrapper |
+| packed varlen、`cu_seqlens_*`、padding boundary、Ring/Ulysses parity | `attention-backend`：`DIFF-1d` | metadata producer → `attention/backends/flash_attn.py::FlashAttentionImpl.forward` → `attention/layer.py::{_run_local_attention,_run_ring_attention}` |
 | ModelOpt/checkpoint adapter、weight/scale remap、unknown tensor、resolution path | `checkpoint-distributed`：`DIFF-2a` | `vllm_omni/diffusion/model_loader/diffusers_loader.py::{DiffusersPipelineLoader._get_checkpoint_adapter,load_weights}` → `checkpoint_adapters/modelopt.py::{ModelOptFp8CheckpointAdapter._resolve_target_and_output_names,adapt}` |
 | HSDP/FSDP、`fully_shard`、DeviceMesh、packed/scalar parameter、FP8 | `checkpoint-distributed`：`DIFF-2b` | `vllm_omni/diffusion/distributed/hsdp.py::{apply_hsdp_to_model,shard_model}` → `model_loader/diffusers_loader.py::DiffusersPipelineLoader._load_model_with_hsdp` → `quantization/hsdp_fp8.py::prepare_fp8_layers_for_fsdp` |
 | component quantization、text encoder/transformer/VAE 独立配置、owner prefix、meta/offload | `checkpoint-distributed`：`DIFF-2c` | `vllm_omni/diffusion/data.py::OmniDiffusionConfig._propagate_quantization_from_tf_config` → `model_loader/diffusers_loader.py::{DiffusersPipelineLoader._get_weight_sources,_process_weights_after_loading}` → 命中 component 的真实 linear consumer |
@@ -31,6 +33,7 @@ confidence: high
 |---|---|---|
 | `core` | 每次共享 diffusion 审查 | `DIFF-1a`, `DIFF-1b` |
 | `execution-parity` | graph/eager、solver、RNG、generator、zero/default | `DIFF-1a`, `DIFF-1b` |
+| `attention-backend` | Flash backend selection、packed varlen、Ring/Ulysses、padding boundary | `DIFF-1c`, `DIFF-1d` |
 | `checkpoint-distributed` | checkpoint、quantization、HSDP/FSDP | `DIFF-2a`, `DIFF-2b`, `DIFF-2c` |
 | `quality-evidence` | 质量阈值、offload、A/B case | `DIFF-3a` |
 | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `DIFF-0a`, `DIFF-0b` |
@@ -57,6 +60,31 @@ confidence: high
   到达 consumer。Cosmos3 的落地约束见
   [Cosmos3 规则](../../models/cosmos3/rules.md)。 ^[PR #5001]
 
+### DIFF-1c — 可选 attention backend 的选择、包装和 Ring 语义必须一致
+
+- 触发：增加或修改 FA4/FA3/FA2 discovery、optional extra、CUDA capability selector、
+  local/Ring wrapper、window 或 LSE 返回值。
+- 强制：同时验证硬件 capability 与目标 symbol 可用性；import/ABI 失败只能降级到下一条
+  已支持路径并留下可见原因；local 与 Ring 对 window、softmax scale、causal 和 LSE 的
+  约定必须一致。
+- 禁止：只按 GPU 名称或已安装 package 选择 backend；显式请求不可用实现后静默换成语义
+  不同的 kernel；Ring wrapper 丢弃上层需要的 LSE 或改变 unlimited-window sentinel。
+- 验收：用 capability × FA4/FA3/FA2 可用性矩阵验证选择优先级和显式失败；local/Ring wrapper
+  参数与返回值测试对齐，并至少运行一次真实 backend smoke，证明 packaging extra、文档命令
+  和 runtime import 指向同一实现。 ^[PR #5691]
+
+### DIFF-1d — packed varlen 边界是原子合同，所有并行路径都必须保留
+
+- 触发：producer 或 backend 读写 `cu_seqlens_q`、`cu_seqlens_k`、`max_seqlen_q`、
+  `max_seqlen_k`，或把带 padding 的 packed 输入送入 Ring/Ulysses/hybrid attention。
+- 强制：四个字段一起生产、转发和消费；每条启用的 parallel/backend 路径必须把相同
+  sequence boundary 交给 kernel，无法表达时在执行前明确拒绝。
+- 禁止：只提供部分 metadata；在 Ring 路径丢弃边界；假设已分配但 backend 忽略的
+  `attn_mask` 能阻止真实 token 关注 padding 或下一条 packed sequence。
+- 验收：缺任一字段立即失败；两个不同长度样本的 packed 结果分别与独立运行对齐且无
+  cross-sequence attention；local 与每个声明支持的 Ring/Ulysses 组合做数值 parity，
+  不支持的组合有 fail-fast 测试。 ^[PR #5691]
+
 ## Checkpoint 与分布式加载
 
 ### DIFF-2a — checkpoint remap 必须追到已注册且真实消费的目标

knowledge/repos/vllm-omni/components/serving/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "Serving"
 created: 2026-07-10
-updated: 2026-07-31
+updated: 2026-08-04
 type: index
 tags: [vllm-omni, components, serving]
 sources: []
@@ -16,6 +16,7 @@ sources: []
 ## 什么时候查这里
 
 - CLI、HTTP、OpenAI-compatible API 或 offline/online 请求行为不一致。
+- serve flag 迁移、multipart media 限额、临时 artifact 所有权或后台任务 cleanup。
 - 参数在入口处丢失、默认值改变，或请求没有进入预期 engine 路径。
 
 ## 不放什么
@@ -28,4 +29,4 @@ sources: []
 | 遇到什么 | 查看哪里 |
 |---|---|
 | 理解入口到 engine 的边界 | [architecture](architecture.md) |
-| 根据 PR 描述直达 request contract、streaming format、artifact readiness 或 metrics 的规则组与第一批源码 | [rules 与代码地图](rules.md) |
+| 根据 PR 描述直达 request contract、upload lifecycle、public CLI、streaming format、artifact readiness 或 metrics 的规则组与第一批源码 | [rules 与代码地图](rules.md) |

knowledge/repos/vllm-omni/components/serving/rules.md

@@ -1,10 +1,10 @@
 ---
 title: "Serving 规则"
 created: 2026-07-20
-updated: 2026-07-31
+updated: 2026-08-04
 type: rule
 tags: [vllm-omni, components, serving]
-sources: ["PR #3576", "PR #4718", "PR #4834", "PR #4905", "PR #4912", "PR #5157", "claude-workflow-starter-private@09dca46", "zuiho-kai/claude-workflow-starter@c217fc6", vllm_omni/entrypoints/async_omni.py, vllm_omni/entrypoints/openai/diffusion_request_utils.py, vllm_omni/entrypoints/openai/serving_speech.py, vllm_omni/metrics/prometheus.py]
+sources: ["PR #3576", "PR #4718", "PR #4834", "PR #4905", "PR #4912", "PR #5157", "PR #5647", "PR #5691", "claude-workflow-starter-private@09dca46", "zuiho-kai/claude-workflow-starter@c217fc6", vllm_omni/entrypoints/async_omni.py, vllm_omni/entrypoints/cli/serve.py, vllm_omni/entrypoints/openai/api_server.py, vllm_omni/entrypoints/openai/diffusion_request_utils.py, vllm_omni/entrypoints/openai/serving_speech.py, vllm_omni/metrics/prometheus.py]
 confidence: high
 ---
 
@@ -19,7 +19,9 @@ confidence: high
 
 | PR 描述在做什么 | 精确规则组 | 第一批 live 源码 |
 |---|---|---|
-| `extra_body`、flattened/nested/canonical/legacy 输入、alias、`negative_prompt`、diffusion request extras | `request-contract`：`SERV-4a`–`4h` | `vllm_omni/entrypoints/openai/diffusion_request_utils.py::{normalize_diffusion_request_args,apply_normalized_diffusion_request_extra_args}` → `serving_chat.py::{OmniOpenAIServingChat._preprocess_chat,OmniOpenAIServingChat.generate_diffusion_images}` |
+| `extra_body`、flattened/nested/canonical/legacy 输入、alias、`negative_prompt`、diffusion request extras | `request-contract`：`SERV-4a`–`4i` | `vllm_omni/entrypoints/openai/diffusion_request_utils.py::{normalize_diffusion_request_args,apply_normalized_diffusion_request_extra_args}` → `serving_chat.py::{OmniOpenAIServingChat._preprocess_chat,OmniOpenAIServingChat.generate_diffusion_images}` |
+| multipart `UploadFile`、重复 media、临时文件、413、sync/async cleanup | `upload-lifecycle`：`SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4i` | `vllm_omni/entrypoints/openai/api_server.py::{_parse_video_form,_persist_uploaded_video_references,_run_video_generation_job,create_video_sync}` → 模型 owner 的 task/source matrix |
+| serve flag 删除/改名、Helm value、headless forwarding、内部兼容字段 | `public-cli-contract`：`SERV-6a`, `SERV-6b` | `vllm_omni/entrypoints/cli/serve.py::{OmniServeCommand.subparser_init,run_headless}` → public wrappers/charts → `entrypoints/utils.py::load_and_resolve_stage_configs` |
 | `chat_template_kwargs`、raw HTTP/SDK `extra_body`、text/audio modalities、choices、空音频 | `chat-multimodal-contract`：`SERV-4c` + 命中模型规则 | upstream `ChatCompletionRequest` → `serving_chat.py::{OmniOpenAIServingChat._preprocess_chat,OmniOpenAIServingChat.chat_completion_full_generator,OmniOpenAIServingChat._create_text_choice,OmniOpenAIServingChat._create_audio_choice}` |
 | endpoint restriction、unsupported route、capability、completions/chat/speech 400 | `endpoint-capability`：`SERV-4c`, `SERV-4d` | `config/endpoint_policy.py::{OmniServingCapability,shutdown_unsupported_routes}` → `config/config_factory.py::StageConfigFactory.get_pipeline_endpoint_restrictions` → `engine/async_omni_engine.py::AsyncOmniEngine.__init__` → `entrypoints/openai/api_server.py::build_app` |
 | sleep/wake、partial stage/tag、idempotency、ACK、generation admission | `engine-lifecycle`：`SERV-5a`, `SERV-5b` | `entrypoints/async_omni.py::{AsyncOmni.sleep,AsyncOmni.wake_up,AsyncOmni.generate}` → `worker/base.py::{handle_sleep_task,handle_wake_task}` / `diffusion/worker/diffusion_worker.py` |
@@ -36,7 +38,9 @@ confidence: high
 | `chat-multimodal-contract` | chat template kwargs、SDK flatten、text/audio response shape | `SERV-4c` + 命中模型规则 |
 | `endpoint-capability` | endpoint restriction、unsupported route、公开 400 | `SERV-4c`, `SERV-4d` |
 | `engine-lifecycle` | sleep/wake、partial stage/tag、ACK、generation admission | `SERV-5a`, `SERV-5b` |
-| `request-contract` | 请求字段、来源、冲突、dispatcher、consumer view | `SERV-4a`, `SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4e`, `SERV-4f`, `SERV-4g`, `SERV-4h` |
+| `upload-lifecycle` | multipart media、临时 artifact、大小限制、后台任务 cleanup | `SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4i` |
+| `public-cli-contract` | serve flag、wrapper/chart key、headless、公开/内部兼容边界 | `SERV-6a`, `SERV-6b` |
+| `request-contract` | 请求字段、来源、冲突、dispatcher、consumer view | `SERV-4a`, `SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4e`, `SERV-4f`, `SERV-4g`, `SERV-4h`, `SERV-4i` |
 | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `SERV-0a`, `SERV-0b` |
 
 ## SERV-1a — 所有可预判错误在第一个 streaming chunk 前返回
@@ -171,6 +175,19 @@ confidence: high
 - 禁止：继续堆 helper、compatibility branch 或 reviewer-specific patch。
 - 验收：恢复编码前 owner、consumer、删除项和 diff 预算都有可检查记录。
 
+### SERV-4i — multipart artifact 在 I/O 前验合同、在所有终态释放
+
+- 触发：公开请求接收一个或多个 `UploadFile`、URL media，或把输入物化后交给后台任务。
+- 强制：在 read/download/persist/decode 前完成 dispatcher、模型 capability 与
+  source/task matrix 校验；流式执行 count、per-file 和 aggregate byte 上限，超限返回
+  413；只清理由当前请求创建的 artifact，并保留输入顺序直到最终 consumer 完成。
+- 禁止：把无限 multipart 先复制到临时目录再校验；让非法组合进入 engine 后变成 sync
+  500 或 async failed job；只在成功路径或 audio 分支 cleanup。
+- 验收：sync/async 都覆盖冲突 400、超限中途 413、setup 失败、generation 失败、timeout、
+  cancellation、missing-job/early-return 与成功；无效请求未调用持久化或 engine，所有已创建
+  路径在每个终态消失，用户提供的非 owned 路径不被删除。MiniMax H3 的具体矩阵见
+  [MiniMax H3 规则](../../models/minimax-h3/rules.md)。 ^[PR #5691]
+
 ## Engine 生命周期合同
 
 ### SERV-5a — sleep/wake 状态必须保留 stage 和 tag 作用域
@@ -192,5 +209,30 @@ confidence: high
   sleep → wake → generate，不支持的 stage 在调用 worker 前明确拒绝。
   ^[PR #4834] ^[PR #4905] ^[PR #4912]
 
+## Public CLI 兼容边界
+
+### SERV-6a — 公开 serve 入口退役必须在所有 producer 上 fail closed
+
+- 触发：删除或改名 serve CLI option、wrapper/chart key 或公开配置文件入口。
+- 强制：parser、headless builder、脚本、chart、测试和公开 serving 文档在同一批迁移到
+  canonical replacement；已删除的外部 key 必须显式拒绝并给出迁移目标。当前 serve
+  部署 YAML 的唯一公开 flag 是 `--deploy-config`。
+- 禁止：删除是有意 breaking change 时又加静默 alias/fallback；wrapper 接受但忽略旧值；
+  留下仍会发出旧 flag 的可运行命令。
+- 验收：replacement 可解析且到达最终 consumer，旧 option parser 失败；standard/headless
+  发出同一 canonical 值，wrapper/chart 同时有正向与旧 key 拒绝测试，公开 serve 调用扫描
+  不再命中退役 flag。 ^[PR #5647]
+
+### SERV-6b — 兼容性按 ingress 分类，不能按同名 symbol 推断
+
+- 触发：公开 CLI 已移除，但 Python/direct API、offline example 或 resolver 仍保留同名字段。
+- 强制：分别列出 public CLI、wrapper/chart、offline example、Python/direct 和内部 resolver；
+  public 行为由 Serving owner 决定，仍保留的 loader/schema 语义交给
+  [Configuration rules](../configuration/rules.md) 并记录明确 follow-up 边界。
+- 禁止：因为仓库仍出现 `stage_configs_path` 就恢复公开 serve flag；也不能因为 public parser
+  已删除就宣称所有内部兼容路径已移除。
+- 验收：公开 rejection 与 canonical forwarding 测试通过；每个暂留内部/direct 路径有独立
+  compatibility test，直到后续迁移显式删除。 ^[PR #5647]
+
 请求到 engine 的边界见 [Serving architecture](architecture.md)；公开协议通用检查见
 [review contracts](../../../../general/review/guides/reviewer-lens-contracts.md)。