1. 先搞清楚 Nvidia-smi 为什么对 KV Cache 泄漏“失明”如果你正在用 vLLM 部署大模型而且习惯用nvidia-smi看显存占用那你很可能已经被“骗”过好几次了。最典型的现象是模型跑着跑着nvidia-smi显示显存占用很高但 vLLM 的日志里显示每个请求的 KV cache 占用却不大或者反过来日志显示 KV cache 已经快满了nvidia-smi看到的显存数字却波澜不惊。这个 GitHub 项目 Kvcachescope 解决的正是这种“工具看不到真实情况”的问题。先说结论Nvidia-smi 不是不知道显存里有 KV cache但它不会把 KV cache 单独列出来给你看。它只能报告整张显卡的总显存使用量包括模型权重、激活值、CUDA context、通信缓冲区、临时张量以及 vLLM 管理的 KV cache 池。这些内容全部混在一起从 nvidia-smi 的视角看过去你只能得到一个总数完全不知道 KV cache 到底占了多少、有没有持续增长、是不是泄漏了。适合看这篇文章的人有三类用 vLLM 做生产部署需要判断显存是否够用、KV cache 是否泄漏的运维和算法工程师。正在调gpu_memory_utilization、max_num_seqs、max_model_len等参数但搞不清 KV cache 真实占用的人。想自建一个轻量观测工具把 vLLM 的 KV cache 占用实时可视化的人。最值得关注的点是Kvcachescope 不是去“修复” KV cache 泄漏而是让你能看见它。在排查泄漏问题之前先把观测做起来比盲目改配置有用得多。下面按实际落地顺序拆解。2. vLLM 里的 KV Cache 到底是怎么分配和释放的2.1 PagedAttention 机制决定了 KV Cache 不能直接用 nvidia-smi 看要理解 Kvcachescope 的价值先要理解 vLLM 的 KV cache 管理方式。vLLM 的核心优化是 PagedAttention思路类似操作系统的分页内存管理。KV cache 不是按完整序列分配的而是按固定大小的 block 分配的。每个 block 可以存放若干个 token 的 Key 和 Value 张量。请求过来时vLLM 从显存里预留好的 KV cache 池中取 block请求结束或 token 被淘汰时block 再释放回池中。这个机制带来一个关键结果KV cache 对 vLLM 来说是一整块预先分配好的显存池而不是“用一点涨一点”的动态内存。你在启动 vLLM 时通过gpu_memory_utilization指定显存利用率vLLM 会在 CUDA context、模型权重之后把剩余显存尽量都预留给 KV cache 池。也就是说即使你现在只处理一个请求KV cache 池也可能已经占用了十几个 GB 的显存。nvidia-smi 看到的高显存占用很大概率是 vLLM 预先占用的 KV cache 池。这个数字高不代表泄漏这个数字稳定也不代表一切正常。关键在于池子里有多少 block 是空闲的有多少 block 被占着被占的 block 是否超出了正常请求的峰值。2.2 泄漏的真实形态不是显存总数一直涨而是空闲池不断缩水很多人把“显存泄漏”理解成nvidia-smi里的数字一直上涨涨到某个临界点 OOM。但在 vLLM 场景下更常见的泄漏形态是KV cache 池的总大小不变因为启动时就预分配好了。池中的空闲 block 不断减少因为某些请求结束后block 没有被正确释放回池中。表现为并发请求变多时可用 KV cache 不够触发 preemption 或者请求排队但 nvidia-smi 的显存总数并没有大幅波动。这种情况下你盯着 nvidia-smi 看只会觉得“显存一直很满是不是模型权重太大”或者“显存没有涨应该没泄漏吧” 两个判断都是错的。Kvcachescope 做的事情就是把 vLLM 内部的 KV cache block 分配状况暴露出来让你能看到空闲 block、占用 block、每个序列的 block 分布以及池的使用率变化曲线。有了这些数据泄漏就不再是“感觉”而是可量化的趋势。3. 在本地环境把 Kvcachescope 跑起来3.1 前置条件需要 vLLM 的日志或监控接口先有数据Kvcachescope 本身不是替代 vLLM 的独立系统而是一个观测层。它的数据来源一般是 vLLM 在运行过程中输出的指标或者 vLLM 提供的内部状态信息。因此前置条件是你的 vLLM 服务已经能正常跑起来并且能输出 KV cache 相关指标。实际部署时我建议先把以下环境信息确认一遍vLLM 的版本。不同版本对 KV cache 指标的名称和输出位置可能有差异建议先确认版本再对接。启动参数里是否开启了相关的统计或日志输出。有些版本需要显式开启 metrics 或 profiling 开关。监控环境是否有 Python 和常见数据处理库。Kvcachescope 这类工具通常以命令行或 Web 面板形式运行Python 环境会比较省事。原始材料里没有给出具体的安装命令所以这里不写死。通用做法是先把项目代码克隆到本地然后按照仓库 README 里的依赖列表安装。如果你拿到的版本已经打包成 pip 包那直接安装等待时间会短很多。3.2 先跑一个最小样例单请求、单输出、连续观察我的习惯是任何观测工具第一轮都不上批量先跑最小样例。启动一个 vLLM 服务用一个小模型甚至可以直接用本地已有的量化模型。然后通过 API 发一个请求同时让 Kvcachescope 开始记录。请求完成后看 KV cache 池的占用率是否恢复到请求之前的状态。这里有三个判断点请求开始时空闲 block 是否减少。请求结束时空闲 block 是否恢复。连续发多个相同请求空闲 block 的恢复曲线是否平稳。如果第一条和第二条符合预期说明 vLLM 的基本分配释放逻辑正常。如果第三条出现“每次请求后空闲 block 都少一点点”的阶梯式下降那就基本可以确认存在泄漏趋势。不要一上来就压并发。并发压力大时preemption 本身会触发 block 的多次分配和释放干扰判断。先单请求抓基线再逐步加压。4. 怎么判断是“正常占满”还是“泄漏”4.1 建立基线和阈值不要凭感觉说泄漏观测工具上线后你面对的第一问题是什么算正常什么算泄漏我建议先用一个稳定负载压出基线。比如固定 10 个并发请求连续跑 10 分钟记录 KV cache 池的空闲 block 数量。如果空闲量在初始下降后保持稳定波动在合理范围内那说明没有泄漏。如果空闲量持续阶梯式下降即使速度很慢也值得继续观察。判断泄漏的常见指标是空闲 block 占比持续下降且不随请求结束而恢复。KV cache 池命中率或者重利用率长期偏低。随着时间推移相同请求的响应速度变慢因为可用的 KV cache 空间变小触发更多 preemption。最终在显存没有占满的情况下vLLM 报出类似 KV cache 空间不足的错误。这些现象里前两条是 Kvcachescope 能直接看到的后两条是你需要在业务侧感知的。结合起来判断准确率会高很多。4.2 CPU 和 GPU 侧分开看有些“泄漏”实际上是显存碎片还有一个常见误区就是把所有显存占用异常都归为 KV cache 泄漏。实际上vLLM 运行过程中显存数据会分成几类模型权重固定占用不会变化。CUDA context固定占用取决于 CUDA 版本和模型。激活值每个请求临时产生请求结束即释放。KV cache 池vLLM 预先分配池内 block 动态分配和释放。通信缓冲区多卡环境明显单卡环境占比低。如果 Kvcachescope 显示 KV cache 池的空闲 block 很充足但 nvidia-smi 显示显存已经快满了那大概率不是 KV cache 泄漏而是其他部分吃掉了显存。这时候要去看激活值峰值、CUDA context 大小甚至要考虑显存碎片化问题。反过来如果 nvidia-smi 显示显存还有余量但 vLLM 反复出现 KV cache 不足的报错那才是 KV cache 池内部出现了管理问题或者你配置的gpu_memory_utilization太低导致 KV cache 池本身太小。5. 让观测工具服务生产环境批量、连续、告警5.1 从单机观测到定时采集本地跑通 Kvcachescope 后如果只手动看几次价值有限。真正有用的是让它持续运行把 KV cache 池使用率输出成时间序列。实际操作中可以设置一个定时任务每隔一段时间采集一次指标比如每 30 秒或 1 分钟。采集内容包括KV cache 池总 block 数。当前空闲 block 数。当前占用 block 数。正在运行的序列数量。发生 preemption 的次数。有了这些连续数据就可以绘制趋势线。当空闲 block 占比从稳定状态进入持续下降区间或者 preemption 频率突然升高就应该触发人工排查。这里要提醒一点不要把采集间隔设得太短。KV cache 池的状态变化非常快如果每 100 毫秒采集一次可能只是抓到瞬时抖动看不出趋势。生产环境 30 秒到 1 分钟一次通常足够。5.2 接入日志和告警不要只靠肉眼看面板Kvcachescope 这一类工具如果只能看实时面板那它更适合调试不适合生产监控。更稳妥的做法是把指标输出到日志文件再接入现有的监控系统。我在生产环境里一般会做三件事把 KV cache 池的使用率写入结构化日志比如 JSON 格式方便后续检索。在空闲 block 占比低于某个阈值时产生一条警告日志。把 preemption 计数和请求排队时间关联起来判断是否需要扩容或调整并发参数。阈值怎么定不能只看绝对数字。要看你的负载模型。长期并发高、请求长空闲 block 占比天然会低空闲池从 30% 降到 5% 可能只是负载变化不是泄漏。但如果负载没有变化空闲池持续下降那就是异常信号。阈值的意义不是“低于 10% 就是泄漏”而是帮助你发现趋势异常。5.3 多卡环境要注意每张卡的 KV cache 池独立但需要对照看如果你的 vLLM 服务跑在多卡环境比如两张或很多张 GPU情况会更复杂。vLLM 的 KV cache 会根据并行策略分布到多张卡上但每张卡的显存状态可能不完全一致。这时建议为每张卡单独记录 KV cache 池使用率同时对比各卡之间的差异。如果某张卡的空闲 block 明显低于其他卡而请求分布又是均匀的那可能是负载分配不均也可能是那张卡的显存管理出了问题。还有个细节多卡环境下nvidia-smi的输出包含每张卡的利用率、显存占用、温度、功耗。Kvcachescope 能补充的是“每张卡上 KV cache 池内部状态”。两者要对照起来看而不是只盯其中一个。6. 用参数调整配合观测结果解决 KV Cache 相关问题6.1 先看数据再改gpu_memory_utilization很多人一遇到显存问题第一反应是把gpu_memory_utilization调高。但这个参数不是越高越好。它决定了 vLLM 愿意把多少比例的显存预留给 KV cache 池。调高后KV cache 池变大能容纳更多 token但也意味着留给 CUDA context、激活值、其他缓冲区的空间更小。如果模型本身较大或者并发请求触发大量激活值调太高反而容易导致显存分配失败。正确做法是先用 Kvcachescope 观察 KV cache 池的使用率。如果空闲 block 时长时短说明池容量基本够用不需要调高。如果空闲 block 长期处于低位且 preemption 频率高再考虑调高gpu_memory_utilization或减小max_num_seqs、max_model_len。6.2 并发数、序列长度和 KV Cache 池容量的关系KV cache 池能容纳多少 token取决于三个因素KV cache 池总大小。每个 token 在模型中每层所需的 KV cache 大小。每层使用的 group size 和 head size 等结构参数。简单理解模型越大、层数越多、注意力头越多每个 token 占用的 KV cache 空间就越大。同样的 KV cache 池能容纳的 token 数就越少。如果你发现 KV cache 池频繁打满优先考虑的是降低并发请求数或者降低max_model_len而不是直接加显存。因为 KV cache 的占用与“正在生成的 token 总数”正相关而正在生成的 token 总数等于并发序列数与每个序列长度的乘积。想压住占用砍这两项最直接。6.3 调整参数后重新观察基线是否变化参数调整不能只看服务能不能启动。我建议每次调整后都用固定负载重新测一轮基线相同并发数。相同请求内容。相同持续时间。观察 KV cache 池的空闲率曲线、preemption 次数、平均响应时间。如果调整后 KV cache 池空闲率上升但响应时间明显变慢说明你砍掉的容量超过了实际需求属于过度调整。如果空闲率上升preemption 下降响应时间变化不大那这次调整是有价值的。7. 常见问题与排查链路7.1 KV cache 池使用率很高但服务没有报错这种情况最常见的原因是负载本来就不低比如并发请求多、序列长。先看正在运行的序列数。如果序列数高KV cache 占用高就是正常的。再看 preemption 次数。如果 preemption 一直没有明显增长说明池容量够用只是“繁忙”。注意KV cache 池使用率高不等同于泄漏。泄漏的定义是“请求结束后应该释放的 block 没有释放”而不是“池子被占满了”。7.2 空闲 block 持续下降但显存总量没有变化这种情况很典型。vLLM 启动时已经预分配了 KV cache 池所以 nvidia-smi 的显存总量不会因为池内分配变化而波动。你只能通过 vLLM 内部的指标看到空闲 block 在减少。排查顺序是先看是否单请求连续运行后也下降。如果是说明释放逻辑可能有问题。再看并发场景下的下降幅度。如果并发越大下降越快可能是 block 管理在高并发下出现竞争问题。确认 vLLM 版本。已知的版本缺陷可能影响 block 释放。把观测周期拉长排除偶发抖动。7.3 请求结束后KV cache 占用没有恢复正常如果单请求测试就出现这个问题优先怀疑释放逻辑。检查你的请求是否真的正常结束包括客户端是否断连、输出流是否完整关闭。有些情况下请求尚未完全结束vLLM 会保留对应的 KV cache block这是正常行为不是泄漏。判断标准很简单等客户端连接完全断开后再观察几秒看 block 是否释放。如果恢复正常说明只是时序问题。如果长时间不恢复再考虑 KV cache 泄漏。7.4 多卡环境下各卡 KV cache 占用差异很大先检查请求负载是否均匀分布到各卡。如果负载不均KV cache 占用不均很正常。其次检查模型并行配置。有些并行策略下不同卡存放不同层的 KV cache每层 block 大小不同显存占用自然不同。最后才考虑某张卡存在异常释放问题。7.5 监控工具本身看不到数据这种问题往往不是 Kvcachescope 坏了而是数据源没有配置对。按这个顺序排查先确认 vLLM 服务是否在运行且监控指标确实有输出。确认监控工具的采集路径、端口、权限是否正确。确认采集频率是否过快导致缓冲刷新不及。确认 vLLM 版本和监控工具版本之间是否存在兼容问题。8. 从“看见 KV Cache”到真正解决泄漏问题8.1 观测只是第一步定位才是关键Kvcachescope 这类工具的最大价值不是给你一个好看的仪表盘而是把 vLLM 内部被隐藏的状态暴露出来。它解决的是“盲区”问题而不是“修复”问题。在实际排查中我一般会按这个思路走先用观测工具确认 KV cache 池是否存在持续下降趋势。如果存在区分是负载变化还是释放异常。如果是释放异常去检查请求生命周期、输出流闭合、批量任务是否有异常分支。如果找不到明显问题检查 vLLM 版本和已知缺陷。最后才考虑通过调整参数来缓解而不是根治。8.2 长期生产建议把 KV cache 观测纳入常态化监控如果你只是学习跑 demo手动看一下 KV cache 占用就够了。但如果是生产环境我强烈建议把 KV cache 的观测纳入常态化监控。原因很简单KV cache 泄漏往往不是一瞬间发生的而是慢慢累积的。等到 nvidia-smi 的显存数字出现异常或者服务开始频繁报错影响面已经很大了。而 KV cache 池内部的空闲 block 变化能更早反映问题。具体落地上至少做到三点定时采集 KV cache 池使用率和 preemption 次数。设置趋势异常告警而不是只盯固定阈值。每次升级 vLLM 版本或调整部署参数后重新跑一轮基线。8.3 最后踩坑经验不要只信一个工具我的建议始终是Nvidia-smi 要看Kvcachescope 这类 KV cache 观测也要看但都不要单独依赖。nvidia-smi 适合看整卡资源状态比如显存有没有被其他进程吃掉、GPU 利用率是不是健康、卡的功耗和温度是否正常。 KV cache 观测工具适合看 vLLM 内部的显存池管理情况。 两者结合才能完整判断一个 vLLM 服务的显存健康状况。如果只盯着 nvidia-smi你会忽略 KV cache 池内部的分配和泄漏趋势。如果只盯着 KV cache 池你会忽略 CUDA context、激活值和其他进程造成的显存占用。多视角交叉验证才是生产环境该有的态度。