vllm-project/vllm

DSv4.1 工具调用启用 XGrammar schema 约束并保留旧版回退

值得精读，但重点不在代码量。源码只有 13 行，真正的价值是三点设计模式：用 `getattr(module, name, None)` 做跨版本能力探测以规避 ImportError、把 grammar 构造委托给上游 builtin 时显式覆盖 `reasoning="disabled"` 以维持 serving 的推理边界契约、以及用 `skipif(hasattr(...))` + `monkeypatch` 双写测试同时锁定新路径与回退路径。建议读者额外关注：(1) 后续 XGrammar bump PR 是否把 ≥ 0.2.7 落到依赖与镜像；(2) 是否补一条带真实权重的 tool-calling eval，验证 strict 约束不会引发重采样或误截断；(3) 回退分支的删除时机与对应测试清理。

PCP 支持 decode-only FULL CUDA 图并统一捕获输入准备

值得精读，但重点看三处：一是 `partition_batch` 中 `num_reqs_after_padding` 的切片语义（真实行 vs padding 行的零值约定），它决定 FULL 图重放的 shape 契约；二是 `PCPManager.prepare_inputs_to_capture` 与 `get_dummy_block_tables` 的持久 buffer / rank-local 表策略，这是图捕获地址稳定的前提；三是 `validate_config` 如何用 `separate_routine()` 表达「decode 可以 FULL、prefill 不行」这一约束。建议同时阅读 pisceskkk/vllm#8 的重构提案，理解 maintainer 为何要求把 InputBatch 贯穿捕获准备。若计划在生产启用 `FULL_DECODE_ONLY`，建议先自行复现多步复用 buffer、请求数波动场景下的 seq_lens padding 行为。

修复 beam search 中止崩溃并保留部分输出

值得精读，优先级中等：改动约 170 行、3 个源文件 + 2 个测试文件，阅读成本低但涉及三个可复用的设计决策。建议重点关注 (1) online.py 用 `break` + 全量标记 abort 而非 `return`，为什么这样才能保留部分输出；(2) offline.py 用 `instance_start_and_end` 切片实现 prompt 级隔离，以及把未完成 beam 放进 `instance.completed` 的后果；(3) `finish_reason="abort"` 成为对外可见契约，以及 `get_beam_search_score` 中 `max(seq_len, 1)` 这类边界防护对排序路径的普适价值。后续可跟进：补一条真实 `/pause?mode=abort` 的端到端测试，并在 API 文档中说明 abort 的返回语义。

Arm CPU kernel 分片超时预算由 30 分钟放宽到 60 分钟

值得快速浏览而非精读：改动只有一行 timeout 与两行注释，10 分钟内即可读完。阅读时建议关注三点设计判断：其一，作者用“不同套件、相同墙钟边界、无 pytest summary”作为区分“预算不足”与“测试失败”的判据，这是处理 CI 超时类问题的可复用方法；其二，只放宽 kernel 分片而不是全局放宽，体现了对影响面的克制；其三，验证路径被明确限定为“必须由真实 Arm runner 端到端确认”，读者应跟进去看后续 nightly 是否真的在 60 分钟内跑完。对维护者的后续建议：为该分片补充耗时基线记录（例如各套件的实际耗时），当运行时间开始逼近 60 分钟时优先考虑拆分 shard 而不是继续加 timeout；同时此类 CI 脚本改动的合并最好留下 Arm runner 验证结论与人工审阅记录，避免作者自审自并成为常态。

DeepGEMM pin 迁至 vLLM fork 2.8.0，并更新 Mega MoE 调用约定

值得精读，尤其是维护 MoE 后端、DeepGEMM 集成或 CI 镜像的同学：本案是「小 diff、大范围」依赖迁移的典型样本。 三个值得关注的设计决策：一是用单一 fork pin 取代「按特性挑分支」，把 SM120 / SM90 / SiTU 三个能力收敛到一条可复现的 commit 上；二是只在 DeepGEMM 调用边界做参数别名映射，vLLM 内部配置名与其它后端（TRT-LLM / CuteDSL / AITER）保持不变，避免配置契约外溢；三是 `getattr(..., None)` 这类「静默 None」模式在依赖升级中极易造成功能性静默失败，本 PR 用「规范名 + 旧拼写 fallback」兼容两种 pin，这种双向兼容写法值得复用到其它外部内核绑定。 后续建议：把 SiTU 的 alpha/beta 映射固化为自动化数值回归（现在只有一次性脚本与 GSM8K A/B）；把 cmake / install script / build_deepgemm_C.py 中的 repo、tag、子模块信息收敛成单一来源；与 #56266 / #56255 合流时确认 `elfutils-devel` 与 `deep_jit` 的最终结论一致；持续跟踪 fork 与上游 2.8.x 的分叉成本。

新增 KVCR 二级卸载适配器并接入工厂与 CI

建议精读。对 KV offload / tiering 方向的维护者与打算编写自家二级 tier 适配器的团队，本 PR 是很好的模板：`_FrameworkPinAdapter` 展示了如何把外部系统的异步 pin 回调安全映射到主 tier 的请求生命周期（pending → process_pending → release_pin → take_pin_job_results），`_VllmKeyAdapter` 展示了 key 双向翻译时如何处理 group 维度与 int/bytes 两种事件格式，`build_metric_definitions` 展示了如何把外部指标并入 vLLM 命名空间。阅读时重点看三处设计决策：其一，注册惰性化 + 测试 `importorskip` 的可选依赖处理策略；其二，KVCR 语义（router hint、策略、描述符）全部外置的边界划分；其三，CI 固定 `v0.1.0` tag 而非 `@main` 的供应链取舍。对只关心推理性能与模型支持的贡献者，可以略读，只需知道默认路径未变。另外建议 reviewer 单独盯一下 `install-kv-offload.sh` 里 `uv pip uninstall` 的容错，以及 `_resolve_pin` 静默吞异常的观测性。

修复稀疏 MLA 分片 cudagraph 下的启动崩溃

推荐精读，尤其是正在处理 cudagraph / 流同步 / 稀疏注意力后端的工程师： 1. 重点看 `set_logical_topk_ready` 与 `_convert_once` 成对守卫的设计——它示范了“生产者停止 record、消费者回退 wait_stream”这种成对修改模式，避免留下半废弃的同步原语。 2. 关注 `in_piecewise_cudagraph()` 放在 `vllm/forward_context.py` 的取舍：为什么不放在 attention 目录下，以及它的捕获/回放双阶段语义（注释里明确写了 at capture or replay time）。 3. 借鉴 PR body 的排查方法论：最小复现（脱离 vLLM 的 10 行 CUDA 复现）+ bisect 定位引入 PR + duplicate check，是排查“只在特定 cudagraph 模式出现”的崩溃的模板。 4. 若后续要改这块代码，建议先补两条测试：FULL 模式仍走 `wait_event` 的断言，以及 hisparse `copy_stream` 在 piecewise 下的显式回归用例。

修正 ITL/TPOT 指标文档并为 Grafana 新增 TPOT 面板

- **值得精读（约 5 分钟）**：负责延迟监控、SLO 定义或性能回归看板的人应重点读 `docs/design/metrics.md` 新增的 ITL/TPOT 对比段落，它解释了为什么两个『看起来都是 TPOT』的指标在投机解码下会差数倍。 - **可以跳过**：`grafana.json` 的 167 行新增大部分是面板样板（`fieldConfig`、`options`、`thresholds`），只有 `targets` 里的 5 条 PromQL 值得复制到自建监控，尤其是 `rate(_sum)/rate(_count)` 这种 request-weighted mean 写法。 - **值得关注的设计决策**：(1) 选择『新增面板 + 保留旧面板』而非重命名替换，保持向后兼容；(2) 定义统一指向 `docs/benchmarking/cli.md`，避免同一概念在多处文档各写一套；(3) 把『单 token 记为 0、bench 会排除』直接写进面板 description，把口径差异前置给使用者而不是藏在文档角落。 - **建议跟进**：在 metrics.md 补充 token-weighted TPOT 的 PromQL 并标注『不推荐/仅供 debug』，以及直方图 bucket 对 P99 精度的影响；这些是 Issue #55276 提出但本 PR 未闭环的部分。