一行代码,少搬一次:LMCache PR #6062 如何让 SGLang KV Cache 直达 Copy Engine
从零解释 KV Cache、分页内存、NHD/HND layout、LMCache multiprocess 的 kernel 与 direct-copy 两条路径,以及 PR #6062 为什么只加一行 production code 就能补齐 SGLang unified MP 的快速路径。
从零解释 KV Cache、分页内存、NHD/HND layout、LMCache multiprocess 的 kernel 与 direct-copy 两条路径,以及 PR #6062 为什么只加一行 production code 就能补齐 SGLang unified MP 的快速路径。
有些性能 PR 会改几千行代码;有些 PR 的 production code 只有一行,却需要先理解半个推理系统。
LMCache PR #6062 属于后者。它真正新增的代码只有:
case EngineKVFormat::NL_X_NB_BS_NH_HS:
这行代码没有创造新算法,也没有新增 CUDA kernel。它做的是:告诉 LMCache,SGLang unified multiprocess 使用的这种 KV layout,也可以绕过 GPU staging buffer 和 scatter/gather kernel,直接交给 GPU copy engine 批量搬运。
一句话先记住:数据以前也能正确搬,现在可以少绕一次路。
本文基于 PR head
efea9f82(2026-10-26)讲解。文中的 H200 数据来自 direct-copy 框架原有设计文档,不是 #6062 新提交的 SGLang 专项 benchmark。
大语言模型生成下一个 token 时,需要关注前面已经读过的 token。注意力层会为每个历史 token 计算 Key 和 Value;如果每生成一个 token 都把之前的 Key/Value 重新计算一遍,序列越长,重复计算越多。
KV Cache 就是把这些结果保存下来:
读过 token → 算出 K/V → 放进 KV Cache
生成下一个 token → 直接复用旧 K/V,只计算新增 token
可以把它理解成模型的“推理记事本”。模型不必重读整本书,只需要查看已经写好的笔记。
但这个记事本非常大。一个服务同时运行许多请求时,KV Cache 还会不断增长、释放和复用。如果每个请求都要求一整段连续显存,内存很快会碎片化。因此 vLLM、SGLang 等推理引擎通常把 KV Cache 切成固定大小的 page,也叫 block。
常见的物理形状是:
[NB, BS, NH, HS]
NB = Number of Blocks,block 数量
BS = Block Size,每个 block 放多少 token
NH = Number of Heads,KV head 数量
HS = Head Size,每个 head 的宽度
例如 [96, 16, 8, 128] 表示 96 个 block,每个 block 容纳 16 个 token,每个 token 有 8 个 KV heads,每个 head 宽 128 个元素。
请求看到的是逻辑 token 0、1、2……,GPU 看到的却可能是物理 block 37、8、52……。两者靠 block table 对应:
逻辑 token 0~15 → 物理 block 37
逻辑 token 16~31 → 物理 block 8
所以,把一个 LMCache chunk 搬回推理引擎时,不能对整个 KV pool 做一次大 memcpy;必须按 block ID,把每段数据放回正确页面。
LMCache 把 KV Cache 从推理引擎的本地显存扩展到 CPU 内存、磁盘或远端存储。这样,相同前缀再次出现时,可以取回以前计算过的 KV,而不是重新做完整 prefill。
在 multiprocess 模式下,可以先把问题简化为两个方向:
真正困难的不是 H2D 或 D2H,而是两端的内存形状不同:LMCache object 面向连续 token,engine cache 面向离散 page。LMCache 必须完成 gather 或 scatter。
最通用的做法分两步:
Pinned host object
⇅ cudaMemcpyAsync
GPU staging buffer
⇅ block-transfer CUDA kernel
Engine paged KV Cache
以 retrieve 为例:先把连续的 LMCache object 拷进 GPU staging buffer,再启动一个 CUDA kernel,根据 block IDs 把 staging 中的 token 分散到不同 paged blocks。Store 则反过来 gather。
这条路径的优点是兼容性强。即使 engine block 内部的字节顺序和 LMCache object 的 token-major 顺序不同,kernel 也可以逐 token、逐 head 计算地址并完成重排。
代价也很明确:
PR #5308 为 LMCache-driven transfer 增加了 direct-copy 路径。CPU 预先把每个源地址、目标地址和长度算好,再用 cudaMemcpyBatchAsync 一次提交多段 copy:
Pinned host object
⇅ cudaMemcpyBatchAsync
Engine paged KV blocks
这里需要区分 GPU 的两类执行资源:
Direct copy 的价值不是减少最终需要传输的字节,而是删掉中间落点和 scatter/gather kernel。
但它有一个硬条件:每个 paged block 必须是一整段连续字节,而且字节顺序要和 LMCache object 的 token-major 顺序一致。 只有这样,一条 memcpy entry 才能表达“搬这个 block”,而不需要 kernel 帮忙重排。
这也是 NHD 和 HND 很重要的原因:
NHD: [Block Size, Num Heads, Head Size]
一个 block 的所有 token 连续摆放 → 可以整块 memcpy
HND: [Num Heads, Block Size, Head Size]
某些按 token 组织的传输会跨 head 分段 → 不能总用一段 memcpy 表达
Direct copy 不是配置开关。只要 build、driver 和当前 object group 都满足条件,LMCache 就自动选择它;否则安全回退到 kernel 路径。CUDA 需要 runtime/driver 支持 CUDA 12.8 的 batch memcpy;ROCm/HIP 路径还带有显式 opt-in 和 host-pointer 能力检查。
SGLang 的 unified KV cache 会把不同 cache component 统一交给一套管理框架。对于普通 MHA,K 和 V 仍然是不同的物理 allocation;在 unified MP 注册时,它们被摊平成一个独立 tensor 列表。
传统 SGLang MP 表示更像:
[
[K_layer0, K_layer1, ...],
[V_layer0, V_layer1, ...],
]
而 unified MP 暴露的是:
[
K_component0,
K_component1,
...,
V_component0,
V_component1,
...,
]
每个 component 自己都是 [NB, BS, NH, HS]。LMCache 为它定义了 EngineKVFormat::NL_X_NB_BS_NH_HS,枚举值为 18。
这段命名很容易把初学者绕晕:
_ 表示同一个 tensor 内的维度;_X_ 表示跨 Python list 的层级;NL_X_NB_BS_NH_HS 表示“一个列表,列表中每个 tensor 是 [NB, BS, NH, HS]”。更关键的是,format 18 把每个 K 或 V component 当作一个独立 entry,因此它的 kv_size 是 1。K/V 不再是 tensor 内部需要额外寻址的轴。
case 就够了Direct-copy executor 不想在每个 copy entry 上反复判断 layout。它先调用 resolve_block_addressing(),把 layout 一次性翻译成:
address = base
+ kv × kv_stride
+ layer × layer_stride
+ block_id × block_stride
PR #6062 把 format 18 放进了这组已有 case:
case EngineKVFormat::NL_X_NB_BS_HS:
case EngineKVFormat::NL_X_NBBS_ONE_HS:
case EngineKVFormat::NL_X_NB_BS_NH_TWO_HS:
case EngineKVFormat::NL_X_NB_BS_NH_CS:
case EngineKVFormat::NL_X_NB_BS_NH_HS: // 新增
out = {B::kPerLayer, 0, 0, blk, tight};
return true;
{B::kPerLayer, 0, 0, blk, tight} 的含义是:
| 字段 | 值 | 解释 |
|---|---|---|
| base | kPerLayer |
每个 component 直接使用自己的 base pointer |
| kv stride | 0 |
tensor 内没有额外 K/V plane |
| layer stride | 0 |
component 之间不用固定 stride;每个 entry 已有独立 pointer |
| block stride | blk |
block b 从 base + b × blk 开始 |
| copy bytes | tight |
搬运 BS × NH × HS × element_size 字节 |
于是 format 18 的实际公式非常简单:
block_address(component, b)
= component_base_pointer
+ b × BS × NH × HS × element_size
为什么这行以前缺失,却没有造成数据错误?因为原有 block-transfer kernel 已经在 calculate_engine_global_offset() 中支持 format 18。缺的是 direct-copy 地址表,不是基本传输能力。
所以前后行为是:
修改前:format 18 → direct-copy 不认识 → fallback kernel → 正确但多绕一步
修改后:format 18 → 得到 BlockAddressing → batch memcpy → 正确且路径更短
表驱动代码最危险的地方,是一行看起来显然正确,但可能把错误的 layout 声明成“连续”。一旦地址公式错了,结果不是普通异常,而可能是静默写坏 KV Cache。
因此 #6062 增加了两层 GPU 测试:
[NB, BS, NH, HS] geometry,在 store 和 retrieve 两个方向比较 direct path 与 kernel reference,要求 bit-exact 一致;同时更新 eligibility table。GPUCacheContext,指定 EngineType.SGLANG 和 kv_list_layout=unified,先验证 detector 得到 format 18,再从公开的 transfer_kv_per_object_group() 入口分别走 kernel/direct 路径。Planner 测试还覆盖 skip_first_n_tokens。这是 retrieve 时的重要并发保护:已经由 APC 共享、可能正在被其他请求读取的前缀 GPU blocks,不能被重复覆盖。
测试代码多于功能代码不是浪费,而是在证明这行“资格声明”满足它隐含的内存连续性合同。
Direct copy 并非所有场景都更快。每个 (kv, layer, block) 都要生成一个 batch entry,CPU 也有提交成本。原设计文档给出的 H200 经验值约为每个 entry 0.6 微秒,break-even 大约在 34 KB/entry;小到 4 KB、16 KB 的 block 反而可能不如 kernel path。
它最适合:
原 direct-copy PR 在 Kimi Linear 的 1.1 MB block 场景中,把 128k-token store 从每 rank 26.6 ms 降到 19.7 ms。这说明框架为什么值得做,但不能直接当作 #6062 在 SGLang 上的加速结论。#6062 当前提供的是路径与 bit-exact 正确性测试,没有附带 SGLang 专项性能数据。
[NB, BS, NH, HS],具备 direct-copy 条件。resolve_block_addressing() 同时承担资格判断和地址 recipe;补一个 case,就能让已有框架自动选择更短的 copy-engine 路径。这就是为什么一个真正只有一行 production code 的 PR,背后仍然涉及 KV Cache、分页内存、tensor layout、CUDA copy engine、multiprocess planner 和测试合同。