UCM可观测性指南：确认KV Cache命中率与性能收益的20+项指标完整清单

UCM可观测性指南确认KV Cache命中率与性能收益的20项指标完整清单【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址: https://gitcode.com/ModelEngine/unified-cache-managementUnified Cache ManagerUCM是一款以 KV Cache 为中心的推理加速套件其内置的指标可观测体系默认开启无需额外 exporter 或服务端口即可通过 Prometheus 标准接口暴露 20 项缓存命中率、带宽与时延指标帮助你在 5 秒内确认 UCM 缓存加速是否真正生效。本指南面向新手带你从零看懂 UCM 指标并量化性能收益。为什么需要 UC M 指标把加速收益变成数字 UCM 通过在 Prefill/Decode 阶段提供前缀缓存、缓存加速算法与分级持久化Store 层来降低推理时延。但是否真的加速了不能靠感觉判断——你需要回答三个问题缓存命中率有多少省掉了多少重复计算传输带宽是否达标缓存搬运是否成为瓶颈存储后端是否健康Posix/Mooncake 存储是否可用UCM 默认导出78 个 Counter、14 个 Gauge、64 个 Histogram详见 docs/source/user-guide/metrics/metrics_list.md全部复用 vLLM 的 Prometheus/metrics端点与 vLLM 自身指标共存一套监控体系即可同时观察模型服务与缓存行为。第一步一键确认 UCM 指标已导出 ✅UCM 指标默认启用无需任何配置。启动带 UCM connector 的 vLLM 服务并发送至少一条推理请求后用一条命令验证curl http://vllm-ip:vllm-port/metrics | grep ^ucm:能看到ucm:ucm_hit_tokens_total{...}这样的输出说明指标链路已打通。每个指标都带三个标签方便多实例定位标签含义示例model_name模型名称Qwen3-32BenginevLLM 引擎区分 DP 实例engine-0worker_rankUCM 进程worker 用数字scheduler 用scheduler0、scheduler新手必读UCM 指标在没有推理请求时不会刷新——vLLM 只有在处理请求、调用get_kv_connector_stats()时才会把累积指标同步到/metrics。另外建议 Prometheus 抓取间隔与面板刷新间隔不小于 5 秒更短的间隔并不会让指标更新更快参见 docs/source/user-guide/metrics/metrics.md。三种观测方式Prometheus Grafana 命令行工具 ️按你的环境选择由重到轻方式适用场景特点Prometheus Grafana生产环境长期监控历史时序查询 告警导入官方 dashboard 即可用Metrics-view 命令行工具无 Prometheus、无图形环境直接读/metrics快照或后台采样存入 SQLite 后查询curl直接看快速排障一条命令确认指标是否存在官方 Grafana 仪表盘导入即用UCM 提供 3 个现成 dashboard见 examples/metrics/在 Grafana 中Dashboards → New → Import上传对应 JSON 并选择 Prometheus 数据源文件监控内容grafana_vllm.json请求时延、Token 吞吐、调度器与缓存状态、Store 健康与探针趋势grafana_connector.json聚合带宽、公共接口耗时、Layerwise 逐层加载耗时grafana_store.jsonCache、Mooncake、Posix 三类存储的性能指标没有 Prometheus用 Metrics-view 命令行安装 UCM toolkit 后pip install -e toolkit无需任何监控系统即可查看# 查看当前累计快照 ucm-toolkit run metrics-view check --url http://127.0.0.1:8000/metrics --config vllm # 后台持续采样PD 分离场景可同时采集 prefill 与 decode 端点 ucm-toolkit run metrics-view start --url http://prefill:8000/metrics --url http://decode:8000/metrics --interval 5s # 查询最近 10 分钟按 1 分钟聚合 ucm-toolkit run metrics-view query --window 10m --aggr-by 1m --config metrics_lite内置的vllm/connector/store/metrics_lite配置与上面的 Grafana 仪表盘一一对应命令行看到的数值就是面板上的数值。核心指标清单确认命中率、带宽与健康状态的 20 项 以下按你要确认什么分组都是默认导出的指标完整 156 项清单见 docs/source/user-guide/metrics/metrics_list.md。1️⃣ 缓存命中率指标——UCM 加速是否生效的直接证据指标类型含义ucm:ucm_hit_tokens_totalCounterUCM connector 命中的前缀 Token 总数收益核心指标ucm:total_prefix_query_tokens_totalCounterUCM 观察到的前缀查询 Token 总数命中率分母ucm:gpu_hbm_hit_tokens_totalCounter进入 UCM 查询前已在 GPU/HBM 命中的 Tokenucm:cache_lookup_hit_blocks_total/ucm:cache_lookup_miss_blocks_totalCounterCache 层查询命中/未命中块数ucm:posix_lookup_hit_blocks_total/ucm:posix_lookup_query_blocks_totalCounterPosix磁盘层查询命中/查询块数ucm:mooncake_lookup_hit_blocks_totalCounterMooncake 层查询命中的块数ucm:mooncake_load_hit_shards_total/ucm:mooncake_load_miss_shards_totalCounterMooncake 加载命中/未命中的分片数ucm:interval_lookup_hit_ratesHistogram逐请求的 UCM 查询命中率分布2️⃣ 带宽指标——缓存搬运是否拖慢推理指标类型含义ucm:load_bytes_total/ucm:save_bytes_totalCounterConnector 路径累计加载/保存字节数ucm:cache_load_bytes_total/ucm:cache_dump_bytes_totalCounterCache 层累计加载/卸载字节数ucm:posix_s2h_bytes_total/ucm:posix_h2s_bytes_totalCounter磁盘读存→内存/写内存→存字节数ucm:cache_load_bandwidth_gbps/ucm:cache_dump_bandwidth_gbpsHistogram单任务有效带宽分布可看 p50/p90/p99ucm:posix_s2h_bandwidth_gbps/ucm:posix_h2s_bandwidth_gbpsHistogramPosix 每任务读/写带宽分布ucm:mooncake_h2d_bytes_total/ucm:mooncake_d2h_bytes_totalCounterMooncake 主设备间拷贝字节数 两种带宽视角不要混用*_bandwidth_gbps直方图反映单任务瞬时速度系统整体吞吐请用字节 Counter 除以时间窗口下文公式。3️⃣ 时延与排队指标——定位卡在哪个环节指标含义ucm:save_duration进入wait_for_save到异步 Dump 完成的耗时ucm:cache_load_duration_ms/ucm:cache_dump_duration_msCache 层加载/卸载端到端耗时ucm:cache_load_queue_wait_duration_ms/ucm:cache_dump_queue_wait_duration_ms任务在队列中等待被 worker 领取的时间ucm:posix_load_task_duration_ms/ucm:posix_dump_task_duration_msPosix 任务端到端耗时ucm:mooncake_get_duration_ms/ucm:mooncake_put_duration_msMooncake 批量 Get/Put 耗时ucm:layerwise_layer_load_duration_msLayerwise 逐层加载的单层墙钟耗时ucm:connector_start_load_kv_duration_msvLLM 调用 connectorstart_load_kv的耗时4️⃣ 健康与容量指标——存储活没活着、满没满指标类型含义ucm:posix_store_health/ucm:mooncake_store_healthGauge熔断器状态1 可用0 已熔断告警首选ucm:posix_healthy_count_total/ucm:posix_unhealthy_count_totalCounterPosix 健康探针成功/失败次数ucm:mooncake_healthy_count_total/ucm:mooncake_unhealthy_count_totalCounterMooncake 健康探针成功/失败次数ucm:posix_store_used_bytes/ucm:posix_store_capacity_bytesGaugePosix 逻辑存储已用/总容量ucm:posix_store_usage_ratioGaugePosix 容量使用率ucm:posix_gc_runningGauge垃圾回收状态1 运行中0 空闲ucm:yuanrong_dram_usage_ratio/ucm:yuanrong_ssd_usage_ratioGaugeYuanRong 共享内存/落盘 SSD 使用率完整语义、桶配置与聚合建议见 health_metrics.md 与指标配置文件 examples/metrics/metrics_configs.yaml。三步确认性能收益命中率、带宽、健康度 第一步算 UCM 外部缓存命中率不要孤立地算每个 Store 的命中率官方推荐的分层口径是先用相邻两层的边界命中率再按各层实际加载来源拆分详见 metrics_list.md 的 Raw Metrics Usage 章节。最常用的一条公式外部缓存命中率 外部命中 / 外部查询 × (1 − HBM命中 / HBM查询)对应到 vLLM 侧 Counter 就是(ucm:ucm_hit_tokens_total − ucm:gpu_hbm_hit_tokens_total) / ucm:total_prefix_query_tokens_total的增量比值。Cache Posix 流水线场景下再用cache_load_shards_total与cache_load_wait_shards_total的占比把命中率拆分到 Cache 层与 Posix 层。第二步算系统级缓存带宽sum(rate(ucm:cache_load_bytes_total[5m])) / 1e9 # 单位 GB/s先按 worker 求和、再换算单位加载与卸载读与写分开看不要用单任务带宽的均值去估算系统吞吐。第三步给存储健康配告警最简单的生产告警——任一 Store 熔断立即通知min by (job, instance, model_name, engine) (ucm:posix_store_health) 0建议搭配for: 30s持续条件避免瞬时抖动误报。探针失败率、健康 Store 占比等更多 PromQL 模板见 health_metrics.md 的Recommended Aggregation章节。常见问题ucm: 指标不出现怎么办按顺序排查 4 点FAQ 原文见 metrics.mdenable_metrics没有被显式设为false若配置了自定义metrics_config_path确认文件存在、可读且包含目标指标该文件一旦设置就只注册文件里列出的指标vLLM 已经处理过会走 UCM 路径的请求——没命中外存时只有很少一部分指标会出现这是正常现象curl /metrics能实际访问到服务端口。另外记住没有推理请求时指标数值不更新低流量场景请加大查询窗口如 5–15 分钟再评估探针失败率等比率型指标。延伸阅读官方指标总览文档docs/source/user-guide/metrics/metrics.md156 项指标完整参考docs/source/user-guide/metrics/metrics_list.md健康探针与告警推荐docs/source/user-guide/metrics/health_metrics.md指标配置示例Counter/Gauge/Histogram 与桶定义examples/metrics/metrics_configs.yaml命令行观测工具源码toolkit/ucm_toolkit/tools/metrics_view/如何为 UCM 新增一个指标docs/source/developer-guide/add_metrics.md掌握这份指标清单后你就能把UCM 帮我加速了多少从一句口号变成 Grafana 上可以持续追踪的数字——命中率、GB/s 带宽与健康状态三组数字讲清全部故事。【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址: https://gitcode.com/ModelEngine/unified-cache-management创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考