Claude API 提示词缓存为什么总 miss：静态前缀、工具定义与 usage 核对

同一个 Claude API 请求，第一轮调用耗时很高，第二次跑起来还是没看到缓存读取命中，很多团队第一反应都是先排查 cache_control 配置有没有生效。实际排查下来，绝大多数问题都出在请求拼装环节：工具定义、系统提示、检索片段和用户输入随便哪部分发生变动，断点之前的前缀内容就对不上了。缓存逻辑不是按“内容看起来相近”做模糊匹配，而是对断点之前的全部内容做完全精准的比对。

缓存命中先看前缀，不是先看开关

提示词缓存适合有固定规则、固定工具和长背景资料的调用场景。它复用的是从请求起始位置到缓存断点的一整段前缀内容；在 Claude 的请求结构里，工具配置、系统提示和消息内容都是按固定顺序拼接成这段内容的。第二次调用只要在断点前面多插了一个日期字段、一条新增的检索结果，或者工具说明的排列顺序有变动，整个前缀就会被判定为全新内容。

这里不用急着把所有资料全都往前缀里塞。缓存命中的核心目的是复用固定不变的内容部分，不等于要把随时会变的业务状态全部封死。比如客服 Agent 的服务规范可以长期不改动，订单号、账户状态和本轮用户提出的问题，就应该放在断点后面传入。

把工具定义与系统规则收在断点之前

最简单的写法可以直接用顶层的自动缓存控制功能。它会把所有可缓存的内容自动推到请求里最后一个支持缓存的位置；只要你的系统规则和工具定义是固定不变的，后续请求就很容易复用同一段前缀。生产环境的代码里还建议把工具数组做成版本化的配置，不要每次根据租户信息临时拼接出顺序不一样的结果。

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 800,
  "cache_control": {"type": "ephemeral"},
  "system": "你是订单助手。只依据给定订单资料回答。",
  "tools": [
    {"name": "get_order", "description": "读取订单摘要"}
  ],
  "messages": [
    {"role": "user", "content": "订单 A-1048 的退款进度"}
  ]
}

上面的示例只用来演示内容摆放的位置关系，不建议把真实订单相关的业务数据直接写进系统提示。如果业务需要附带一份很长的商品规则，你可以把这份规则和工具定义放在一起固定下来，用户的订单号和本次提问内容留在消息尾部传入。这么做既不会丢失业务的实时性，也不会因为一个动态字段把前面的缓存复用机会彻底破坏。

两次相同请求，先确认缓存是否真的被读取

验证效果的时候不用一上来就压测几百个请求。先在同一个运行环境里连续发两次内容完全一致的调用，把每次返回响应里的 usage 字段存下来。第一次调用通常会生成缓存，对应返回缓存创建 token；第二次调用如果前缀匹配成功，就会返回对应的缓存读取 token。只看接口返回耗时判断完全不准，网络抖动、请求排队都可能拖慢响应速度，干扰判断。

{
  "usage": {
    "input_tokens": 322,
    "cache_creation_input_tokens": 1840,
    "cache_read_input_tokens": 0,
    "output_tokens": 126
  }
}

代码里单独打点统计 cache_read_input_tokens 字段。如果这个值一直是0，可以按顺序缩小排查范围：先删掉动态生成的系统文本，再把工具数组固定下来，接着把历史消息精简到只剩一条。每次只改动一个变量，才能准确定位到底是哪部分内容破坏了原本的前缀匹配。缓存本身的生命周期也会影响命中结果，隔了很久再重新测试，就算命中也没法证明你的前缀设计是完全正确的。

三个容易忽略的 miss 来源

工具描述被拼进了租户信息

有些项目为了在工具说明里显示店铺名称、权限范围，每次都临时替换描述文本。它对模型也许更直观，却破坏了缓存前缀。更稳妥的做法是保持工具契约不变，把租户信息放到用户消息或单独的数据块。

把当前时间写入系统规则

“现在是几点”这类变量放在系统规则开头最容易造成连续 miss。若确实需要时间，用靠后的消息承载，或者只在业务需要时补充，不要让所有请求为此失去复用。

命中后仍然只统计总 token

总输入 token 不会直接告诉你哪一段被复用。仪表盘至少分开记录普通输入、缓存创建和缓存读取三类 token，并把模型、工具版本和缓存策略一起作为维度。这样某次发布后命中下降，才能及时回查是哪套配置变了。

相关问题

自动缓存和显式断点怎么选？

调用结构简单、对话逐步增长时，自动方式更省事；需要精确控制一段长资料的位置时，再使用显式断点。无论哪种方式，断点之前都要稳定。

用户问题相同就一定命中吗？

不一定。用户问题只是请求的一部分；前面的工具、系统规则、历史消息或图片变化，同样会使前缀不再相同。

为什么本地命中、线上却不命中？

先比较线上拼装后的完整请求：环境变量插入的日期、租户配置、工具版本和观测字段都值得检查。不要只比业务入参。

缓存读取为零要不要马上改提示词？

先做两次完全一致的最小请求确认环境与生命周期，再逐步恢复真实上下文。一次线上调用的零读取，信息量通常不够。

收尾：把前缀当成一份可发布的配置

提示词缓存的收益来自稳定的内容复用，不是多开一个配置开关就能拿到的。把系统规则和工具定义当成版本化的配置产物，动态业务数据往后放，再通过 usage 返回字段核对缓存读取情况，频繁 miss 的问题就能从摸不着头脑的成本问题，变成可以一步步定位的配置问题。