vllm-project/vllm · 标签视图

KV Offload 热度改为每请求结算一次，修正淘汰顺序

建议精读，尤其是负责 KV Offload、CPU 缓存策略或调度器的工程师： - 值得学习的三个设计决策：一是「用逻辑 rank 而非物理位置表达 recency」，从而让 pin 状态与淘汰顺序解耦；二是「每请求一次访问」的语义边界（insertion / reuse / 内部级联 pin 三分类）；三是通过默认实现保持 `touch` API 与外部策略兼容的渐进式改法。 - 重点关注 `policies/lru.py` 的 `_is_current()` / `_update_recency()` / `evict()` 三者构成的懒失效与原子回滚协议，这是最容易在后续修改中被破坏的部分。 - 若维护自定义 `cache_policy_module_path` 策略，需验证新的 `on_request_finished()` / `on_store_miss()` 默认路径是否符合预期；若新增 offload key 的产出路径，务必同时调用 `set_offload_key_position()`，否则顺序会静默降级。

修正 Mamba 准入块估算，避免长请求永久卡在等待队列

值得精读，重点不在 diff 规模（源码仅 4 行），而在于三个设计决策：(1) 「上限截断」与「条件覆盖」的语义差异，以及为什么 `min()` 才能同时避免高估导致的准入饥饿和低估计的块池超发；(2) `apply_admission_cap` 从「影响数值」退化为「只影响副作用」，使准入与分配共用同一估算口径；(3) 新增测试把「估算等于实测」写成断言，是排查同类 block accounting 问题的通用模板。建议阅读顺序：先看 PR body 的复现场景与 Stall 描述，再看 `MambaManager.get_num_blocks_to_allocate` 尾部的构造与 `min()`，最后看新测试如何先把请求推进 `_allocated_block_reqs` 再制造 checkpoint 场景。后续可跟进：对 partial hit + checkpoint 组合、`num_prefill_checkpoint_blocks > 1` 与不同 `hash_block_size` 补充参数化覆盖，并在 review 中确认 #53614 是否为确定回归来源。

修复 P/D 下多模块 MTP 未验证 draft 污染 KV cache

值得精读，尤其适合关注 P/D 架构、KV connector 与投机解码交叉区域的工程师。核心设计决策是“把跨模块的 lookahead 推导收敛为单一属性 + 单一 backoff 函数”，并以 max 组合语义兼容 Mamba 与 MTP 两类 drafter，这种消除重复推导、防止契约漂移的思路可直接借鉴。基准数据完整（含逐 position 接受率），可作为同类性能修复 PR 的范本。

重构结构化输出与投机解码的约束起点契约

值得精读，且建议按「契约 → 消费方 → 测试」的顺序读：先看 `vllm/v1/structured_output/__init__.py` 的 `_get_constraint_start()`，它是整个 PR 唯一的语义来源；再看 `scheduler.py` 三个调用点确认新契约的用法；最后看 `test_structured_output_manager.py` 的 `FlowCase` / `_run_real_flow()` 理解验证方式。重点关注四个设计决策：(1) 用 `len + 1` 哨兵而非 `None` 表达「本窗口无约束」，三个消费点的 `>=` / `>` / `<=` 各有语义，不要「顺手统一」；(2) 降序扫描把语义从「第一次边界」改成「最后一次边界」，这对交错思考模型更合理但改变了行为；(3) 断言降级为日志是刻意的（避免 engine core 被打挂），代价是失败请求要等 accept 阶段兜底；(4) 「reasoning parser 必须无状态」目前只是文档契约，落地前不建议在生产上把 stateful parser 与投机解码 + 结构化输出组合使用。

修复 SWA 卸载中失效窗口内 pending 块误阻塞就绪前缀

值得精读 `_sliding_window_lookup` 的“状态作用域”设计：一个只应在当前有效窗口内生效的标志位，如何随窗口失效（MISS/RETRY）正确清除，是小而典型的调度状态机 bug，且修复只改 12 行源码。测试写法（先 mock 扫描器、再真实 manager 集成、同步/异步双参数化）也值得借鉴。对 KV offload / SWA 相关贡献者推荐阅读。

提交前校验 routed-experts 偏移，避免 EngineCore 崩溃

值得精读（篇幅小、信息密度高）。关注三个设计决策：(a) 校验位置选在 InputProcessor 而非 SamplingParams 或调度器，理由是覆盖 OpenAI 与非 OpenAI 全部生成调用且早于 EngineCore 提交；(b) 采用 '拒绝' 而不是 'clamp'，避免把非法请求静默改写为语义不明的合法请求；(c) 闭区间语义——把 offset == prompt_len 视为合法的空切片而非错误，并同步放宽调度器断言。建议读者顺手排查自己代码里是否存在绕过 InputProcessor 直接投递 Request 的路径，以及在 `python -O` 下调度器 assert 失效后的行为。若计划进一步加固，可考虑把下界检查下沉到 `SamplingParams` 校验或让调度器显式抛错替代 assert。

KV Offload 异步查找复用在途探针，消除重复后端探测

值得精读，尤其是关注「用显式状态机替代布尔标记」这一设计决策：`LookupPhase` 让 `flush()` / `drain_results()` / `cleanup()` 三处的判定条件自解释，也顺带把「孤儿回收」这一新职责安放到 `drain_results()` 这个唯一的结果入口，避免了在多处散落删除逻辑。测试手法同样值得借鉴：用 `monkeypatch` 把 `batch_lookup` 换成受 `threading.Event` 控制的 `blocking_lookup`，把并发时序钉死成确定性断言（`batch_lookup_calls == 1`），比 sleep 轮询稳健得多。阅读时建议重点核对两点：一是 worker 在 `batch_lookup` 异常时是否一定投递结果（决定在途状态是否会永久滞留），二是 `flush()` 无条件 drain 后是否还有别的地方依赖旧的结果可见时序。建议对 `AsyncLookupManager` 增加一个长跑/压力场景的回收断言，作为对本次状态驻留改动的兜底。

排除 QSA ring 组，修复 MooncakeStore 混合注意力启动崩溃

值得精读。该 PR 展示了「transferable ≠ storable」的投影分层设计：同一 KV cache group 可因 `prefix_cacheable` 属性在不同连接器视角下呈现不同子集，并通过「扩展既有 API 而非新增 selector」控制接口膨胀。review 中 ivanium 与作者的几轮交锋（命名、抽象层次、API 删除）是接口设计讨论的良好案例。建议关注后续是否统一 `select_transfer_block_ids` 与 `get_block_ids(group_ids=...)` 的接口职责，以及 `prefix_cacheable` 属性在各 cache spec 上的契约覆盖。