阅读 py-kvcache 时,我最关心一个具体问题:已经知道一个请求的前缀命中了 SSD 缓存,接下来应该加载它,还是直接让 GPU 重算?

命中率只能说明数据是否存在,不能替系统回答这个问题。需要比较的是两条执行路径到达首个输出 token 的时间,而不只是 SSD 的标称带宽。

本文是基于 arXiv:2609.11744v1 的原创阅读笔记,不是论文全文译文。论文结果、源码观察与独立推导分别说明;没有复跑论文的性能基准。

一、先把论文数字放回实验条件里

原文第 7 节使用 vLLM 0.22。下面摘取 H100、Llama 3.2 3B、80k 前缀的 query TTFT 对照;这里的 80k 是 81,920 个 token,LMCache 基线是 0.4.7 的默认磁盘后端。

对照论文报告的加速比
仅磁盘:py-kvcache 开启预加载,对比 LMCache约 2.0×
同一 py-kvcache 磁盘配置,开启与关闭预加载约 1.34×
多层缓存配置:py-kvcache 对比 LMCache约 1.23×

仅磁盘实验使用 50 个并发请求,关闭 GPU 前缀缓存与 break-even 门控;论文多数测量使用 FP16 KV、只生成 1 个输出 token。Bailian 回放则呈现另一面:较弱 GPU 上有收益,H100 上相对 GPU 前缀缓存没有额外收益。

我的解读:这些结果提供的是有条件的证据,而不是项目的永久排名。 2.0× 表示相应 TTFT 约减半,不表示 SSD 带宽翻倍;1.34× 的预加载收益已经包含在开启预加载的完整配置中,不能再乘一次。只输出一个 token 的实验也不能直接推出长时间 decode 的吞吐结论。

二、独立算例:一个命中到底意味着搬多少数据

先不用任何论文中的硬件数字。假设一个没有压缩、没有跨 GPU 分片的普通注意力模型:32 层、8 个 KV head、每个 head 128 维,每个元素占 2 字节。

下面是独立的容量算例,不是 py-kvcache 的接口,也不是论文模型的配置:

def kv_bytes(token_count, layer_count, kv_heads, head_dim, element_bytes):
    return (
        2 * token_count * layer_count * kv_heads
        * head_dim * element_bytes
    )


example_bytes = kv_bytes(16_384, 32, 8, 128, 2)
print(example_bytes / (1024 ** 3))

输出为 2.0,即 2 GiB。开头的系数 2 分别对应 Key 和 Value。这里必须数 KV head,不能不加区分地代入 Query head 的数量。

这意味着,一个“缓存命中”可能对应数 GiB 的读取和传输。省掉的是计算,新增的是另一组成本:查找对象、打开文件、等待存储队列、读入主机内存、传到 GPU,以及必要的同步。

为了避免把这些成本混在一起,我会先写出一个串行近似:

外部加载时间 ≈ 查找与打开
             + 存储排队与读取
             + CPU → GPU 传输
             + 协调与同步

它不是精确预测式。分块流水线能让不同块的读盘与 GPU 传输重叠,预加载还能把部分读取提前完成。它的用途是提醒我们:只用“KV 字节数 ÷ SSD 带宽”估计命中成本,会漏掉多个阶段。

对于部分前缀命中,还要保留另一个维度:未命中的后缀仍然需要计算。假设已有前缀长度为 prefix_tokens,新后缀长度为 suffix_tokens,后缀的注意力仍需访问前缀。它不等价于在空上下文中运行一个同样长度的短请求。

因此,我更愿意用二维实测表比较“总输入长度、可复用前缀长度”,而不是拿一个固定 token 阈值套遍所有请求。上面的容量公式只适用于描述的普通 KV 布局,也不能直接套到所有压缩或潜在表示架构上。

三、结合源码看:数据仍然经过 CPU

以下实现说明来自公开代码核对,而不是把论文段落换一种说法。源码基线固定为论文列出的 790074a,完整提交与文件链接放在文末。

py-kvcache 接入 vLLM 的 OffloadingConnector。调度侧负责判断和组织计划,worker 侧负责执行传输;IoReactor 管理 I/O 队列、staging 槽位和 CUDA 传输。

读取路径可以画成:

等待请求的前缀信息
        │
        ▼
调度侧:查找、准入、预加载计划
        │
        ▼
worker:TransferCoordinator → IoReactor
                                  │
文件 ── io_uring 读取 ──► CPU staging
                                  │
                         CPU → GPU 块复制
                                  │
                                  ▼
                              GPU KV Cache

这里容易产生两个误解。

第一,direct I/O 不等于 NVMe 直接把数据送到 GPU。 liburing_file.py 使用 O_DIRECT,transfer.py 分配对齐的 CPU staging,随后再进行 GPU 块复制。这个设计绕开的是文件数据的常规 page-cache 路径,不是整个主机内存中转阶段。

第二,Python 实现不意味着数据按字节经过 Python 解释器搬运。 Python 组织提交、完成处理和对象状态;底层 I/O 与 CUDA 复制负责数据移动。不过,提交频率、元数据处理和回调仍然可能消耗 CPU,不能反过来断言解释器开销永远无关紧要。

这个实现里,我认为最值得检查的是三组资源约束:

实现机制解决的问题阅读时要检查的边界
iodepth 与单个 reactor用在途 I/O 数量表达存储并行度不要把线程数等同于并行 I/O 数
open_lookahead将提前打开文件与实际数据读取分开控制已打开文件不应无条件占住数据槽位
共享 staging 与引用计数让加载、写回、预加载复用缓冲;相同前缀避免重复读DMA 未完成或仍有使用者时,槽位不能回收

源码还保留前台槽位,并让有真实读取压力时的推测性预加载退让。可选的 LRU/ARC DRAM 缓存也复用这些槽位,而不是为每条路径再分配一整套内存。

一个值得单独记下的小细节是:有界 staging 不等于 staging_mem 是整个进程的硬内存上限。 StagingPool.compute_slot_count() 会取预算换算槽位数与最低槽位数的较大者;reactor 还为复制保留 headroom。预算很小时,实际分配可能高于这个配置值,此外还有对齐和其他运行时内存。部署时应核对实际分配,而不是只读取配置文件。

四、独立时间线:预加载减少的是哪一段等待

“使用异步 I/O”和“把 I/O 提前”不是同一件事。即使 API 立即返回,如果请求已经获得执行机会,却仍然没有所需 KV,用户还是得等。

用一个人为构造的例子说明。假设请求从到达开始,要等待 40 ms 才能执行;读盘需要 30 ms,CPU 到 GPU 传输需要 5 ms。暂时忽略两条路径共同的剩余计算、网络和调度开销,并假设提前读盘不影响其他工作。

路径时间安排到达 GPU 数据就绪的时间
按需读取先等 40 ms,再读盘 30 ms,再传输 5 ms75 ms
到达后立即预加载在前 40 ms 等待窗口内完成读盘,执行时只传输 5 ms45 ms

磁盘仍然读取相同字节,花费相同的 30 ms,但这 30 ms 不再额外延后该请求的数据就绪时间。

这个例子也说明,不能只盯局部百分比:执行机会到来后的加载等待从 35 ms 降到 5 ms,是 7 倍差距;从请求到达计算,则是 75 ms 降到 45 ms,约 1.67 倍。再加上共同开销,端到端比例还会变化。这些数字只是解释时间线的算例,不是论文测量。

对预加载,我会重点追问三个问题:

  • 是否有足够的提前量?请求马上就能执行时,读盘未必藏得住。
  • 数据准备好之后是否能留到使用时?提前读入又被淘汰,只会增加流量。
  • 是否挤占其他请求的资源?一个请求提前完成,不能以整个队列的等待恶化为代价。

因此,预加载的成功率应按“在需要时已经可用并被实际消费”统计,不能只按“提前发出了读取”统计。

五、我的成本判断:是否命中之后,还要决定何时加载

从工程策略看,我会把决策拆成三种,而不是一个缓存开关:

  1. 现在加载。 外部数据已就绪或很快就绪,预计比重算更早完成。
  2. 短暂等待。 后台读取能在有限时间内完成,且暂缓这个请求不会破坏延迟目标或公平性。
  3. 放弃外部命中。 直接重算更合算,或者系统没有可靠的资源余量。

这三种选择是我的策略拆解,不是在宣称论文已经分别评估了每种策略。尤其是暂缓执行,需要可靠的预加载完成信号和明确时限,不能只是把请求留在等待队列中。

这里还有两个容易漏掉的成本。

一个是调度误差。离线校准得到的读取曲线,不一定能代表当前队列已经排着很多写请求、CPU 内存紧张或传输链路竞争时的实际成本。我会给预测保留安全余量,并在收益接近零时避免激进决策。

另一个是写入成本。当前请求没有命中,不代表“缓存功能没有影响当前请求”:为了将来可能发生的复用而保存 KV,也会使用 GPU 复制、CPU 内存和磁盘资源。加载准入与保存准入应该分别检查,不能只优化读命中的路径。

最后,暂缓必须有截止时间;否则对平均 TTFT 有利的策略,也可能让一部分长请求反复让路。只报告平均值,无法发现这种问题。

六、如果复现,我会怎样组织实验

以下是我的验证方案,不是已经执行的测试记录。

  1. 固定版本与语义。 记录推理引擎、connector、模型、KV dtype、block size、CPU 内存预算和缓存后端。比较的是具体实现路径,不是两个项目名字。
  2. 先测两条基线。 一条是 GPU 内命中,另一条是完整重算;再加入 CPU 命中和真正的磁盘读取。区分模型启动预热、缓存填充和正式测量。
  3. 扫描请求形状。 同时改变总长度、可复用前缀、并发、到达间隔和输出长度;特别保留短请求混在长请求中的情况。
  4. 只切一个机制。 固定其余配置,对比预加载开关、DRAM 保留策略或准入策略,避免同时修改内存与并发后把全部收益归给某一个开关。
  5. 记录资源与分位数。 除平均 TTFT,还记录 P50/P95/P99、吞吐、staging 高水位、实际磁盘字节数、传输字节数、CPU 占用和被放弃的预加载。

其中,实际 I/O 字节数非常重要。如果想复用的数据只有 2 GiB,底层却读了更多,首先应该解释重复读取、对齐、块粒度或淘汰重读,而不是先更换 I/O 框架。

我还会做一个“预算收紧”测试:保持请求集合不变,逐步减少 staging 空间,观察系统是平滑降低并行度,还是出现读入、淘汰、再读入的循环。这个测试比单独证明峰值 SSD 带宽更能暴露资源管理问题。

七、工程边界:把原型接起来,不等于完成生产化

从该代码快照的 README 和实现看,它依赖作者修改过的 vLLM 接口,并声明当前只服务单一模型;磁盘文件也没有完整的清理、垃圾回收和淘汰策略。不能把 DRAM 层存在 LRU/ARC,理解为磁盘容量已经受到同样的管理。

另一个边界是可见性与持久性。写入路径先产生临时文件,再通过 hard link 建立最终哈希文件名,避免读者直接看见正在写入的目标对象。但是,能够完整地被其他读者发现,不等于断电后一定持久保存。 Linux 的 O_DIRECT 本身不提供 O_SYNC 的持久化保证;源码另外用 sync_on_store 控制相关 fsync 操作。

如果把它放进长期运行的服务,我会继续验证:空间耗尽如何处理,未完成写入怎样回收,请求取消之后怎样释放引用,多进程并发发布和异常退出如何恢复。这里列的是验收问题,不是在没有测试的情况下断言它们已经有缺陷。

这次阅读留下的最实用判断是:外部 KV 缓存首先是一项带资源预算的执行决策,然后才是一次数据搬运。 是否命中、是否值得搬、什么时候搬、搬完放在哪里,需要分别回答。

参考资料