KVPP（实验性）¶

概述¶

KVPP（KV 流水线并行）针对非混合 MLA/SFA 模型，将原本会在 TP 各 rank 间复制的历史 KV 缓存按层进行分布。这减少了每个 rank 的持久化缓存存储占用，使相同的 HBM 容量能够容纳更多的上下文 token 或并发请求。

KVPP can be combined with TP, EP, and PP. With Model Runner V2, it can also be combined with PCP.

KVPP 中的流水线并行指的是 KV 缓存的存储与通信，而模型计算仍保持上述并行配置。关于底层的按层 KV 存储概念，请参见 Z.ai 的 Scaling Pain of Coding Agent Serving: Lessons from Debugging GLM-5 at Scale 中的 LayerSplit。

使用场景¶

KVPP 面向长上下文推理和并发服务负载，这些场景中重复的 KV 缓存限制了可用的缓存容量。对于具有可复用长前缀的负载，它还可以与前缀缓存和 KV 池化结合使用。

在 Ascend 950DT系列产品上，使用 TP8 + EP 在单台八卡节点上运行 GLM-5.2-W4A8C8 时，实测 KV 缓存容量为 6.25×；使用 TP8 + PP2 + EP（38/40 层）在两台八卡节点上运行 GLM-5.2-W8A8C8-mxfp8 时为 5.35×。每次对比均使用相同的模型、硬件和内存预算，分别在关闭和开启 KVPP 的情况下进行。这些容量比仅适用于性能章节中的特定配置；它们不是吞吐量倍数，也不构成对其他模型的保证。

支持的场景¶

支持的模型¶

KVPP 在 Model Runner V1 和 V2 下支持非混合 MLA 和 SFA 模型。将 KVPP 与 PCP 结合使用需要 Model Runner V2。

注意力后端	KVPP 支持	模型范围
MLA	✅ 支持	使用 MLA 的非混合模型
SFA	✅ 支持	使用 SFA 的非混合模型，例如 GLM-5.2

模型还必须满足 vLLM Ascend 的硬件、量化以及注意力后端要求。

支持的特性¶

下表列出了与 KVPP 配合的各项特性组合。这并不意味着所有列出的特性都可以同时启用。

特性或组合	支持情况	条件与限制
Graph mode	✅ Supported	Eager and PIECEWISE.
TP	✅ 支持	KV 缓存在每个缓存副本组内按层分配。
EP	✅ 支持	需要支持 EP 的 MoE 模型。
PP	✅ Supported	Can be combined with KVPP.
分块预填充	✅ 支持	可与 KVPP 结合使用。
前缀缓存	✅ 支持	可与 KVPP 结合使用。
异步调度	✅ 支持	可与 KVPP 结合使用。
LI-C8 和 SFA-C8 缓存布局	✅ 支持	分配遵循实际的 KV 缓存规格。
Speculative decoding	✅ Supported	All speculative decoding methods with fixed K; dynamic K has not been validated.
PCP	✅ 支持	需要 Model Runner V2；缓存在 PCP × TP rank 间共享。
DCP	❌ 不支持	目前无法与 KVPP 结合使用。
P/D 分离	✅ 支持	使用 `MooncakeConnectorV2`（实验性）；仅在 prefill 节点上启用 KVPP。
KV pooling	✅ Supported	Memcache with `AscendStoreConnector`, `kv_producer` or `kv_both`, and whole-block loading.

✅ 支持：在所述条件下支持该特性组合。
❌ 不支持：目前不支持该组合。

使用方法¶

Enable KVPP through enable_kvpp in --additional-config:

vllm serve <model-path> \
    --tensor-parallel-size 2 \
    --enforce-eager \
    --additional-config '{"enable_kvpp": true}'

Replace <model-path> with a supported MLA/SFA model path and select TP according to model size and available devices. The KVPP group size follows TP × PCP and requires no separate setting.

如果启动命令中已包含 --additional-config，请将 enable_kvpp 合并到现有的 JSON 对象中。

组合特性¶

KVPP 可与 EP、PP、分块预填充、前缀缓存和异步调度结合使用。以下示例使用支持 EP 的 MoE 模型：

vllm serve <model-path> \
    --tensor-parallel-size 2 \
    --enable-expert-parallel \
    --enable-chunked-prefill \
    --enable-prefix-caching \
    --async-scheduling \
    --max-num-batched-tokens 32768 \
    --max-num-seqs 12 \
    --enforce-eager \
    --additional-config '{"enable_kvpp": true}'

请根据设备容量和负载调整 token 预算和最大序列数。

For PCP, set VLLM_USE_V2_MODEL_RUNNER=1 and add --prefill-context-parallel-size to the launch configuration. KVPP shares caches across PCP × TP ranks.

For PP, add enable_kvpp to the existing PP launch configuration.

KVPP supports all speculative decoding methods, including MTP, DSpark, and Eagle3, with a fixed number of speculative tokens (K). Dynamic K has not been validated.

配置参数¶

参数	默认值	说明
`additional_config.enable_kvpp`	`false`	启用 KVPP；组大小遵循 TP × PCP。

KV 传输配置¶

PD 分离¶

KVPP supports P/D disaggregation through MooncakeConnectorV2 (Experimental).

Use MooncakeConnectorV2 with kv_producer on the prefill node and kv_consumer on the decode node. Enable KVPP only on the prefill node.

# Prefill node: include {"enable_kvpp": true} in --additional-config.
--kv-transfer-config '{"kv_connector":"MooncakeConnectorV2","kv_role":"kv_producer","kv_port":37000}'

# Decode node: leave KVPP disabled.
--kv-transfer-config '{"kv_connector":"MooncakeConnectorV2","kv_role":"kv_consumer","kv_port":37010}'

每个 worker 使用由 kv_port 及其并行 rank 派生的握手端口。当两个节点运行在同一主机上时，请选择不重叠的端口范围。

Memcache 池化¶

KVPP 支持 kv_producer 和 kv_both 用于 Memcache 池化。kv_consumer 尚未经过测试，不在已验证的支持范围内。

按照 KV Cache Pool (Ascend Store) 中的说明配置 memcache SDK 和 MetaService，然后添加：

--kv-transfer-config '{"kv_connector":"AscendStoreConnector","kv_role":"kv_producer","kv_connector_extra_config":{"lookup_rpc_port":"0","backend":"memcache","use_layerwise":false,"load_async":true}}'

The example uses kv_producer; you can also set kv_role to kv_both. Both roles save and load prefixes in this pooling configuration. Keep use_layerwise=false and discard_partial_chunks=true (the default). Layerwise pooling, KV events, and consumer write-back are not supported with KVPP.

Combining Connectors¶

Use MultiConnector to combine MooncakeConnectorV2 with AscendStoreConnector. KVPP validates the type and role of each child connector. Set the P/D connector to kv_producer and enable KVPP only on the prefill node; child roles are configured independently of the wrapper role. The pooling backend still requires its own SDK and service configuration.

{
  "kv_connector": "MultiConnector",
  "kv_role": "kv_producer",
  "kv_connector_extra_config": {
    "connectors": [
      {
        "kv_connector": "MooncakeConnectorV2",
        "kv_role": "kv_producer",
        "kv_port": 37000
      },
      {
        "kv_connector": "AscendStoreConnector",
        "kv_role": "kv_producer",
        "kv_connector_extra_config": {
          "backend": "memcache",
          "lookup_rpc_port": "0",
          "use_layerwise": false
        }
      }
    ]
  }
}

性能¶

以下在 Ascend 950DT系列产品上对 GLM-5.2 的测量展示了其对缓存容量、首 token 时延（TTFT）和 prefill 吞吐量的影响。单节点和双节点部署使用不同的量化权重；请在每种部署内比较 KVPP 开启和关闭的情况。

测试配置¶

设置	单节点	双节点 PP
硬件	一个节点，配备 8 个 Ascend 950DT系列产品	两个节点，每个节点配备 8 个 Ascend 950DT系列产品
模型	GLM-5.2-W4A8C8	GLM-5.2-W8A8C8-mxfp8
并行	TP8 + EP	TP8 + PP2 + EP，38/40 层划分
通用设置	DSA-CP、chunked prefill、前缀缓存、异步调度、LI-C8、Model Runner V1、eager 模式	与单节点相同
调度与内存	`max_num_batched_tokens=32768`、`max_num_seqs=12`、`gpu_memory_utilization=0.90`	与单节点相同

未启用 MTP 和 SFA-C8。以下所有测量均使用 32K 调度 token 预算。

KV 缓存容量¶

服务自动计算容量，未覆盖 block 数量。单节点数值来自池化测试配置；双节点数值来自非池化服务启动日志。

部署	KVPP 关闭（tokens）	KVPP 开启（tokens）	容量倍数	相同 token 容量下的等效 KV 内存节省
单节点	235,008	1,467,904	6.25×	83.99%
双节点 PP	555,392	2,972,416	5.35×	81.32%

Equivalent KV memory savings are estimated from the capacity ratio and do not represent the same reduction in total HBM usage. Capacity gains depend on the model and parallel configuration.

首 token 时延¶

该测试测量长输入、零前缀命中、低并发的请求。单节点部署使用 GLM-5.2-W4A8C8，配备八个 Ascend 950DT系列产品，采用 TP8 + EP。双节点部署使用 GLM-5.2-W8A8C8-mxfp8，每个节点配备八个 Ascend 950DT系列产品，采用 TP8 + PP2 + EP（38/40 层）。其他服务设置遵循上述测试配置。

输入长度为 32K、64K 和 128K tokens。前缀缓存命中率为 0%，输出 1 个 token。每个结果是客户端并发为 1 时 4 个请求的平均 TTFT。正值变化表示时延增加。

部署	输入长度	KVPP 关闭	KVPP 开启	TTFT 变化
单节点	32K	2.623 s	2.614 s	-0.33%
单节点	64K	5.295 s	5.375 s	+1.52%
单节点	128K	10.901 s	11.268 s	+3.36%
双节点 PP	32K	2.900 s	2.905 s	+0.19%
双节点 PP	64K	4.503 s	4.887 s	+8.53%
双节点 PP	128K	7.805 s	8.665 s	+11.01%

非池化 Prefill 吞吐量¶

每次运行包含 40 个请求，客户端并发为 12，每个请求 128K 输入 tokens 和 1 个输出 token。两种配置中均禁用了 KV 池化。

部署	前缀缓存命中率	KVPP 关闭（输入 tokens/s）	KVPP 开启（输入 tokens/s）	吞吐量变化
单节点	0%	12,492.4	12,205.7	-2.30%
单节点	90%	116,516.2	110,224.8	-5.40%
双节点 PP	0%	21,395.2	18,742.3	-12.40%
双节点 PP	90%	177,375.4	154,717.3	-12.77%

The actual hit rate in all 90% scenarios was 89.9414%. Under these workloads, KVPP increased cache capacity; non-pooling throughput did not improve.

使用建议¶

对于受 KV 缓存容量限制的负载，应优先评估 KVPP。使用真实的输入长度、并发量和前缀分布，对比开启和关闭 KVPP 时的容量、TTFT 和吞吐量，然后选择满足服务延迟要求的配置。

When cache capacity is already sufficient, use measured latency and throughput to decide whether to enable KVPP.