From dec465550cd0c65f4cd40dd65da962fdb0c86f77 Mon Sep 17 00:00:00 2001 From: zuiho <2324465096@qq.com> Date: Thu, 13 Aug 2026 12:40:29 +0800 Subject: [PATCH] Harden runtime review coverage Signed-off-by: zuiho <2324465096@qq.com> --- .../vllm-omni/components/diffusion/_index.md | 4 +- .../vllm-omni/components/diffusion/rules.md | 43 ++++++++++++++++++- src/infermatrix_copilot/thin_mcp_server.py | 5 ++- test/test_thin_mcp_server.py | 37 ++++++++++++++++ 4 files changed, 84 insertions(+), 5 deletions(-) diff --git a/knowledge/repos/vllm-omni/components/diffusion/_index.md b/knowledge/repos/vllm-omni/components/diffusion/_index.md index 572eef874..1d073c227 100644 --- a/knowledge/repos/vllm-omni/components/diffusion/_index.md +++ b/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-13 type: index tags: [vllm-omni, components, diffusion] sources: [] @@ -28,7 +28,7 @@ sources: [] | 遇到什么 | 查看哪里 | |---|---| | 理解共享职责和数据流 | [architecture](architecture.md) | -| 根据 PR 描述直达 execution parity、checkpoint/distributed 或 quality evidence 的规则组与第一批源码 | [rules 与代码地图](rules.md) | +| 根据 PR 描述直达 execution parity、checkpoint/distributed、quality evidence 或 paged-cache system-runtime 规则组与第一批源码 | [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) | diff --git a/knowledge/repos/vllm-omni/components/diffusion/rules.md b/knowledge/repos/vllm-omni/components/diffusion/rules.md index 7a573e767..e26607084 100644 --- a/knowledge/repos/vllm-omni/components/diffusion/rules.md +++ b/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-13 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 #6094", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py] confidence: high --- @@ -26,6 +26,7 @@ confidence: high | 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 | | LPIPS/PSNR/相似度阈值、CPU offload、量化质量证据 | `quality-evidence`：`DIFF-3a` | changed quality test 的 exact case → `vllm_omni/diffusion/worker/diffusion_model_runner.py::DiffusionModelRunner.execute_model` → 命中 pipeline；baseline/candidate 必须复用同一路径 | +| paged KV/cache、block manager、显存预算、warmup/profile、scheduler admission | `system-runtime`：`DIFF-4a`, `DIFF-4b`, `DIFF-4c` | `diffusion_engine.py` 初始化顺序 → `diffusion_kv/initialization.py` → `worker/diffusion_worker.py::determine_available_kv_memory` → native config/allocator → `sched/base_scheduler.py` 的 enabled 请求、异常和清理路径 | | 审查组 | 什么时候触发 | 规则 ID | |---|---|---| @@ -33,6 +34,7 @@ confidence: high | `execution-parity` | graph/eager、solver、RNG、generator、zero/default | `DIFF-1a`, `DIFF-1b` | | `checkpoint-distributed` | checkpoint、quantization、HSDP/FSDP | `DIFF-2a`, `DIFF-2b`, `DIFF-2c` | | `quality-evidence` | 质量阈值、offload、A/B case | `DIFF-3a` | +| `system-runtime` | cache/资源预算、native 边界、feature gate、异常或并发调度 | `DIFF-4a`, `DIFF-4b`, `DIFF-4c` | | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `DIFF-0a`, `DIFF-0b` | ## 优化路径与 eager 的等价合同 @@ -101,5 +103,42 @@ confidence: high - 验收：运行测试文件中的 exact case，并在规则/配置旁保留最短资源原因；对称 baseline 证明质量差异来自目标量化变量。 ^[PR #5136] +## Paged cache、资源预算与系统运行时 + +### DIFF-4a — 容量预算必须在影响峰值的初始化完成后测量 + +- 触发：新增或修改 KV/cache block 数、GPU/CPU memory budget、auto-fit、warmup/profile、 + dummy run 或物理 cache 分配。 +- 强制：写出并核对 `model load → activation warmup/profile → available-memory measurement + → logical config → physical allocation → first real request` 的真实顺序；预算必须包含真实 + activation/graph/lazy-kernel 峰值及明确 headroom。若当前阶段故意只建逻辑控制面，必须使用 + 显式固定预算或把最终容量决定推迟到数据面 profile 之后。 +- 禁止：用 warmup 前的当前 free/process residency 推导可用 cache，再在之后执行会常驻或抬高 + 峰值的 dummy/profile；也不能用 native auto-fit 或 allocator 成功证明预算来源正确。 +- 验收：enabled 路径在真实初始化顺序下记录测量前后峰值，低显存/最大合法请求不会因漏算 + activation 在首次或后续执行 OOM；显式预算分支和自动预算分支各有测试。 ^[PR #6094] + +### DIFF-4b — 复用 native 组件仍须审计 caller/adapter 契约 + +- 触发：diffusion adapter 调用 vLLM 的 cache spec/config/manager、scheduler 或其他版本化 API。 +- 强制：按仓库 pin 的精确 vLLM 版本核对 property/method、签名、sentinel、block-size 单位、 + max-length/capacity 前提、返回失败语义和 free/rollback 责任；分别证明 adapter 输入、调用时序、 + 输出解释和 native 内部算法。 +- 禁止：把“委托给 native vLLM”当作端到端正确性证明；native manager 不负责验证 Omni 在何时 + 测量预算、是否漏算其他显存、是否正确传播失败，也不保证 adapter 模拟对象符合真实属性合同。 +- 验收：真实 pin 的 contract test 覆盖正常值、边界/sentinel、容量不足、property 访问和清理； + fake 不能把真实 property 改成同名 method 或跳过 native precondition。 ^[PR #6094] + +### DIFF-4c — Feature gate 只限制影响范围，enabled 路径必须独立闭环 + +- 触发：新增或修改 `dense_legacy`/paged、eager/optimized 或其他默认关闭的 diffusion 路径。 +- 强制：分别审计 disabled/default 与 enabled；enabled 至少覆盖单请求、并发/多 rank、低资源、 + partial allocation、执行异常、取消、timeout、shutdown 和重复释放。异常必须到达终端请求或 + engine 信号并唤醒 waiter，所有已分配资源由明确 owner 回收。 +- 禁止：用“默认路径有 gate”“dense 未回归”或单请求 smoke 推导新路径正确；也不能让 scheduler/ + busy-loop 异常逃逸后留下永远等待的 stream。 +- 验收：path/lifecycle matrix 每行有 production-path 测试或明确 `MISSING_EVIDENCE`；enabled + 关键行缺失时审查只能是 partial，不能输出 clean/no findings。 ^[PR #6094] + 相关执行流见 [Diffusion architecture](architecture.md)；benchmark 证据合同见 [performance evidence](../../benchmark/guides/performance-evidence.md)。 diff --git a/src/infermatrix_copilot/thin_mcp_server.py b/src/infermatrix_copilot/thin_mcp_server.py index b701e9c77..a583c9538 100644 --- a/src/infermatrix_copilot/thin_mcp_server.py +++ b/src/infermatrix_copilot/thin_mcp_server.py @@ -166,7 +166,6 @@ def _knowledge_root() -> Path: ), "scope_prefixes": ( "vllm_omni/core/sched/", - "vllm_omni/diffusion/sched/", ), }, ) @@ -186,6 +185,10 @@ def _knowledge_root() -> Path: # owner, so no knowledge route will surface them. "When the diff adds or changes a test, check the assertions bind to real behavior and not to values the fixture, mock, or fake injected.", "When the diff passes a new argument to a dependency, check it against the lowest version the project's own constraints still permit, not the version installed here.", + "For resource or cache changes, trace budget measurement through reservation and physical consumption, including warmup/profile/activation ordering and low-resource behavior.", + "For runtime changes, trace exception propagation, partial-allocation cleanup, cancellation, timeout, shutdown, and concurrent scheduling to the terminal user-visible signal.", + "At native dependency boundaries, verify the pinned API contract and caller inputs; native reuse does not prove the caller's budget, ordering, adapter, or lifecycle correctness.", + "For feature-gated behavior, audit the enabled path independently; a safe disabled/default path limits blast radius but does not prove the new path correct.", "Stop investigating when every changed semantic path has a supported finding or explicit no-issue conclusion; do not add searches only for confidence.", "Run subtraction only when the diff adds or expands a helper, class, fallback, compatibility branch, or public behavior; otherwise mark no subtraction signal.", "Plan exactly one consolidated final review comment.", diff --git a/test/test_thin_mcp_server.py b/test/test_thin_mcp_server.py index 1ecfcd736..afbea02d0 100644 --- a/test/test_thin_mcp_server.py +++ b/test/test_thin_mcp_server.py @@ -247,6 +247,43 @@ def test_direct_routes_title_body_before_changed_files(monkeypatch): assert review["execution_budget"]["knowledge_file_reads"] == 1 +def test_direct_ranks_diffusion_owner_for_scheduler_managed_kv_pr(monkeypatch): + mcp, _core = _fake_mcp(monkeypatch) + review = mcp.tools["review"]( + target="https://github.com/vllm-project/vllm-omni/pull/6094", + repo="vllm-project/vllm-omni", + mode="direct", + title=( + "[Diffusion] Add native KV cache initialization and " + "Scheduler-managed block allocation" + ), + body=( + "Discover KV geometry, calculate available memory, initialize " + "paged_scheduler allocation, and keep dense_legacy gated. " + "HunyuanImage3 is the first consumer." + ), + changed_files=[ + "vllm_omni/config/omni_config.py", + "vllm_omni/diffusion/diffusion_engine.py", + "vllm_omni/diffusion/diffusion_kv/manager.py", + "vllm_omni/diffusion/sched/base_scheduler.py", + "vllm_omni/diffusion/worker/diffusion_worker.py", + ( + "vllm_omni/diffusion/models/hunyuan_image3/" + "hunyuan_image3_transformer.py" + ), + ], + ) + + owners = [route["owner"] for route in review["knowledge_routes"]] + assert owners[:2] == ["model:hunyuan-image3", "diffusion"] + assert "serving" not in owners + assert any( + "resource or cache changes" in item + for item in review["first_review_checklist"] + ) + + def test_direct_docs_only_budget_stays_small(monkeypatch): mcp, _core = _fake_mcp(monkeypatch) review = mcp.tools["review"](