当一个 vLLM Block 不再等于一个 KV Page:LMCache PR #6019 详解
从 KV cache、block table 和 kernel page 的零基础概念讲起,解释 LMCache 为什么会把 kernel paging 误判成压缩、缓存命中为何可能静默恢复错误 KV,以及 PR #6019 如何用 num_blocks、k 检测和 block-to-page 展开修复全部 MP 传输路径。
从 KV cache、block table 和 kernel page 的零基础概念讲起,解释 LMCache 为什么会把 kernel paging 误判成压缩、缓存命中为何可能静默恢复错误 KV,以及 PR #6019 如何用 num_blocks、k 检测和 block-to-page 展开修复全部 MP 传输路径。
大多数 KV cache 代码都默认一件看起来很自然的事:vLLM 给出一个 block ID,KV tensor 的第一维就能用同一个数字索引。
这个假设在很多 backend 上确实成立。但如果 attention kernel 使用的 page 比 vLLM 配置的 block 更小,它就会突然失效:一个 engine block ID 背后其实有多个连续 tensor page。LMCache 若仍把 block ID 直接当 page ID,程序不会越界,也不一定报错,却会搬错 KV。第二次请求看似命中了缓存,模型读到的却可能是错位的历史上下文。
这就是 LMCache PR #6019 解决的问题。本文基于 2026-10-29 的 PR head e2b0bf4d。重点不是逐行复述 diff,而是把背景、坐标系、误判原因、修复边界和兼容策略完整串起来。
大模型生成文字时,每个新 token 都要回看此前 token 的 Key 和 Value。把历史 K/V 每次重新计算一遍很浪费,所以推理引擎把它们保存在显存里,这就是 KV cache。
请求长度不同、结束时间也不同。如果给每个请求预留一整段连续显存,会有大量浪费。vLLM 因此把 KV cache pool 切成固定大小的块,用 block table 把请求的逻辑 token 映射到物理块:
tokens 0..127 -> engine block 3
tokens 128..255 -> engine block 7
这里的 3 和 7 不是 token 编号,而是 KV pool 中的物理 block ID。LMCache 接到 STORE / RETRIEVE 时,也会收到这样的 ID 列表。
为了避免术语互相覆盖,先固定本文的四个词:
在最简单的情况里,四者很整齐:一个 engine block 覆盖 128 token,一个 tensor page 也有 128 slot,于是 block ID == page ID。
--block-size 128 表达的是 vLLM 调度侧一个 block 覆盖 128 个 token,却不保证每个 attention kernel 都用 128-token page。backend 可能只支持更小的 kernel block size。
PR 的 A10 复现中,FlashInfer 的 page 上限是 64 token。于是:
tokens_per_block = 128
slots_per_page = 64
k = 128 / 64 = 2 pages per engine block
一般化以后,engine block b 的 page 范围是:
因此 [3, 7] 在 k = 2 时必须变成 [6, 7, 14, 15],而不是继续使用 [3, 7]。
engine block ids
tensor page ids
LMCache 早就要处理另一种情况:slot compression。例如一个 engine block 逻辑上覆盖 128 token,但 tensor 只给它 64 个 slot。这时 tokens_per_block > slots_per_block,确实意味着一个压缩比例。
kernel paging 表面上也满足类似关系:一个 page 只有 64 slot,而 engine block 有 128 token。区别是缺少的 64 slot 没被压缩掉,而是在紧邻的第二个 page 里。
只看单页 shape 时,两者会混在一起:
slot compression: N engine blocks -> N tensor pages, each page has fewer slots
kernel paging: N engine blocks -> N × k tensor pages, k pages tile one block
旧的 LMCache 逻辑主要从 tokens_per_block 和单页 slots_per_block 推断压缩。它不知道 vLLM 总共分配了多少 block,因此也无法用 tensor 的 page 总数验证“是不是每个 block 恰好有 k 页”。
后果分三条路径:
1/k,并用 block ID 错索引 page;最危险的是前两种:请求仍能返回文本,但缓存命中结果和冷请求不一致。
num_blocks 带到注册协议要区分两种情况,LMCache 需要同时知道:
PR 给 EngineGroupInfo 新增 num_blocks。vLLM 从 KVCacheConfig.num_blocks 填入这个值;connector 私有的 auxiliary pool 没有这层含义,继续报告 0。
在 protobuf 里它是新的 field 7,在 msgspec 结构里有默认值 0。因此旧发送方没提供该字段时,接收方仍能解码,0 的语义就是“未报告”。
检测规则可以写成:
这个规则比“看到 slots 少就猜”强,因为它要求数量关系和容量关系同时闭合。
修复不是把所有 block 数乘以 k。有些逻辑讨论的是“请求有几个 engine block”,有些逻辑讨论的是“tensor 要访问几个 page”。两者必须留在各自坐标系。
仍按 block ID 计数的部分包括:
只有真正进入 gather / scatter、也就是 tensor 第一维被索引时,才调用 expand_block_ids_to_pages。
def expand_block_ids_to_pages(block_ids, pages_per_block):
if pages_per_block == 1:
return block_ids
return [
block_id * pages_per_block + offset
for block_id in block_ids
for offset in range(pages_per_block)
]
这条边界有两个好处。第一,k = 1 的普通 backend 完全保持旧行为;第二,null chunk、窗口和多 group 同步仍使用调度器原本的语义,不会因为物理 page 变多而虚构出更多逻辑 chunk。
LMCache MP 不是只有一个复制入口。PR 覆盖了:
其中 single-group 特别容易漏掉:它为了减少开销,会绕过 KVLayerGroupsManager 的多 group 建模。因此 PR 需要在 single-group 注册分支单独检测 k,把 chunk 中的 page 数注册正确,并在同步、异步、读取三个入口都展开 ID。
physical pages moved
slots_per_block 和 slots_per_engine_block 不再是同一个数PR 把单个物理 page 的 slot 数保留为 shape_desc.bs / slots_per_block,再新增语义:
slots_per_engine_block = slots_per_page × kernel_pages_per_block
压缩比例必须用后者计算。否则 64-slot page × 2 明明完整覆盖 128 token,却仍会被算成 2:1 压缩。
calculate_num_blocks 现在数的是 tensor page函数名里的 block 容易让人误会。对 kernel-paged group,它返回的是 transfer kernel 要处理的 page 数。需要回到 engine block 数时,再除以 kernel_pages_per_block。
某些已知 layout 可以在 connector 侧把多 page zero-copy re-view 成一个逻辑 block,但这个 edit 只对它认识的格式安全。PR 选择在 LMCache 的 page 计数层处理,因此 format detector 支持的布局都能共享规则,不必为每个 backend 猜一套 shape 重写。
PR 描述给出了 A10、vLLM 0.32.0、--block-size 128、LMCache chunk 256 的端到端结果。
| 模型 / backend | 路径 | dev 表现 |
PR 表现 |
|---|---|---|---|
| Qwen3-8B / FlashInfer | lmcache-driven | 命中后文本变化,无错误 | 与冷请求一致 |
| Qwen3-8B / FlashInfer | engine-driven | inline 命中后文本变化 | inline、SHM 均一致 |
| Olmo-3-7B-Think / FlashInfer | lmcache-driven | 输出退化为重复垃圾文本 | 与冷请求一致 |
| Olmo-3-7B-Think / FlashInfer | engine-driven multi-group | 启动拒绝 compressed group | inline、SHM 均一致 |
FlashAttention 的 k = 1 对照组保持原行为。测试还覆盖检测 fallback、page 展开、null chunk 仍按 block 计数、store→retrieve round trip,以及 single/multi-group 的同步和异步入口。
这里最值得记住的不是某个模型名称,而是验证标准:缓存命中不仅要成功返回,还必须与同一请求的冷结果一致。 silent corruption 的系统不能只检查“有没有 exception”。
这个修复有意保留了几个边界:
num_blocks = 0 表示 engine 未报告,检测回退到 k = 1;兼容旧协议,但也意味着无法凭空识别 kernel paging;slots_per_page × k == tokens_per_block 时成立;不满足就不冒险猜;num_blocks;k = 1 返回原 block ID 列表,普通 backend 不增加额外映射语义;PR #6019 的本质不是“多搬几页”,而是把一个长期被重合数字掩盖的抽象边界说清楚:
engine block ID 负责调度语义
kernel page ID 负责 tensor 寻址
当两者一一对应时,直接复用编号很方便;当 k > 1 时,这个捷径就变成 correctness bug。num_blocks 让 LMCache 有足够证据识别坐标系,kernel_pages_per_block 保存映射比例,expand_block_ids_to_pages 则把转换压缩在真正的数据移动边界。
对于 KV cache、分页存储和跨进程 GPU transfer,这是一条很通用的工程原则:不要因为两个层次暂时使用相同的整数,就把它们当成同一种身份。
延伸阅读: