[Contribution] 任务 #3：[Docs/Correctness] 固化 layerwise 支持矩阵、配置校验与默认值契约

背景

当前文档将 layerwise 描述为仅支持 Memcache/Prefill，并称 CP、hybrid/multi-group 均不支持；实际代码同时保留 Memcache/GVA 和非 GVA key-based layerwise 路径，支持 kv_producer、kv_consumer、kv_both 的入口，部分 CP attention 已接入 layerwise hook，多 KV group 也已有实现和测试。现状无法从文档和配置反馈中确定哪些组合是正式支持能力。

配置契约也不一致：Memcache/GVA 的 layerwise_prefetch_layers 默认值为 min(layerwise_num_shared_buffers, 8)，非 GVA key-based 路径默认值为 1；discard_partial_chunks 的运行时默认值在两种模式下均为 true，与文档所称 layerwise 默认 false 不符。非 GVA 路径还未拒绝 layerwise_prefetch_layers <= 0，可导致首层未提交却持续等待完成事件。

相关代码路径：vllm_ascend/distributed/kv_transfer/kv_pool/ascend_store。

任务

1. 形成并经维护者确认一张唯一的 layerwise 支持矩阵，至少覆盖：
   • backend：Memcache/GVA、Mooncake key-based、YuanRong key-based；
   • KV role：kv_producer、kv_consumer、kv_both；
   • attention：attention_v1、mla_v1、sfa_v1、DSA 及其实际 CP 变体；
   • cache layout：单 group、hybrid/multi-group、MTP、sparse/non-AttentionSpec、buffer reuse；
   • parallel：TP 一致/不一致、CP、PP。
2. 支持矩阵只使用“支持/不支持”两种发布状态。受支持组合必须有测试和硬件证据；不支持或未验证组合必须在初始化阶段给出包含具体冲突项的 ValueError/NotImplementedError，不得静默进入运行线程。
3. 保持并明确当前兼容默认值：
   • Memcache/GVA：layerwise_prefetch_layers = min(layerwise_num_shared_buffers, 8)；
   • 受支持的非 GVA key-based 路径：layerwise_prefetch_layers = 1；
   • discard_partial_chunks = true，普通和 layerwise 相同。
4. 对所有可进入的 layerwise 路径复用同一套 layerwise_prefetch_layers 解析和范围校验：只接受正整数，或为兼容旧配置接受可无损解析为正整数的十进制字符串；拒绝 bool、浮点数、空字符串、非数字、0 和负数。校验必须在创建 transfer thread 前完成。
5. 更新 kv_pool.md、layerwise_kv_pool.md、参数说明和相关本地化内容，删除“prefetch 一定增加 NPU KV buffer 数量”等未经实现或测量支持的表述。若改变上述运行时默认值，必须单独说明兼容性、实际峰值内存、in-flight 元数据/lease/backend 资源和性能影响。

本任务不包含非 GVA layerwise 性能调优，也不要求把当前不支持的组合实现为支持；允许通过明确拒绝来收敛契约。

验收标准

• 文档只有一份权威支持矩阵，概览页与专题页无 backend、KV role、attention、CP、hybrid/MTP/sparse 或并行配置冲突。
• 每个标为支持的组合至少有配置/路径单测和一项代表性 NPU 验证；每个标为不支持的组合有初始化期拒绝测试。
• 两条 layerwise 路径的默认 prefetch 值、显式覆盖值和 discard_partial_chunks=true 均有断言测试，文档与运行时完全一致。
• layerwise_prefetch_layers 的合法边界及 bool、浮点数、字符串、零、负数测试完整；非法值不会启动线程，也不会进入 wait_for_layer_load()。
• 保留 TP mismatch 的明确拒绝；现有正式支持场景无功能、精度和启动行为回归。

交付件

• PR、支持矩阵和兼容性说明。
• 更新后的用户文档、参数说明及对应本地化更新。
• 配置矩阵、默认值、非法值和支持/拒绝路径单测；代表性 NPU 验证结果。

环境约定

• vllm-ascend：最新 main
• 硬件：Ascend NPU（注明型号 + 卡数 + TP/CP/PP 配置）
• 关联任务池：#9079
• 验收人：@赵鹏博

任务周期

• 发布：2026-08-12
• 回收：2026-09-30