# Cache Hit Rate

> 查看并计算缓存命中率。用户提到缓存命中率、cache hit rate、命中次数、未命中次数、缓存效率或想知道缓存表现时使用；适用于代码库、日志、监控导出和运行时指标，优先读取现有数据，不凭空创建或估算指标。

- Skill: `lqyeyao6666/cache-hit-rate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lqyeyao6666/cache-hit-rate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lqyeyao6666/cache-hit-rate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lqyeyao6666 (https://skillmd.com/u/lqyeyao6666)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lqyeyao6666/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')` 过滤时间）：

  ```bash
  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. **输出结果**
   - 结果先给结论，再给口径和数据来源。
   - 默认使用以下格式：

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

   - 有多个缓存、实例或时间段时，用简洁表格逐项列出，并给出整体值时说明聚合方式。整体命中率应使用总命中数和总未命中数加权计算，不要直接平均各分项百分比。
   - 数据不完整、时间范围不明或字段含义冲突时，明确标注不确定性，并说明需要补充什么；不要猜测。

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

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