Claude 提示词缓存——费率、usage 对象，以及为什么通过网关时命中率会下降

提示词缓存是代理账单上最大的单项杠杆，也是最可能悄无声息地失效的部分。正确标记后，请求中重复部分按输入费率的十分之一计费。标记错误，或通过会重写前缀的组件路由时，费用会高于普通费率，因为你在为从未被读取的缓存条目支付写入费用。

该机制在其他地方已有充分文档说明。没有任何地方记录的是：请求经过网关时会发生什么变化，而这正是大多数读者所处的情况。下面分别介绍两者。

机制简介

你标记一个稳定前缀——系统提示词、工具架构或文档——由提供商存储其处理结果。下一次前缀完全匹配的请求会读取该结果，而不是重新处理。

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

两个属性决定了一切，也造成了所有问题。匹配针对的是前缀，因此开头的任何变化都会使其后的全部内容失效。条目还具有生命周期，因此轮次之间间隔很长的对话会重新构建，而不是读取缓存。

费用

第三列是标准比例：读取费用为输入费用的十分之一。第四列也是标准值——缓存写入费用为输入费用的 1.25×，这是 Anthropic 为五分钟条目列出的倍数——由于两种比例都应用于 Kunavo 的输入价格，因此相对于 Anthropic 列表价，它们都享有与模型输入相同的折扣。Kunavo 与 Anthropic 的不同之处在于一小时条目：Anthropic 将该写入列为输入的 2×，而 Kunavo 按同样的 1.25× 计费。这对于经常重建的工作负载尤其重要——长期运行的代理、响应缓慢的对话，以及前缀频繁变化的任何场景——因为在这些工作负载中，主导账单缓存项的是写入而不是读取。

两个数字都会在渲染时从目录读取，来源与价格表和 Claude 计算器读取的来源相同——本页面没有手动输入的费率。

读取使用量对象

不要从账单推断缓存行为；每个响应都会直接告诉你，三个 token 计数足以完成全部诊断。

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

为什么通过网关后命中率会下降

缓存存在于创建它的上游，前缀匹配是精确的。这两个事实共同导致三种直接调用单个提供商时不会出现的故障模式：

路由发生了变化。如果连续请求落到不同的上游，第二个请求就找不到缓存——第一个请求写入的条目从第二个请求运行的位置不可见。这在你自己的日志中不可见，只会表现为本应是读取却出现了缓存创建计数。这是最常见的原因，也是为什么一个在上游之间自由重新路由的网关可能每 token 更便宜、每个会话却更贵。

有内容被注入到你的前缀之前。重写系统消息、规范化工具定义或重新排序字段的层会产生不同的前缀，而不同前缀就是未命中。不会报错；账单只会增加。

间隔超过了条目生命周期。如果代理在轮次之间思考几分钟，它可能每次都重新构建。这是工作负载本身的属性，而不是网关的属性，但会与第一种情况产生不良交互：重新构建也提供了一次重新路由的机会。

三种情况的诊断方法相同——在整个会话中观察 cache_creation_input_tokens。数值始终较大且平坦，意味着你在不断重建。第一次较大、之后为零，意味着缓存正在工作。在 Kunavo 中，请求级费用和缓存 token 计数位于使用量视图，而缓存参考提供端点级详情。

如何处理

保持缓存前缀真正稳定——将每个请求中会变化的内容放在标记区块的后面，绝不要放在前面。在可行的情况下，让代理的轮次更紧密地批量执行，因为空闲时间是短生命周期条目的敌人。并且要端到端测量整个会话，而不是单个请求：缓存是序列的属性，单请求估算无法看到这一点。Claude token 费用计算器提供缓存 token 字段正是出于这个原因——将其设置为提示词中真正重复的比例，月度数字就不再是虚构的。

常见问题