vllm-project/vllm

清理 0.29 到期弃用项：移除隐式同步属性与旧配置项

建议精读，但只精读三处，其余可略过：① `vllm/v1/attention/backend.py` 的契约收缩与 `unpadded()` 的替代传递路径，理解“为什么 CPU 侧长度必须显式获取”；② `vllm/models/deepseek_v4/compressor.py` 与 `vllm/v1/attention/backends/mamba_attn.py` 的 `async_spec_decode` 守卫写法——这是“乐观上界不可用于精确判断”的范式，任何新增读取 `seq_lens_cpu_upper_bound` 的内核都应照此判断；③ `tests/v1/e2e/spec_decode/draft_model/test_async.py` 用 `VLLM_GPU_SYNC_CHECK=error` 取代自建 fixture 的取舍。对使用方，需要在发布说明中明确列出被删除的环境变量与配置别名，并检查自有启动脚本中对 `envs.VLLM_MM_HASHER_ALGORITHM` 之类的直接引用。设计上值得讨论的遗留问题：ReplaySSM 的校验是否应前移到启动期参数校验，以及是否该给所有 `seq_lens_cpu_upper_bound` 消费点加统一断言。

Kimi K3 MLA 缓存插入支持 FP8 分组内核，小 batch 提速约 6 倍

值得精读。三条设计决策值得关注：(1) 用模板参数而非运行时分支承担 BF16/FP8 差异，hot loop 中 `if constexpr` 零开销；(2) 每层 cache 基址与 scale 都放进设备端 tensor，一次 launch 内并行读取，这是 5 层合并后还能继续扩展到更多层的关键；(3) `process_weights_after_loading` 的时序修复揭示了 vLLM 里 `_k_scale` 这类量化 scale 的定稿时机，凡是要缓存量化参数的地方都应遵循同样的约束。建议读者重点比对 `cache_kernels.cu` 的派发宏与 host 校验顺序，以及测试中 `shared_slot_mapping` 别名场景的覆盖方式；若后续要在其它模型复用该内核，需要先确认 `_has_uniform_block_layout` 这类前提在目标模型上是否成立。

EPD 编码实例视频 IO 默认启用 NVDEC 解码

值得精读，属于「小改动、系统级收益」的典型样本。重点关注三处设计决策：一是 `_resolve_mm_video_decode_device` 的守卫顺序与「只在 encode-only 实例自动开启」的边界划分，它把资源独占性作为默认开启 GPU 解码的前提；二是把解码设备与多模态处理器设备绑定的决定（`mm_config.get_mm_processor_device_type()`），这是 review 中被作者自己推翻初版设计后得出的结论，避免了 D2H/H2D 重复搬运；三是 `VideoMediaIO.merge_kwargs` 中「启动期旋钮 vs 请求级旋钮」的划分和 `incompatible_backend_options` 的差集清理思路。建议同时阅读 PR body 的消融表（配置 A/B/D 对比）来理解收益来源，并跟踪作者预告的 kwargs 结构化重构 PR，因为当前的字典式选项合并已经出现过一次真实 bug（`device` 泄漏到 `opencv`）。如果团队正在做 EPD 规模扩展，这组数字可以直接用于容量规划：encoder 侧不再是瓶颈，PD 副本数成为吞吐决定因素。

固定 AINIC apt 仓库到快照，修复 ROCm 镜像构建失败

该 PR 改动很小但值得快速阅读：它清晰展示了如何修复 apt 可变仓库路径导致的完整性检查失败，并通过选中内容完全一致的快照来保持镜像二进制不变。对于维护 ROCm 镜像或处理第三方 apt 源不稳定问题的工程师有参考价值，无需深入代码学习。

Prometheus 直方图桶默认值收敛到单一模块，零行为变更

值得精读，但目标读者是 metrics/observability 维护者和准备做桶配置化的开发者，普通模型开发者可以只看结论。建议重点看三处设计决策：一是用 `Literal` + `get_args` 派生 `BUCKET_FAMILY_KEYS`，让「家族集合」在类型层和运行时各有一份但同源，便于测试做集合等值断言；二是快照测试的双层策略（访问器级 + 通过 `PrometheusStatLogger` 与 Prometheus 注册表的端到端回读），其中第二层捕捉到的正是「`main` 合进来一个新指标」这类跨分支漂移，非常值得在其他「单一数据源」重构中复用；三是 `histogram_buckets` 明确返回新副本的契约，为将来「默认值 + 用户覆盖」的合并逻辑留出了安全边界。审阅时建议继续追问两点：五个指标共享同一 `list` 实例是否应改为各自取副本，以及未知家族键是否应统一抛 `ValueError`——这两点都会在 #48867 落地时被放大。

对齐 vLLM 与 Transformers 的 YaRN，修正 YaRN 变体 max_model_len 二次缩放

值得精读，尤其是三个设计决策：(1) 为什么用预计算 `attention_factor` 而不是 `mscale: 0.7`（上游只在 `mscale_all_dim` 为真时才看 `mscale`，否则会得到 1.1386 而非 1.0970）；(2) 为什么把修复从“给别名打补丁”改为“对整个 YaRN 家族套用上游规则”，并顺势删除重复类；(3) 为什么把 `apply_yarn_scaling` 重拼为 `attention_factor` 而不是保留别名——结果是 RoPE 字典的每个键都成为 Transformers 键，`ignore_keys_at_rope_validation` 这类 workaround 随之消失。阅读时应同时留意作者自述的验证缺口：`Model evaluation — Not yet run — needs a GPU run before merge` 并未在合并前补齐。若下游确实在生产使用 TeleChat3、sarvam-105b 或任何带 `mscale`/`mscale_all_dim` 的 YaRN 模型，建议自行补一次长上下文精度与输出一致性回归，并确认新默认 `max_model_len` 与现有部署配置兼容。

Cosmos3-Edge 内层语言模型显式传入文本架构

值得精读，但不是因为代码量：改动只有 3 行，真正有信息量的是 PR body 里的根因表与两条失败链（CPU 的 use_mla -> self.architectures[0] IndexError、PP 的 is_pp_supported_model -> inspect_model_cls ValueError）。建议关注三个设计点：一是把修复放在模型实现侧而不是 ModelConfig._get_transformers_backend_cls() 加通用兜底的取舍论证；二是显式声明 `NemotronHForCausalLM` 与内层实际类 Cosmos3EdgeForCausalLM 的对应关系；三是内层 hf_config 从顶层多模态配置切换到 text_config 带来的字段来源变化。此外，hmellor 对 MODEL_MAPPING_NAMES 与 MODEL_FOR_CAUSAL_LM_MAPPING_NAMES 的区分是理解 vLLM 配置推断边界的好材料。后续建议补一个断言内层 architectures 非空的单元测试或小模型 CPU 初始化用例，把这层契约固化下来。

Qwen3 reranker 缺模板时启动告警

值得精读的防御式 bugfix 范例：改动面小（源码 21 行 + 测试 147 行）、动机数据扎实（issue 中给出量化对比表）、review 反馈有效改善了实现健壮性。建议关注两点设计决策：一是用配置标志（`is_multimodal_model`）而非字符串匹配选择模板；二是用 `getattr` 默认值保证对非 reranker 模型零侵入。若团队日常部署 Qwen3 reranker，建议直接采用；后续可考虑把 issue 提案第 2 项（无模板时自动回退到内置模板）作为可选项落地。