From 9de23e553c50b313c4e44f59dd3bb4ad2d4d5a8a Mon Sep 17 00:00:00 2001 From: zuiho <2324465096@qq.com> Date: Sun, 23 Aug 2026 16:33:27 +0800 Subject: [PATCH] Learn rules from full human review audit --- knowledge/repos/vllm-omni/_index.md | 4 +- knowledge/repos/vllm-omni/ci/_index.md | 3 +- knowledge/repos/vllm-omni/ci/rules.md | 65 +++++++++++++++++++ .../repos/vllm-omni/components/_index.md | 3 +- .../vllm-omni/components/diffusion/rules.md | 53 ++++++++++++--- .../components/host-weight-runtime/_index.md | 26 ++++++++ .../components/host-weight-runtime/rules.md | 53 +++++++++++++++ .../components/model-executor/_index.md | 2 +- .../components/model-executor/rules.md | 18 +++-- .../vllm-omni/components/serving/rules.md | 30 +++++++-- .../vllm-omni/models/minicpm-o-4-5/_index.md | 6 +- .../vllm-omni/models/minicpm-o-4-5/rules.md | 27 +++++++- 12 files changed, 262 insertions(+), 28 deletions(-) create mode 100644 knowledge/repos/vllm-omni/ci/rules.md create mode 100644 knowledge/repos/vllm-omni/components/host-weight-runtime/_index.md create mode 100644 knowledge/repos/vllm-omni/components/host-weight-runtime/rules.md diff --git a/knowledge/repos/vllm-omni/_index.md b/knowledge/repos/vllm-omni/_index.md index 64a87279c..f672625cf 100644 --- a/knowledge/repos/vllm-omni/_index.md +++ b/knowledge/repos/vllm-omni/_index.md @@ -1,7 +1,7 @@ --- title: "vLLM-Omni 入口" created: 2026-07-10 -updated: 2026-07-31 +updated: 2026-08-23 type: index tags: [vllm-omni] sources: [] @@ -23,6 +23,8 @@ PR title/body 先选择 owner；changed files 只校验实际范围。Direct 已 | HTTP/OpenAI request、response、endpoint、engine lifecycle | [serving rules](components/serving/rules.md) | | checkpoint、tokenizer、processor、stage input/handoff | [model-executor rules](components/model-executor/rules.md) | | diffusion pipeline、denoise、VAE/DiT、图像生成 | [diffusion rules](components/diffusion/rules.md) | +| host-weight artifact、lease、filesystem store、restore transaction | [host-weight rules](components/host-weight-runtime/rules.md) | +| Buildkite、硬件 lane、CI guard、xdist/shared fixture | [CI rules](ci/rules.md) | | connector、collective、跨 stage 通信 | [distributed](components/distributed/_index.md) | | queue、token budget、prefix cache、调度 | [scheduler rules](components/scheduler/rules.md) | | 明确模型名或 registry key | 直接查看 [models 目录](models/_index.md) | diff --git a/knowledge/repos/vllm-omni/ci/_index.md b/knowledge/repos/vllm-omni/ci/_index.md index cee1066b5..b4cc07af3 100644 --- a/knowledge/repos/vllm-omni/ci/_index.md +++ b/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-23 type: index tags: [vllm-omni, ci] sources: [] @@ -21,5 +21,6 @@ sources: [] | 遇到什么 | 查看哪里 | |---|---| +| 审查硬件 lane、回归 fence、CI 工具供应链或 xdist/shared fixture | [CI rules](rules.md) | | 查看仓库特有 CI 陷阱 | [CI guides](guides/_index.md) | | 调查历史 CI 失败 | [CI incidents](incidents/_index.md) | diff --git a/knowledge/repos/vllm-omni/ci/rules.md b/knowledge/repos/vllm-omni/ci/rules.md new file mode 100644 index 000000000..a9104d47e --- /dev/null +++ b/knowledge/repos/vllm-omni/ci/rules.md @@ -0,0 +1,65 @@ +--- +title: "vLLM-Omni CI 规则" +created: 2026-08-23 +updated: 2026-08-23 +type: rule +tags: [vllm-omni, ci] +sources: ["PR #3422", "PR #5074", "PR #5524", "PR #5543", "PR #5670", "PR #5872", "PR #6048", "PR #6096", "PR #6102", "PR #6202", "PR #6208", "PR #6273", "PR #6293", "PR #6339", "PR #6343"] +confidence: high +--- + +# vLLM-Omni CI 规则 + +只有 `OMNI-CI-数字字母` 是可审计规则 ID。 + +## Direct 代码快速入口 + +| PR 描述信号 | 规则 | 第一批源码 | +|---|---|---| +| 新模型、nightly、CUDA/NPU、硬件 marker、镜像升级 | `OMNI-CI-1a` | `.buildkite/**` → `pyproject.toml` markers → 目标 e2e/accuracy test | +| regression/guard、route census、middleware、mutation test | `OMNI-CI-1b` | 公开 app/handler → guard test；先证明旧实现会失败 | +| pre-commit、SPDX、shellcheck、stability marker | `OMNI-CI-2a` | `.pre-commit-config.yaml`、`.buildkite/**`、`tools/**` | +| xdist、共享 worker、下载 fixture、进程池 | `OMNI-CI-2b` | `tests/conftest.py`、`tests/helpers/**`、`tests/model_tests/**` | + +## OMNI-CI-1a — 硬件 lane 必须真实收集并执行目标路径 + +- 触发：增加模型、硬件路径、nightly/ready/merge lane，或升级运行时/镜像。 +- 强制：资源数、pytest marker、pipeline 路由和共享 stage registry 同步；必需依赖、模型初始化 + 或 collection 失败必须让 job 失败，并证明目标测试数大于零且原失败在对应硬件消失。 +- 禁止：初始化失败后 skip-green；用 CPU 静态检查代替 CUDA/NPU 执行；只改模型目录而漏掉 + 共享 registry/路由；把临时硬件硬编码留到合并。 +- 验收：当前 head 的目标 lane 记录硬件、依赖版本、collection 数和执行结果；注入缺依赖、坏 + registry 或错误 marker 时 lane 必须红。 ^[PR #3422] ^[PR #5524] ^[PR #5543] + ^[PR #5872] ^[PR #6048] ^[PR #6096] ^[PR #6102] + +## OMNI-CI-1b — 回归 fence 必须锚定可观察合同且非空转 + +- 触发：新增 bug regression、API guard、route census 或 middleware fence。 +- 强制：从 assembled app/公开 handler 观察行为，只改变目标变量；必需 state 不仅检查存在， + 还要检查非 `None`。测试须在旧实现或代表性 mutation 上失败，在修复后通过。 +- 禁止：绑定可搬迁私有符号或单个 router；用恒真类型断言、错误参数的提前失败、宽泛 + `>=400`、不同文本或长度冒充目标分支证据。 +- 验收：mutation 分别置空 wiring、移除目标 route/method、绕过 inner middleware，fence 均失败； + route census 覆盖应用实际暴露的 HEAD/OPTIONS 和依赖 state key。 ^[PR #3422] ^[PR #5074] + ^[PR #5670] ^[PR #6202] + +## OMNI-CI-2a — CI 工具、schema 和 hook 是可复现供应链 + +- 触发：修改 pre-commit/Buildkite schema、下载 lint 工具、SPDX/import 检查或 stability marker。 +- 强制：固定工具版本并校验摘要；声明本地与 CI 强制 hook 矩阵；路径跨 Windows/POSIX + 归一化；源码头使用项目 SPDX 标识且覆盖 `.sh`；marker 参数 shell-quote 并有明确默认值。 +- 禁止：下载浮动 `stable`；让 rebase 静默回退 hook/marker；未引用包含 `: ` 的 YAML command； + 用测试名后缀代替硬件 marker。 +- 验收：当前 main schema/pre-commit、DCO 和 marker collection 通过；篡改摘要、Windows 路径、 + shell header 或非法 stability 参数分别被对应 gate 拒绝。 ^[PR #3422] ^[PR #6273] + ^[PR #6293] ^[PR #6343] + +## OMNI-CI-2b — 并行测试基础设施隔离任务失败和共享状态 + +- 触发：xdist、共享下载 fixture、长寿命 judge/transcriber worker 或进程池 retry。 +- 强制：任务级异常后丢弃污染 worker；submit/result 串行，只有进程崩溃可 retry-once；传给 + xdist 的参数可序列化，依赖固定兼容 major；共享文件在读锁前显式检查存在，写入保持锁语义。 +- 禁止：普通 task error 复用同一进程；为 pytest 生命周期不可达的竞态堆测试；把并行参数或 + 活对象隐式跨进程传递。 +- 验收：OOM、普通异常和 BrokenProcessPool 分别验证隔离/重试；online/offline xdist 均通过， + 并发 cache miss 只产生一个完整文件。 ^[PR #6208] ^[PR #6339] diff --git a/knowledge/repos/vllm-omni/components/_index.md b/knowledge/repos/vllm-omni/components/_index.md index 590a84958..66813ad8f 100644 --- a/knowledge/repos/vllm-omni/components/_index.md +++ b/knowledge/repos/vllm-omni/components/_index.md @@ -1,7 +1,7 @@ --- title: "vLLM-Omni 组件 owner" created: 2026-07-10 -updated: 2026-07-31 +updated: 2026-08-23 type: index tags: [vllm-omni, components] sources: [] @@ -18,6 +18,7 @@ sources: [] | [Serving](serving/_index.md) | 用户请求、OpenAI API、响应、AsyncOmni engine 生命周期 | [rules](serving/rules.md) | | [Model Executor](model-executor/_index.md) | stage config/input、模型加载、worker、跨 stage 数据桥 | [rules](model-executor/rules.md) | | [Diffusion](diffusion/_index.md) | diffusion pipeline、denoise、VAE/DiT、并行和 cache | [rules](diffusion/rules.md) | +| [Host Weight Runtime](host-weight-runtime/_index.md) | immutable host artifact、lease、filesystem store、typed outcome 与 restore transaction | [rules](host-weight-runtime/rules.md) | | Distributed | connector、KV 迁移、collective、跨 stage 通信 | [index](distributed/_index.md) | | [Scheduler](scheduler/_index.md) | 请求队列、token budget、KV transfer、prefix cache | [rules](scheduler/rules.md) | diff --git a/knowledge/repos/vllm-omni/components/diffusion/rules.md b/knowledge/repos/vllm-omni/components/diffusion/rules.md index 70e51020b..07acb6ed9 100644 --- a/knowledge/repos/vllm-omni/components/diffusion/rules.md +++ b/knowledge/repos/vllm-omni/components/diffusion/rules.md @@ -4,7 +4,7 @@ created: 2026-07-20 updated: 2026-08-23 type: rule tags: [vllm-omni, components, diffusion] -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] +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] confidence: high --- @@ -20,23 +20,23 @@ confidence: high | PR 描述在做什么 | 精确规则组 | 第一批 live 源码 | |---|---|---| -| 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 | +| CUDA Graph、compile、fused solver、eager parity、tensor dtype/device | `execution-parity`：`DIFF-1a`–`1c` | `compile.py::regionally_compile` → runner batch → model denoise/solver | | seed、request-local generator、guidance=0、并发 RNG、batched generators | `execution-parity`：`DIFF-1b` | `inputs/data.py::OmniDiffusionSamplingParams` → runner `_initialize_generator` → request-batch generator collate | | 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}` | | 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 | | 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` | | 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 | | LPIPS/PSNR/相似度阈值、CPU offload、量化质量证据 | `quality-evidence`：`DIFF-3a` | changed exact case → runner `execute_model` → model pipeline；A/B 同路径 | -| 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 | +| 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 | | worker/RPC 异常、rank-status、traceback/device cache 清理 | `system-runtime`：`DIFF-4d` | `diffusion_worker.py::{_execute_rpc,_worker_busy_loop}` 的 raise/reply/status 路径 | | 审查组 | 什么时候触发 | 规则 ID | |---|---|---| -| `core` | 每次共享 diffusion 审查 | `DIFF-1a`, `DIFF-1b` | -| `execution-parity` | graph/eager、solver、RNG、generator、zero/default | `DIFF-1a`, `DIFF-1b` | +| `core` | 每次共享 diffusion 审查 | `DIFF-1a`, `DIFF-1b`, `DIFF-1c` | +| `execution-parity` | graph/eager、solver、RNG、generator、tensor dtype/device | `DIFF-1a`, `DIFF-1b`, `DIFF-1c` | | `checkpoint-distributed` | checkpoint、quantization、HSDP/FSDP、artifact identity | `DIFF-2a`, `DIFF-2b`, `DIFF-2c`, `DIFF-2d` | | `quality-evidence` | 质量阈值、offload、A/B case | `DIFF-3a` | -| `system-runtime` | cache/资源预算、native 边界、feature gate、异常或并发调度 | `DIFF-4a`, `DIFF-4b`, `DIFF-4c`, `DIFF-4d` | +| `system-runtime` | cache/预算、native/backend/platform、attention layout、异常与并发 | `DIFF-4a`–`4f` | | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `DIFF-0a`, `DIFF-0b` | ## 优化路径与 eager 的等价合同 @@ -61,6 +61,15 @@ confidence: high 到达 consumer。Cosmos3 的落地约束见 [Cosmos3 规则](../../models/cosmos3/rules.md)。 ^[PR #5001] +### DIFF-1c — 新 tensor 从真实 consumer 派生 dtype 和 device + +- 触发：mixed precision pipeline 中新建 mask、index、constant、buffer 或预计算 tensor。 +- 强制：从输入或目标权重派生 device/dtype，整数 index 显式使用 consumer 要求的类型； + graph/eager 与 batch 重排后保持 shape、alias 和数值语义。 +- 禁止：依赖 process 默认 fp32/CPU 或隐式 cast/move；只测 shape 而不执行 BF16 consumer。 +- 验收：BF16、错长、batch reorder 和 graph/eager 用例断言 consumer 收到相同 device/dtype、 + alias 与结果。 ^[PR #5067] ^[PR #5068] ^[PR #5174] ^[PR #5981] + ## Checkpoint 与分布式加载 ### DIFF-2a — checkpoint remap 必须追到已注册且真实消费的目标 @@ -71,7 +80,8 @@ confidence: high - 禁止：把 producer 有而当前 consumer 不支持的 tensor 静默过滤；必须 fold/map 或 fail fast，并在错误中标明依赖的 upstream 版本边界。 - 验收：测试覆盖已消费 key、未知 key、当前版本不支持的 scale 以及两条 resolution - path 的输出名。ModelOpt `pre_quant_scale` 是该规则的原始触发。 ^[PR #5087] + path 的输出名；fused mixed-FP8 还须覆盖 weight/scale/shard、gate/up 顺序、nested serialized + FP8 和 combined projection，缺 shard 不得默认 0。 ^[PR #5087] ^[PR #5848] ### DIFF-2b — HSDP/FSDP 修复必须执行真实 fully_shard @@ -79,7 +89,8 @@ confidence: high - 强制：至少用单 rank Gloo + CPU DeviceMesh 执行一次真实 `fully_shard`。 - 禁止：只断言传给 mock 的 kwargs 后声称分布式语义已覆盖。 - 验收：普通 float parameter 变为 DTensor；packed uint8/scalar parameter 保持本地 - identity，并覆盖 loader 的真实调用边界。 ^[PR #5088] + identity，并覆盖 loader 的真实调用边界；replicate size 非正值拒绝，1 用 1D、>1 用 2D + DeviceMesh，测试 world size 与参数一致。 ^[PR #5088] ^[PR #5872] ### DIFF-2c — component quantization 独立解析且保留完整 owner 前缀 @@ -91,7 +102,8 @@ confidence: high 隐式覆盖其他组件；因为同属一个模型就量化全部 linear。 - 验收：至少覆盖“只量化一个组件、其他组件保持 BF16”的真实构造与加载，逐层断言 命中/排除集合，并验证 meta-device parameter 不会被提前 move。FLUX.2 的具体边界见 - [FLUX.2 规则](../../models/flux2/rules.md)。 ^[PR #5136] + [FLUX.2 规则](../../models/flux2/rules.md)；新增 quantization×offload 组合需给兼容矩阵， + 未验证 quantizer fail-closed，并核对 dtype/shape/stride。 ^[PR #5136] ^[PR #6279] ### DIFF-2d — Artifact identity 只信任已验证的不可变来源 @@ -115,7 +127,8 @@ confidence: high - 禁止：用 50-step A/B 数字为 10-step 测试阈值背书；只写“需要 offload”而不说明 是资源前提还是功能行为。 - 验收：运行测试文件中的 exact case，并在规则/配置旁保留最短资源原因；对称 baseline - 证明质量差异来自目标量化变量。 ^[PR #5136] + 证明质量差异来自目标量化变量。低 steps smoke 只能证明 runtime compatibility，不得声称 + BF16 quality parity。 ^[PR #5136] ^[PR #6279] ## Paged cache、资源预算与系统运行时 @@ -165,5 +178,25 @@ confidence: high - 验收：测试分别覆盖 `collect_rank_status=true` 与抛出/错误回复路径，断言错误文本仍可见、 `exc.__traceback__ is None`、cache cleanup 被调用，后续健康 RPC 仍成功。 ^[PR #6385] +### DIFF-4e — paged backend 在启动时按平台和逐层能力闭环 + +- 触发：启用 paged scheduler、增加 diffusion attention backend 或平台 override。 +- 强制：启动阶段解析并验证每层实际 backend 与当前平台；走 Omni platform hook，保留 + piecewise/SP 等能力。尚无生产 caller 的模式必须明确告警并文档化。 +- 禁止：未知平台继承 GPU 默认；分配 cache 后到首次 dispatch 才失败；静默占用 paged KV + 却继续 dense；直接换用 upstream backend 丢失 Omni 能力。 +- 验收：unsupported platform/backend fail-fast；CUDA/NPU 对应 lane 和正式模型 E2E 证明 + resolved backend；mixed-mask piecewise/SP 回归通过。 ^[PR #5543] ^[PR #6102] + +### DIFF-4f — paged attention metadata 不从 padding 猜逻辑布局 + +- 触发：paged adapter 修改 GQA、prefix/current-token packing、LSE layout 或二维特例。 +- 强制：显式传递 Q/KV head 数、每请求 prefix/current span 和 layout；保持压缩 GQA 与 packed + current-token 语义，单 token/单 head 二维输入仍使用同一合同。 +- 禁止：从 padding 长度推断逻辑跨度；在 `sequence == heads` 时猜 LSE 维度；fallback 静默换 + backend 或把 KV heads 扩成 Q heads。 +- 验收：32Q/8KV、异构 prefix、单 token/单 head、非对称等维 LSE 和 batch compaction 精确 + 对照 dense/reference 输出。 ^[PR #5543] ^[PR #6102] + 相关执行流见 [Diffusion architecture](architecture.md)；benchmark 证据合同见 [performance evidence](../../benchmark/guides/performance-evidence.md)。 diff --git a/knowledge/repos/vllm-omni/components/host-weight-runtime/_index.md b/knowledge/repos/vllm-omni/components/host-weight-runtime/_index.md new file mode 100644 index 000000000..3c9753ea8 --- /dev/null +++ b/knowledge/repos/vllm-omni/components/host-weight-runtime/_index.md @@ -0,0 +1,26 @@ +--- +title: "Host Weight Runtime" +created: 2026-08-23 +updated: 2026-08-23 +type: index +tags: [vllm-omni, components] +sources: ["PR #6419", vllm_omni/host_weight_runtime/] +confidence: high +--- + +# Host Weight Runtime + +- 源码入口：`vllm_omni/host_weight_runtime/`。 +- 主要职责：跨模型共享的 immutable host artifact、lease、filesystem store、typed outcome + 和 restore transaction；具体 diffusion producer/identity adapter 仍归 Diffusion owner。 + +## 什么时候查这里 + +- 修改 host-weight store、lease/lock、deny/quarantine、locality、fallback 或 restore transaction。 +- 具体 diffusion layout/source identity 同时读取 [Diffusion DIFF-2d](../diffusion/rules.md)。 + +## 目录内容 + +| 遇到什么 | 查看哪里 | +|---|---| +| typed failure、lease/store concurrency、restore transaction | [rules](rules.md) | diff --git a/knowledge/repos/vllm-omni/components/host-weight-runtime/rules.md b/knowledge/repos/vllm-omni/components/host-weight-runtime/rules.md new file mode 100644 index 000000000..63e3cf9bf --- /dev/null +++ b/knowledge/repos/vllm-omni/components/host-weight-runtime/rules.md @@ -0,0 +1,53 @@ +--- +title: "Host Weight Runtime 规则" +created: 2026-08-23 +updated: 2026-08-23 +type: rule +tags: [vllm-omni, components] +sources: ["PR #6419", "PR #6445", vllm_omni/host_weight_runtime/] +confidence: high +--- + +# Host Weight Runtime 规则 + +只有 `HWR-数字字母` 是可审计规则 ID。 + +## Direct 代码快速入口 + +| PR 描述信号 | 规则 | 第一批源码 | +|---|---|---| +| typed outcome、preferred/required、producer、timeout | `HWR-1a` | `runtime.py` → `outcomes.py`/`errors.py` → store/writer | +| lease/lock、fork、deny、cleanup、filesystem locality | `HWR-1b` | `lease.py` → `filesystem/{locks,store,writer}.py` | +| plan/commit、manifest/schema、fallback model | `HWR-2a` | `protocols.py`/`manifest.py` → consumer restorer | + +## HWR-1a — fallback 只消费显式 retryable typed outcome + +- 触发：store mkdir/write/publish、producer、identity 或 timeout 路径变化。 +- 强制：所有 `OSError` 转成 typed result 并清临时目录；preferred 只对明确 retryable 的 miss、 + lock/domain/capacity failure fallback，producer、identity、publication 和配置错误必须 fail startup。 + Timeout 只承诺实现能强制的 coordination/lock 范围。 +- 禁止：preferred 泄漏裸异常或吞掉 semantic error；把同步 producer 描述成可取消的总时限。 +- 验收：mkdir/writer failure、retryable miss、nonretryable producer/publication 和 lock timeout 逐项 + 断言 terminal outcome、fallback 决策和临时目录清理。 ^[PR #6419] + +## HWR-1b — lease 返回和本地 store 状态必须线性一致 + +- 触发：lease close、fork、deny/quarantine、cleanup 或 filesystem 检测变化。 +- 强制：并发 `close()` 返回即代表 teardown/锁释放完成；fork child 只关闭继承 FD，不得解锁 + parent lease；打开 lease 后在共享锁内重查 deny；无 artifact 的孤儿 deny 自愈为 MISS。node-local + backend 只接受明确 allowlist，并记录真实 filesystem type。 +- 禁止：teardown 未完先返回；child 对继承 FD 执行 `LOCK_UN`；让 NFS/CIFS/Lustre/Ceph 或 unknown + mount 静默满足 local backend。 +- 验收：线程 close、fork、open-vs-deny race、orphan deny 和 remote/unknown filesystem 回归分别 + 证明锁、状态和 typed result；cleanup 不移除活跃 mapping。 ^[PR #6419] + +## HWR-2a — restore 是 validation-only plan 加一次性 commit + +- 触发：manifest/schema、producer/restorer identity 或模型 hydration 变化。 +- 强制：`plan_restore` 只校验且不变更 model/lease；`commit()->None` 是唯一一次性 mutation； + producer、manifest 和 restorer schema/version 必须精确匹配。commit 开始后失败只能丢弃 model， + fallback 必须新建实例。 +- 禁止：planning 提前写权重；失败后复用半 hydration model；malformed safetensors 或未知 + post-load policy 当 cache miss。 +- 验收：plan failure 保持原 model，commit failure 后 fresh model fallback；schema/version mismatch、 + malformed artifact 和 unsupported policy 均 fail-closed。 ^[PR #6419] ^[PR #6445] diff --git a/knowledge/repos/vllm-omni/components/model-executor/_index.md b/knowledge/repos/vllm-omni/components/model-executor/_index.md index 947529b94..3be3c7fc3 100644 --- a/knowledge/repos/vllm-omni/components/model-executor/_index.md +++ b/knowledge/repos/vllm-omni/components/model-executor/_index.md @@ -1,7 +1,7 @@ --- title: "Model Executor" created: 2026-07-10 -updated: 2026-07-31 +updated: 2026-08-23 type: index tags: [vllm-omni, components, model-executor] sources: [] diff --git a/knowledge/repos/vllm-omni/components/model-executor/rules.md b/knowledge/repos/vllm-omni/components/model-executor/rules.md index 3a5eefa19..9d3a82f14 100644 --- a/knowledge/repos/vllm-omni/components/model-executor/rules.md +++ b/knowledge/repos/vllm-omni/components/model-executor/rules.md @@ -1,10 +1,10 @@ --- title: "Model Executor 规则" created: 2026-07-10 -updated: 2026-07-31 +updated: 2026-08-23 type: rule tags: [vllm-omni, components, model-executor] -sources: [vllm_omni/worker/gpu_model_runner.py, tests/worker/test_omni_gpu_model_runner.py, vllm_omni/config/stage_config.py, vllm_omni/engine/stage_runtime.py, vllm_omni/engine/stage_engine_startup.py, "PR #3642", "PR #4730", "claude-workflow-starter-private@09dca46"] +sources: [vllm_omni/worker/gpu_model_runner.py, tests/worker/test_omni_gpu_model_runner.py, vllm_omni/config/stage_config.py, vllm_omni/engine/stage_runtime.py, vllm_omni/engine/stage_engine_startup.py, "PR #3422", "PR #3642", "PR #4730", "PR #5074", "PR #5792", "claude-workflow-starter-private@09dca46"] --- # Model Executor 规则 @@ -19,14 +19,14 @@ sources: [vllm_omni/worker/gpu_model_runner.py, tests/worker/test_omni_gpu_model | strict stage config、known-fields/projection、service/stage 字段归属、runtime config | `strict-stage-config`：`EXEC-3a` | `vllm_omni/config/stage_config.py::{build_stage_runtime_overrides,_build_engine_args}` → `vllm_omni/config/omni_config.py::{_build_common_stage_config_kwargs,VllmOmniConfig.from_pipeline_config}` → 真实 startup consumer | | runner `_preprocess`、逐请求 metadata、prefill/decode phase、batch preprocess、MTP | `runner-preprocess`：本页“Runner 到模型的预处理合同” | `vllm_omni/worker/gpu_model_runner.py::{OmniGPUModelRunner._maybe_run_batch_preprocess,_preprocess,_build_model_kwargs_extra,_talker_mtp_forward}` → `vllm_omni/model_executor/models/<命中模型>` consumer | | stage TP/PP/DP、devices、replica、visible devices、worker 启动、容量 fail-fast | `stage-runtime`：本页“Stage 并行度和设备容量必须一起验收” | `vllm_omni/config/stage_config.py::build_stage_runtime_overrides` → `vllm_omni/engine/stage_runtime.py::{StageRuntime.initialize,StageRuntime._resolve_replica_physical_devices}` → `stage_engine_startup.py::{launch_stage_replica,get_headless_replica_devices}` | -| `runtime_info`、`OmniOutput`、multimodal payload、跨 stage bridge、batch 串线 | `bridge-batch`：`EXEC-1a`, `EXEC-1b` | `vllm_omni/worker/gpu_model_runner.py::{extract_multimodal_outputs,_gather_runtime_additional_information,_build_model_kwargs_extra}` → `vllm_omni/model_executor/stage_input_processors/<命中模型>` | +| `runtime_info`、request RNG、batch compaction、跨 stage bridge/串线 | `bridge-batch`：`EXEC-1a`–`1c` | shared runner request state → stage input processor → model consumer | | loader dtype、只取 checkpoint config、避免整仓权重下载 | `loader-contract`：`EXEC-2a` | `vllm_omni/model_executor/model_loader/weight_utils.py::download_weights_from_hf_specific` → `vllm_omni/model_executor/models/<命中模型>` loader | | 审查组 | 什么时候触发 | 规则 ID | |---|---|---| | `core` | 每次 model-executor 审查 | `EXEC-1a` | | `strict-stage-config` | stage schema、projection、known fields | `EXEC-3a` | -| `bridge-batch` | runtime info、跨 stage payload、batch | `EXEC-1a`, `EXEC-1b` | +| `bridge-batch` | runtime info、跨 stage payload、batch、request RNG | `EXEC-1a`, `EXEC-1b`, `EXEC-1c` | | `loader-contract` | dtype、checkpoint config 获取、loader | `EXEC-2a` | | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `EXEC-0a`, `EXEC-0b` | @@ -88,6 +88,16 @@ Stage 拓扑错误的最小充分源码证据只有三段：一处最终配置 - 验收：至少两个不同输入的同批测试，分别断言 bridge、输出和错误归属；不能重复相同 prompt 让串线不可见。 ^[PR #3642] +### EXEC-1c — 请求随机状态跨 batching 和 yield 保持请求所有权 + +- 触发：AR/talker adapter 接收 seed/sampling knob，或修改 batch compaction/reorder、逐 token loop。 +- 强制：请求值在 adapter/model 构造前到达真实 sampling consumer；使用 request-local generator。 + 若依赖必须临时改 global RNG，只能在无 yield 的窄上下文 save/restore。 +- 禁止：deploy 默认覆盖请求 seed；共享 generator；每步复制完整历史或创建无界 + `batch*vocab` 临时量；global RNG 状态跨 yield 泄漏到兄弟请求。 +- 验收：同 seed 同输出、异 seed 不同输出，batch reorder/compaction 后逐请求结果稳定；全局 RNG + 前后相同，计数器证明目标分支实际消费请求参数。 ^[PR #3422] ^[PR #5074] ^[PR #5792] + ### EXEC-2a — loader 的 dtype 与 config 获取必须显式、最小化 - 触发：模型 loader 构造 text encoder、VAE、transformer 或只读取 checkpoint config。 diff --git a/knowledge/repos/vllm-omni/components/serving/rules.md b/knowledge/repos/vllm-omni/components/serving/rules.md index 3affc400c..b5a2056c3 100644 --- a/knowledge/repos/vllm-omni/components/serving/rules.md +++ b/knowledge/repos/vllm-omni/components/serving/rules.md @@ -4,7 +4,7 @@ created: 2026-07-20 updated: 2026-08-23 type: rule tags: [vllm-omni, components, serving] -sources: ["PR #3576", "PR #4718", "PR #4834", "PR #4905", "PR #4912", "PR #5157", "PR #6138", "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 #5670", "PR #6138", "PR #6202", "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] confidence: high --- @@ -21,11 +21,11 @@ confidence: high |---|---|---| | `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}` | | `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` | +| endpoint restriction、route/app-state guard、capability、公开 400 | `endpoint-capability`：`SERV-4c`, `SERV-4d`, `SERV-5d` | endpoint policy → `api_server.py::build_app` assembled app → public handler | | 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` | | serving class/factory 重构、optional adapter、diffusion/no-TTS 实例、warmup | `engine-lifecycle`：`SERV-5c` | `entrypoints/openai/serving_speech.py` 的所有 factory/`__new__` 路径 → `warmup`、voice upload/list、speech request caller | | SSE/streaming speech、audio format、PCM/WAV、speed、首 chunk 前校验 | `streaming-format`：`SERV-1a`, `SERV-1b` | `vllm_omni/entrypoints/openai/protocol/audio.py::{OpenAICreateSpeechRequest.validate_streaming_constraints,StreamingSpeechSessionConfig.validate_streaming_constraints}` → `serving_speech.py::{OmniOpenAIServingSpeech._validate_speech_streaming_request,OmniOpenAIServingSpeech.create_speech}` | -| `ref_audio`、x-vector/ICL、artifact cache、readiness、失败后 engine 存活 | `artifact-readiness`：`SERV-3a`, `SERV-3b` | `vllm_omni/entrypoints/openai/serving_speech.py::{_qwen3_tts_can_use_ref_audio_artifact_only,_track_ref_audio_artifact_warmup,_mark_ref_audio_artifact_ready_for_request,_discard_ref_audio_artifact_ready_if_unreferenced}` | +| `ref_audio`、x-vector/ICL、content identity、artifact cache/readiness | `artifact-readiness`：`SERV-3a`–`3c` | `serving_speech.py` reference resolve/decode/cache → adapter speaker cache → prefix salt | | Prometheus、waiting/running gauge、replica stats、throttle、collector lifecycle | `metrics-lifecycle`：`SERV-2a`, `SERV-2b` | `vllm_omni/entrypoints/omni_base.py::{OmniBase._log_summary_and_cleanup,OmniBase._process_stage_metrics_message}` → `vllm_omni/metrics/prometheus.py::{OmniPrometheusMetrics.__init__,set_running,set_waiting}` | | 审查组 | 什么时候触发 | 规则 ID | @@ -33,9 +33,9 @@ confidence: high | `core` | 每次 serving 审查 | `SERV-4c` | | `streaming-format` | SSE、audio streaming、format/default/capability | `SERV-1a`, `SERV-1b` | | `metrics-lifecycle` | metrics、gauge、replica、collector | `SERV-2a`, `SERV-2b` | -| `artifact-readiness` | artifact cache、capability、ready/mark/discard | `SERV-3a`, `SERV-3b` | +| `artifact-readiness` | artifact/content cache、capability、ready/mark/discard | `SERV-3a`, `SERV-3b`, `SERV-3c` | | `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` | +| `endpoint-capability` | endpoint restriction、route/app-state guard、公开 400 | `SERV-4c`, `SERV-4d`, `SERV-5d` | | `engine-lifecycle` | sleep/wake、partial stage/tag、ACK、generation admission、factory 状态矩阵 | `SERV-5a`, `SERV-5b`, `SERV-5c` | | `request-contract` | 请求字段、来源、冲突、dispatcher、consumer view | `SERV-4a`, `SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4e`, `SERV-4f`, `SERV-4g`, `SERV-4h` | | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `SERV-0a`, `SERV-0b` | @@ -100,6 +100,17 @@ confidence: high - 验收：单测枚举状态迁移；E2E 复现原始坏顺序、证明修复后存活，并在回退修复代码时 重新出现目标错误，避免测试空跑。 ^[PR #5157] +### SERV-3c — 内容身份必须原子贯穿全部缓存层 + +- 触发：本地/inline reference audio 或其他 locator 同时经过 decode、speaker/code 与 prefix cache。 +- 强制：先通过 allowed-local-media gate，再规范解析 URI/stat；本地身份至少含 size 与 + `st_mtime_ns`。decoded payload 与 identity 一次计算、一起返回，并把同一身份贯穿每层 cache key + 和 prefix salt；named voice 加 inline ref 按真实分支区分。 +- 禁止：raw locator 充当内容 salt；授权前 stat；两次独立 decode/stat；用 client-controlled + locator 建无界共享 side table；把完整 base64/路径写日志。 +- 验收：同长度覆盖、并发改写、named+inline、speaker cache 和 prefix hit 均不复用旧内容； + 非法路径不 stat，日志只含截断值且命中真实 logger hierarchy。 ^[PR #5670] + ## 请求输入合同 ### SERV-4a — 公开字段由 serving 显式拥有 @@ -205,5 +216,14 @@ confidence: high startup warmup、voice list/upload 与对应 request route；每条路径保持重构前的成功或结构化 错误合同，不得出现 `AttributeError`。 ^[PR #6138] +### SERV-5d — 应用 wiring guard 检查可用性而非属性名 + +- 触发：assembled app 的 route/middleware 依赖 `app.state` handler 或 factory wiring。 +- 强制：mandatory state 同时检查属性存在且非 `None`；guard 测试通过 assembled app/公开 handler + 观察行为，并覆盖应用实际暴露的方法和 middleware inner-app 调用。 +- 禁止：`hasattr` 接受显式 `None`；测试绑定可搬迁私有 symbol/单 router；用恒真断言证明 wiring。 +- 验收：把 handler 置空、移除 route/method、绕过 inner app 三类 mutation 均使 guard 失败； + 正常 app 的 HEAD/OPTIONS census 与必需 state key 完整。 ^[PR #6202] + 请求到 engine 的边界见 [Serving architecture](architecture.md)；公开协议通用检查见 [review contracts](../../../../general/review/guides/reviewer-lens-contracts.md)。 diff --git a/knowledge/repos/vllm-omni/models/minicpm-o-4-5/_index.md b/knowledge/repos/vllm-omni/models/minicpm-o-4-5/_index.md index 43bdd9b12..79a66b786 100644 --- a/knowledge/repos/vllm-omni/models/minicpm-o-4-5/_index.md +++ b/knowledge/repos/vllm-omni/models/minicpm-o-4-5/_index.md @@ -1,10 +1,10 @@ --- title: "MiniCPM-o 4.5" created: 2026-07-20 -updated: 2026-07-31 +updated: 2026-08-23 type: index tags: [vllm-omni, models, model-executor] -sources: ["PR #3642", vllm_omni/model_executor/models/minicpmo_4_5/] +sources: ["PR #3642", "PR #6154", "PR #6170", "PR #6318", vllm_omni/model_executor/models/minicpmo_4_5/] confidence: high --- @@ -32,6 +32,6 @@ runtime bridge 交给 TTS stage，再包装为 `OmniOutput.multimodal_outputs` ## 什么时候查这里 -- 审查 MiniCPM-o 4.5 registry、remote-code gate、TTS dependency、batch 或 stage handoff。 +- 审查 MiniCPM-o 4.5 registry、remote-code gate、TTS dependency、batch/stage handoff 或 native duplex session。 - 问题位于共享 bridge/batching 时转到 [Model Executor rules](../../components/model-executor/rules.md)。 diff --git a/knowledge/repos/vllm-omni/models/minicpm-o-4-5/rules.md b/knowledge/repos/vllm-omni/models/minicpm-o-4-5/rules.md index bc7af3f7d..4a15f7325 100644 --- a/knowledge/repos/vllm-omni/models/minicpm-o-4-5/rules.md +++ b/knowledge/repos/vllm-omni/models/minicpm-o-4-5/rules.md @@ -1,10 +1,10 @@ --- title: "MiniCPM-o 4.5 规则" created: 2026-07-20 -updated: 2026-07-31 +updated: 2026-08-23 type: rule tags: [vllm-omni, models, model-executor] -sources: ["PR #3642"] +sources: ["PR #3642", "PR #6154", "PR #6170", "PR #6318"] confidence: high --- @@ -20,6 +20,8 @@ confidence: high | tokenizer/processor、`trust_remote_code` | MCPMO-1a | pipeline/config factory → `model_executor/models/minicpmo_4_5/` loader | | TTS extra、backend 初始化、空音频 | MCPMO-1b | `minicpmo_4_5_omni_tts.py::MiniCPMO45OmniTTSForConditionalGeneration`、`minicpmo_4_5_token2wav.py::MiniCPMO45Token2wav` | | batch、`runtime_info`、stage handoff | MCPMO-3a/3b | `stage_input_processors/minicpmo_4_5_omni.py` → `minicpmo_4_5_omni.py::MiniCPMO45OmniForConditionalGeneration` → TTS/code2wav | +| native duplex、Stage0 resume、LISTEN/SPEAK、server VAD | MCPMO-4a | `experimental/fullduplex/{minicpmo45,openai}/` → stage input processor | +| instructions/persona/voice/mode update、prefill slots、context lock | MCPMO-4b | `experimental/fullduplex/minicpmo45/session.py` → runtime adapter/session runner | ## MCPMO-1a — trust_remote_code 服从用户选择 @@ -60,5 +62,26 @@ confidence: high - 禁止：直接 TTS class 不读 runtime bridge；返回 tuple 让 runner 猜它是 hidden state。 - 验收：真实 wrapper handoff 测试断言字段名、逐请求 shape、最终公开 payload。 ^[PR #3642] +## MCPMO-4a — native duplex 保留可恢复 Stage0，VAD 只作显式策略 + +- 触发：MiniCPM-o native duplex 的连续音频、LISTEN/SPEAK handoff 或 server VAD interruption。 +- 强制：模型说话时仍把音频单元追加到同一可恢复 Stage0，保留 KV/runtime state 和上一 + terminator；LISTEN 是成功且不需要 Talker hidden state，SPEAK 才转交 Talker。server VAD + hard cancellation 必须显式 opt-in，阈值不得落到使 silence branch 不可达的边界。 +- 禁止：用 server VAD cancellation 冒充 native interruption；每轮重建 Stage0；让 LISTEN 因 + 无 Talker payload 失败。 +- 验收：native case 完成响应≥2、cancel/truncate=0、listen≥1；opt-in hard interrupt 恰好一次 + terminal、fence 后无 stale delta、保留打断语句且后续响应成功。 ^[PR #6154] ^[PR #6170] + +## MCPMO-4b — session update 与派生 reservation 原子提交 + +- 触发：运行中更新 instructions、persona、voice、native mode 或影响 prefill slot 的字段。 +- 强制：先重算并验证 `prefill_slots`/first-append context tokens 等派生状态，再 ACK 并原子提交； + `native_context_locked` 只在真实 append 成功后设置。route-defining native mode 在 session 内不可变。 +- 禁止：buffered/deferred/rejected append 提前锁定；配置已变而 reservation 保持旧值；用 + true→false 绕过 native context lock。 +- 验收：成功更新同时改变派生状态；资源不足时无部分 mutation；buffer/defer/reject 均不锁， + append 成功才锁，mode flip 明确拒绝。 ^[PR #6318] + 共享 bridge/batch 规则见 [Model Executor rules](../../components/model-executor/rules.md)； 公开入口完整性见 [model adaptation guardrails](../../review/guides/model-adaptation-guardrails.md)。