Cache Hit Rate

查看缓存命中率

ZCode 内置数据源（优先查这里，跳过下面的探索步骤）

在 ZCode 客户端里查 LLM 模型（GPT 等）的缓存命中率时，直接查 ~/.zcode/cli/db/db.sqlite 的 model_usage 表，不要先翻日志：

• 口径：命中 = cache_read_input_tokens，总输入 = input_tokens。OpenAI 系的 inputTokens 已含缓存部分，所以命中率 = cache_read / input_tokens，未命中 = input - cache_read。

• 坑：cli/log/zcode-*.jsonl 日志里的 usageCacheReadTokens 等字段被脱敏成 [Redacted]，不可用；cache_creation_input_tokens 恒为 0（OpenAI 不报），别拿它当分母。

• 查法（可加 WHERE model_id LIKE 'gpt%'、date(started_at/1000,'unixepoch','localtime') 过滤时间）：

  sqlite3 ~/.zcode/cli/db/db.sqlite "
  SELECT model_id, COUNT(*) AS requests,
         SUM(input_tokens) AS input_tokens,
         SUM(cache_read_input_tokens) AS cache_read,
         ROUND(100.0*SUM(cache_read_input_tokens)/NULLIF(SUM(input_tokens),0),2) AS hit_rate_pct
  FROM model_usage
  WHERE status='completed' AND model_id LIKE 'gpt%'
  GROUP BY model_id;"
  

• 数据只写到最近一次落库（实测可能滞后数天），报告时用 datetime(MAX(started_at)/1000,'unixepoch','localtime') 给出覆盖范围，并提醒实时会话可能未计入。

当用户要查看缓存命中率时，按以下顺序执行：

1. 先找真实数据来源

   • 检查项目里的指标、日志、监控导出、缓存适配器和文档。
   • 搜索这些常见字段或表达式：cache_hits、cache_misses、hits、misses、hit_rate、hit ratio、cache_hit、cache_miss。
   • 优先使用现有命令、脚本、指标端点或查询，不要为了查看一次结果新建采集系统。
   • 如果用户指定了服务、时间范围、环境或缓存名称，只查询对应范围。

2. 确认指标定义

   • 命中率统一按 hits / (hits + misses) * 100% 计算，除非现有系统明确规定了不同定义。
   • 同时报告 hits、misses 和总请求数 hits + misses，让结果可复核。
   • 分母为零时报告“暂无请求，无法计算”，不要返回 0%。
   • 如果只有已经计算好的命中率，说明其来源和时间范围；不要把 miss rate、缓存占用率或命中延迟当成命中率。

3. 输出结果

   • 结果先给结论，再给口径和数据来源。

   • 默认使用以下格式：

     缓存命中率：92.50%
     命中：1850
     未命中：150
     总请求：2000
     时间范围：2026-08-24 10:00–11:00
     数据来源：<来源>
     计算：1850 / (1850 + 150)
     

   • 有多个缓存、实例或时间段时，用简洁表格逐项列出，并给出整体值时说明聚合方式。整体命中率应使用总命中数和总未命中数加权计算，不要直接平均各分项百分比。

   • 数据不完整、时间范围不明或字段含义冲突时，明确标注不确定性，并说明需要补充什么；不要猜测。

4. 必要时做最小验证

   • 对从代码或数据文件计算出的结果，做一次独立的算术校验。
   • 如果数据来自实时服务，记录查询时间；如果无法访问运行环境，只报告找到的配置、查询方式或静态数据，并明确尚未取得实时值。
   • 除非用户明确要求，不修改业务代码、不新增依赖、不部署监控。

常见触发示例：

• “帮我看一下 Redis 的缓存命中率”
• “这个服务 cache hit rate 是多少？”
• “根据这份日志算命中率”
• “统计最近一小时的缓存 hits 和 misses”