[RFC]: Model customized KVCache Planning

快速结论：这属于 vLLM 的 RFC/设计讨论，不是普通的运行时报错。核心议题是 [RFC]: Model customized KVCache Planning，也就是把 KV Cache 的分组与规划从核心层下放到模型层，以适配 DeepSeek-V4 这类包含多种 Attention 类型的模型。优先排查方向是确认你所用的 vLLM 版本是否已包含 #53558 引入的可插拔 KVCacheConfigBuilder。

适用环境：Issue 中未提供可确认的操作系统、Python、CUDA、PyTorch 或显卡版本。涉及对象为 vLLM 的 V1 KV Cache 规划代码（vllm/v1/core/kv_cache_planning.py、kv_cache_utils.py）以及模型层、Platform 层接口。

最快修复方案：暂无确认的一步修复方案。该 Issue 最终以设计文档形式推进，并通过 PR #53558 以实验性方式实现；如需使用自定义 KV Cache 规划，可优先尝试升级到包含该 PR 的 vLLM 版本，并参考新的 Builder 接口。

注意事项：#53558 中的实现被标注为 experimental，接口可能变化。Issue 讨论还明确依赖 #42449（models 层与硬件解耦、移除 UniformTypeKVCacheSpecs）的进展，因此旧方案不一定适用于后续版本。

问题场景

用户在做 vLLM 推理框架的二次开发或模型适配：模型包含混合 Attention（如 Gemma3、Qwen3.5、Bailing 等），或者像 DeepSeek-V4 那样同时存在 7 种 KV Cache 类型。原有 KV Cache 规划逻辑集中在 kv_cache_utils.py，并依赖 UniformTypeKVCacheSpecs、页面大小对齐和 num_layer_tuples 个张量等 DeepSeek-V4 专用逻辑；这些逻辑被硬编码在核心层，导致代码架构不合理，也难以扩展到新的复杂模型。

报错原文

[RFC]: Model customized KVCache Planning

原因分析

可能原因：这并非运行时异常，而是设计层面的问题。核心 KV Cache 规划流程（合并各 worker 的 spec、分组、覆盖 num_blocks、自动修正 max model len、创建 KVCacheTensor/KVCacheConfig）把模型专属的复杂分组逻辑塞进了通用核心代码。模型层又正在推进与硬件解耦（#42770），因此有维护者担心再引入模型专属 Planner 会让模型层更复杂。

环境排查

确认 vLLM 版本是否已包含 #53558，以及是否仍暴露 ModelConfig.kv_cache_planner_cls；该方案在讨论中已被调整，最终采用平台 Hook + SupportsKVCacheGrouping 类方法。
确认 vllm/v1/core/kv_cache_planning.py 中是否仍在 monkey-patch 规划函数（例如 vllm-ascend 的自定义 planner），若存在，需迁移到 Builder 接口。
确认目标模型是否符合混合 Attention 场景（Attention 类型数量、是否需要页面大小对齐）。
确认 #42449 是否已合入，它计划移除 UniformTypeKVCacheSpecs，会影响旧规划方案的可用性。

解决步骤

先判断是否真的需要模型定制规划：单一 Attention 类型或 2 种以内混合 Attention 的模型，保持默认 DefaultKVCachePlanner/默认规划流程即可。
若模型确实有复杂 KV Cache 结构，升级到包含 #53558 的 vLLM 版本，改用可插拔 KVCacheConfigBuilder：由 Platform Hook 选择 Builder，模型侧只通过 SupportsKVCacheGrouping 类方法提供分组策略，不再配置 planner 类字符串。
让 Builder 负责张量放置（多个张量、替代打包、slot 布局），内存记账仍由 Core 统一完成；Core 通过 one-block probe 推导每块设备字节数，避免各模型重复实现准入检查与跨 rank 收敛。
若 Builder 使用多个设备分配，可临时覆盖私有的 _get_pool_bytes_per_block，但需注意这是过渡接口，预计随 #42449 的 worker 侧分配方案移除。
移除对 kv_cache_planning.py 的 out-of-tree monkey-patch，改为实现官方扩展点。

验证方法

确认模型可以正常加载并完成 KV Cache 初始化，num_gpu_blocks_override、null-block 预留、auto-fit、准入检查和跨 rank 收敛行为与默认流程一致；自定义 Builder 的张量布局能被正确创建且显存占用符合预期。由于该实现标注为实验性，建议同时对比默认规划路径的显存与吞吐表现。