KV 水位是什么
KV 水位指 KV 池被占用的比例，vLLM 里对应 gpu_cache_usage_perc 这类指标。它的正确用法是与等待请求数一起看：水位高且持续排队说明容量到顶；水位高但不排队说明还有调度余量；水位低却仍排队，说明瓶颈在别处，比如 CPU 侧预处理或网关侧排队。
基本信息
| 核心指标 | KV 池使用率（名称以本机 /metrics 输出为准） |
|---|---|
| 配套指标 | 等待中请求数、运行中请求数 |
| 裕量建议 | 峰值水位留出约 15%~20%，避免长期贴着上限 |
| 影响因素 | 输入长度分布、窗口大小、并发数与是否启用前缀缓存 |
| 阈值有效期 | 模型、量化或引擎版本变化后需重新标定 |
典型使用场景
- 扩容时机：水位持续高位且等待数上涨，是加实例最直接的信号
- 排查排队：卡没满却排队时，转去查 CPU 预处理、网关与实例争抢
- 参数复核：调整窗口或显存比例后，回看水位是否落在健康区间
- 压测找饱和点：逐档加并发，观察水位与延迟同时恶化的拐点
- 长请求预警：输入长度分布右移时，同样的并发会吃掉更多 KV 块
指标速览与组合判断
指标速览与组合判断
# 指标名以本机 /metrics 实际输出为准
curl -s http://127.0.0.1:8000/metrics | grep -E 'gpu_cache_usage_perc|num_requests_waiting|num_requests_running'
# 组合判断：
# 水位高 + 等待数上涨 → 容量到顶，扩容或限流
# 水位高 + 不排队 → 接近上限但还有余量，继续观察
# 水位低 + 仍排队 → 瓶颈在别处，查预处理、网关与实例间争抢水位与排队的四种组合
| KV 水位 | 等待请求数 | 含义 | 动作 |
|---|---|---|---|
| 高 | 上涨 | 容量饱和 | 扩容或限制并发 |
| 高 | 稳定 | 接近上限 | 观察并预留裕量 |
| 低 | 上涨 | 瓶颈不在 KV | 排查预处理、网关、共享卡争抢 |
| 低 | 稳定 | 健康 | 维持现状 |
高水位本身不是故障：KV 池被充分利用是正常状态，真正要动作的信号是排队时长变长、延迟分位恶化。
KV 水位与延迟要联动看：只有把水位曲线和 TTFT/TPOT 曲线叠在一起，才能区分「用得满」和「用得过满」。