提示词缓存为什么没命中？用 usage 字段核对读写 token

先分清你想复用的是什么

提示词缓存与“将问答结果存进 Redis”解决的是不同问题。前者仍需生成新输出；后者由应用决定是否跳过模型调用。先观察应用是否真的发出请求：若被本地结果缓存拦截，就不应把这次速度当作供应商提示词缓存表现。记录缓存层名称，避免把两种命中率混在同一张图表中。

检查前缀稳定性与模型适用条件

官方缓存指南强调可复用前缀与相关请求设置的一致性，最小长度、有效期及写入方式依模型而异。把相同的说明与工具定义放在稳定位置，将每次变化的任务信息放在后面，是值得验证的布局；不要在开头插入每次变化的时间戳。调换工具或输出 schema 后，也应重新检查，而非只比较肉眼可见的用户问题。

官方依据：来源 1

看计数，不把未知当零

在文档对应的 Responses 模型中，input_tokens_details.cached_tokens 表示读取计数；支持的模型还可返回 cache_write_tokens 与不同有效期的写入细分。先确认字段语义、是否包含在 input_tokens 中，再拆分账目。某个兼容服务不返回这些字段时，正确结论是“当前无法从响应核实”，不是“缓存不存在”。

官方依据：来源 1

运行一个互斥账目检查

以下数字全部是合成教学数据，不是商家价格或真实请求。保存为 cache-usage.mjs 并运行。只有确认计数互斥且都包含在 total 中，才可用减法算 ordinary；字段缺失会报错，防止静默补零。

function splitInput(total, cached, written) {
  if (![total,cached,written].every(Number.isSafeInteger) ||
      Math.min(total,cached,written)<0 || cached+written>total)
    throw new Error('用量缺失、无效或不满足互斥口径');
  return {ordinary:total-cached-written, cached, written};
}
const usage = splitInput(10000, 6000, 2000);
console.assert(usage.ordinary === 2000);
const hitRate = usage.cached / 10000;
console.assert(hitRate === 0.6);
console.log(usage, '缓存读取占比', hitRate);
// 这里只核对数量。单价、币种、缓存有效期必须另查真实账单。

没有命中时，按变量做小范围对照

先固定模型与客户端配置，再对照前缀是否真正相同；如果只是短提示词，先核对该模型的最低条件。每轮只改变一项，例如是否在前缀插入时间、工具定义顺序或间隔时长。记录请求 ID、输入量、读取量、写入量与异常原因，控制次数和预算。本站没有执行这一付费验证，也不保证改布局就一定命中。

把计数带回费用估算，保留恢复办法

同一有效期、同一写入单价的场景，可把互斥计数填入本站费用估算器。若写入分成多个有效期，不要把它们合并后套同一个单价；分项计算或使用真实账单。写入成本也要计入比较，不能只看读取占比。若优化后总费用或任务正确性变差，恢复原提示词布局并保留对照记录；应用结果缓存还需独立处理过期与数据隔离。