TRT-LLM KV cache 复用速查:paged KV 与 reuse 标志的行为差异、命中率验证方法
更新时间:2026-10-06。前面 前缀缓存与 prompt 复用 讲过前缀复用的通用机制,PagedAttention 讲过分页 KV 的 block 管理。TensorRT-LLM(下称 TRT-LLM)里这两件事由两个独立开关控制——
paged KV cache和KV cache reuse——它们的组合语义比表面看起来微妙,配错的表现是「以为开了复用其实没开」。本篇把行为差异和验证方法一次说清。
本文要回答的问题
- paged KV cache 和 KV cache reuse 两个开关各自管什么,组合起来有几种行为?
- 复用命中是 exact match 还是 partial match,block 粒度怎么影响命中率?
- 怎么确认复用真的生效了,命中率怎么量?
一、两个开关的组合语义
paged KV cache(构建引擎时的 paged_kv_cache 选项)管的是存储结构:KV cache 按固定大小 block 分页管理,序列的 KV 不必占连续显存,消除内部碎片。它是现代 TRT-LLM 部署的事实默认,关掉它用的是早期的连续 KV 布局,长上下文并发能力大打折扣——但注意,分页本身不等于复用,它只是让「不同序列共享同一份物理 block」在结构上成为可能。
enable_kv_cache_reuse(Executor/调度器侧配置)管的是策略:调度器在请求进来时,把新请求的 prompt 前缀按 block 切块,在 KV block 池里查找内容相同的已缓存 block,命中则直接引用、跳过对应段的 prefill 计算。这个开关依赖 paged 布局,没开 paged 它无从生效。打开后调度器还多了两件事要做:给每个被复用块维护引用计数(最后一个引用者结束时才真正回收),以及在显存紧张时按 LRU 顺序驱逐未引用的缓存块——所以复用不是纯收益,调度开销和显存里「缓存块驻留」的机会成本都要算,只是在前缀共享度高的场景收益远大于成本。
两个开关的生效层级也不同:paged 是引擎构建期决定,写进 engine 文件,换它要重建引擎;reuse 是运行期配置,改 Executor 配置重启服务即可。这个差异在排障时很重要——怀疑 paged 没开,查的是引擎构建参数;怀疑 reuse 没生效,查的是运行时配置和服务日志。
| paged | reuse | 实际行为 |
|---|---|---|
| 关 | 关 | 连续 KV,无复用,旧式布局 |
| 关 | 开 | 配置无效或引擎报错(版本而异) |
| 开 | 关 | 分页存储但每请求独立计算前缀 |
| 开 | 开 | 分页加前缀复用,生产推荐 |
第三种组合是最常见的配置事故:很多部署文档只强调开 paged,运维配完看到显存利用率正常就收工,完全没意识到前缀复用没开——多轮对话和共享系统提示场景的 prefill 算力白白多花几倍,而且因为功能完全正常、只是慢,这类问题往往以「容量规划不足」的假象存在很久。
二、复用的匹配规则:block 粒度的 exact match
TRT-LLM 的复用是 block 级精确匹配:prompt 按 block 大小(默认常见 32/64 token)切成块,每块的 token 序列做哈希,和缓存池里 block 的哈希比对。两个推论直接决定命中率成色。
第一,前缀必须 block 对齐才能命中。两个请求共享 100 token 前缀、block 大小 32,则前 3 个完整块(96 token)可复用,余下 4 token 所在的部分块无法匹配,要从那里重新算。系统提示词长度最好对齐到 block 的整数倍,差几个 token 就浪费一整块的 prefill。
第二,任何位置不同的 token 都会让该块及之后全部失配。RAG 场景把可变内容(检索结果)放在固定模板之前是致命错误——第一个不同块之后的所有块哈希全变,哪怕后半段文本完全一样也命中不了。正确的 prompt 组织是「固定内容在前、可变内容在后」,这与 prefix caching 通用原则 一致。
还有一个版本相关的细节:较早版本的 TRT-LLM 复用只针对已完成的请求释放到池里的 block,进行中的请求 KV 不可被复用;新版本支持复用进行中请求的 block(涉及引用计数)。升级后如果发现命中率异常低,先核对所用版本的这一语义。
驱逐策略对命中率的影响也值得单独一段。KV block 池的显存配额由 kv_cache_free_gpu_memory_fraction 之类的参数划定,池子越小,LRU 驱逐越频繁,长模板刚缓存就被挤出。经验上复用收益明显的场景,池子至少应能装下「活跃前缀种类数 × 平均前缀 block 数」的 1.5 倍以上;RAG 服务模板就几个、池子压力小,多租户 Agent 服务前缀百花齐放,池子要按实测命中率回推。驱逐计数在指标里可查,命中率低且驱逐率高的组合就是「池小了」的明确信号——要么加显存配额,要么降低并发给缓存腾地方,两者怎么选看 TTFT/TPOT SLO 的优先级。
三、验证方法:日志、指标、对照实验
TRT-LLM 的复用同样是「配了不等于生效」,验证三板斧。
第一板斧,日志与指标:Executor 的统计输出里有 KV cache 相关计数(不同版本字段名略异,找 reuse/hit 字样),kvCacheUsage 之外重点看复用命中的 block 数;Triton 部署时这些指标经 metrics 端点暴露,接 Prometheus 画图。
第二板斧,TTFT 对照实验:构造两组各 100 条请求——A 组共享 4000 token 系统提示,B 组每条 prompt 完全独立。开复用后 A 组的平均 TTFT 应显著低于 B 组(省掉共享段 prefill);如果两组无差异,复用没生效,回查开关组合和 block 对齐。
第三板斧,算力侧交叉验证:nvidia-smi 或 Nsight 看 prefill 阶段的 SM 利用率,命中时 prefill 步的计算量应按复用比例下降。TTFT 受排队影响有噪声,SM 侧的下降是更硬的证据。板斧的使用顺序也有讲究:先看指标确认开关层面的状态,再做 TTFT 对照确认业务收益,最后 SM 侧只在两者矛盾时用来裁决——日常巡检跑前两步足够,别每次都上 profiler。
命中率公式好记:命中 block 数 / 总 prompt block 数。健康基线——多轮对话场景 70% 以上,RAG 共享模板场景 60%~90%(视模板占比),纯独立 prompt 场景接近零属正常,别拿它当故障。命中率突然下跌通常三个原因:prompt 模板变更破坏了对齐、KV block 池显存被调小导致驱逐加剧(复用块被 LRU 挤掉)、升级后语义变化。
最后补一个容易和复用混淆的特性:beam search 内的 KV 共享。beam search 的多条 beam 共享同一 prompt 前缀,TRT-LLM 对此有独立的优化路径(引擎内的 beam 宽 prefix 共享),它不依赖 reuse 开关、也不体现在复用命中率指标里。开 beam search 的服务测复用命中率时要把这部分流量剔除或用贪心采样流量测,否则数据互相污染,结论没法看。同理,投机解码(见 投机解码草稿模型)的草稿验证 KV 与复用机制在部分版本里有交互限制,组合开启前查版本 release note 的组合矩阵。
这一篇在知识体系里的位置
本篇是推理引擎配置速查线的 TRT-LLM 分支:上游 前缀缓存与 prompt 复用(机制)、PagedAttention(分页 KV 原理);同层 TensorRT-LLM in-flight batching(调度器)、TensorRT 推理优化(引擎构建)、SGLang Radix 前缀缓存(另一引擎的对照实现)。
总结
TRT-LLM 的前缀复用由两个开关叠加生效:paged_kv_cache 提供 block 化存储结构、enable_kv_cache_reuse 打开按块哈希的复用策略,「只开 paged 没开 reuse」是最常见的配置事故;复用是 block 粒度的精确匹配,要求共享前缀放在 prompt 最前且按 block 大小对齐,可变内容一律后置;验证走「日志命中计数、共享前缀组与独立组的 TTFT 对照、prefill 阶段 SM 利用率」三板斧,命中率健康基线多轮对话 70% 以上,突跌先查模板对齐、池显存水位和版本语义变化。