Claude提示缓存何时回本？盈亏平衡计算

缓存节省成本前需要付出的代价

提示缓存可让 Claude 重用提示词的开头部分，而不必在每次调用时重新读取。整个决策取决于模型基础输入价格的两个倍数。截至 2026 年 8 月，5 分钟有效期的缓存写入费用是基础输入价格的 1.25 倍，1 小时有效期则是 2 倍。缓存读取费用是基础输入价格的 0.1 倍。这些倍数适用于模型列表中的所有模型，因此每个 token 的价格变化不会改变下面的盈亏平衡点。

这种机制的取舍是现在支付附加费用，以换取之后的折扣。您需要先支付一次额外费用来存储前缀。之后每个以完全相同字节开头的请求，在该部分只需支付正常输入价格的十分之一。如果某个前缀在有效期内从未被重用，您就会无谓地多支付 25% 的费用。

盈亏平衡：用一行代数表示

将未使用缓存时发送前缀所需的基础输入成本记为 B。不使用缓存时，N 次请求的成本为 N 乘以 B。使用 5 分钟缓存时，第一个请求以 1.25B 写入前缀，其余 N 减 1 个请求以 0.1B 读取前缀。令两者相等，可得 0.9N = 1.15，因此 N = 1.28。第二个请求的成本已经低于完全不使用缓存的情况。

对 1 小时缓存使用 2 倍写入成本进行同样计算，可得 0.9N = 1.9，因此 N = 2.11。长时缓存需要两次读取后才能达到盈亏平衡，因此不是默认选择。

下图以 Claude Opus 5 的 20,000 token 前缀为例计算成本。截至 2026 年 8 月，该模型的基础输入价格为每百万 token $5。对于每百万 token $3 的模型，将所有数值乘以 0.6。曲线形状不会改变。

[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

单独发送一次请求时，不使用缓存的成本为 $0.10，使用缓存的成本为 $0.125，因此为一次性提示启用缓存只会增加成本。到第二个请求时，5 分钟缓存的成本为 $0.135，而不使用缓存的成本为 $0.20。此时 1 小时缓存仍处于不利状态，成本为 $0.21，而不使用缓存仍为 $0.20；直到第三个请求，它才低于不使用缓存的成本：$0.22，而不使用缓存的成本为 $0.30。当请求数达到 20 时，两者的差额为：不使用缓存 $2.00，使用 5 分钟缓存 $0.315。

命中缓存还会刷新缓存条目，因此发布的价格表将该列称为缓存命中和刷新。高流量端点可以按读取价格使 5 分钟缓存条目无限期保持有效；只有当流量之间确实存在间隔时，1 小时缓存的生命周期才值得其 2 倍写入成本。

糟糕的命中率会带来什么代价

真实流量会出现未命中。请求未命中缓存但仍携带断点时，会按写入计费。因此，准确的建模方式是将成本表示为命中率的函数。下图以 1,000 个请求为例，每个请求都携带相同的 20,000 token 前缀。

[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

命中率为 0% 时，费用为 $125.00，而不是 $100.00；1 小时缓存会将费用翻倍至 $200.00。求解 1.25 减去 1.15h 等于 1，可知 5 分钟缓存的命中率达到约 22% 后才开始节省费用。因此，命中率达到 25% 时，费用已经是 $96.25。对 2 倍写入成本进行同样计算，可得 1 小时缓存的临界命中率约为 53%。因此，命中率为 50% 时，费用仍为 $105.00，高于不使用缓存的费用线。命中率达到 90% 时，两者分别为 $21.50 和 $29.00。命中率达到 99% 时，短时缓存的费用降至 $11.15，接近不使用缓存时价格十分之一的下限。

应监控命中率，因为前缀大小固定后，命中率是唯一由您控制的输入。

哪些前缀值得设置断点

一次请求最多可以包含 4 个缓存断点，因此关键问题是哪些区块值得设置断点。候选区块必须在多次调用之间逐字节相同，并且足够大，能够产生实际影响。下图按 5 分钟缓存、90 percent 命中率，计算了 1,000 次请求中 4 种常见结构的成本。

[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

仅包含 2,000 个 token 的基础系统提示词，相比不使用缓存的 $10.00，每 1,000 次请求可节省 $7.85。在大规模调用时，这笔金额确实可观，但这不是缓存真正有价值的原因。加入工具定义后，前缀长度达到 8,000 个 token，可节省 $31.40。每次请求都会针对其提问的 25,000 个 token 的策略文档，可节省 $98.12。最后一行会改变架构：120,000 个 token 的代码库或对话记录上下文，在不使用缓存时成本为 $600.00，使用缓存后为 $129.00，可节省 $471.00。

节省额只随前缀长度和命中率增加，不受其他因素影响。这也改变了哪些内容值得放入提示词：一百万个 Claude token 的实际成本 对于发送超过一次的内容，成本会降至标价的十分之一。

月度账单中的实际效果

下方图表使用上文的 8,000 token 前缀，以及系统提示词和工具定义，并按 90 percent 的命中率计算月度请求量。

[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

每月发送 10,000 个请求时，可节省 $314.00，即 $400.00 与 $86.00 之间的差额。每月发送 100,000 个请求时，可节省 $3,140.00。每月发送一百万个请求时，未缓存输入的费用为 $40,000.00，缓存可从中节省 $31,400.00。这些费用只计算输入 token。输出按单独价格计费，缓存不会降低输出费用。在承诺将账单降低 90 percent 之前，应牢记这一点。缓存只是控制 VPS 上 AI 代理账单这一更广泛做法的一部分，参见 控制 VPS 上 AI 代理的账单。

如何证明缓存正在生效

不要只相信设计。读取响应中的 usage 块。每个 Messages API（应用程序编程接口）响应都会报告写入的缓存令牌数、读取的缓存令牌数，以及必须处理的新令牌数。

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

使用同一份文档和不同的问题运行两次。第一次调用会报告非零的 cache_creation_input_tokens 和为 0 的 cache_read_input_tokens。第二次调用则相反，因为系统找到了此前的前缀。input_tokens 只统计最后一个断点之后的令牌，因此正常情况下第二次调用的值很小，通常只有新的用户消息。两次调用都会计费，因为 Claude API 没有免费层级，不过对于上文所述的 20,000 个令牌前缀，这两次调用合计约为 14 美分。

也可以在 shell 中，对已保存到 request.json 的请求正文执行相同检查：

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

正常情况下，第二次调用会输出类似以下内容：

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

其中一行会显示实际情况。如果多次调用中 cache_read_input_tokens 始终为 0，您每次都在支付 1.25x 的写入费用，却没有获得任何缓存结果。

对于 1 hour 的生命周期，断点会携带生存时间（TTL）：

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

系统还支持自动缓存：在请求顶层添加一个 cache_control 字段，之后 API 会随着对话增长自动管理断点。这会占用 4 个断点槽位中的 1 个。先从这里开始。只有在需要精确决定边界位置时，再改用显式断点。

导致命中率下降的排序规则

缓存从请求开头逐字节匹配前缀，请求按固定顺序组装：tools，然后是 system，最后是 messages。任意层级发生变化，都会使该层级及其后面的所有内容失效。编辑一个工具描述后，system prompt 和完整消息历史也会随之失效，即使您没有修改它们。

因此只有一条规则，没有例外：每次调用都会变化的内容，必须放在所有不变内容之后。

最常见的问题是时间戳。在 system prompt 顶部加入一行 Current time: 2026-08-03T14:07:11Z，会使命中率固定为 0%，因为每次调用的前缀哈希都不同，之前的条目永远无法匹配。应将它移到 user message 的末尾。会话标识符或每个请求使用的 nonce 也会以相同方式破坏缓存，修复方法相同。每个请求获取的不同文档也应放在缓存块之后，否则会将所有稳定 token 推到一个不断移动的边界之后。

第二个问题是将断点放在会变化的块上。缓存会在断点处写入，因此如果该块每次都不同，就不会存储任何稳定内容；回溯查找时，只能找到之前的请求在各自移动断点处写入的条目。应将 cache_control 放在跨请求内容完全相同的最后一个块上。

第三个问题是修改了一个您未视为 prompt 内容的参数。不同的 model 使用不同的缓存。更改 tool choice 会使 system 层级及其后面的内容失效。添加或移除工具会使所有内容失效。

最小前缀长度与静默无操作

短于模型最小长度的前缀不会被缓存，而且不会收到任何提示。不会报错，也不会发出警告。请求会成功，但两个计数器都显示为 0。截至 2026 年 8 月，已公布的最小长度如下：

• Claude Opus 5 和 Claude Fable 5：512 个 token
• Claude Sonnet 5 和 Claude Opus 4.8：1,024 个 token
• Claude Haiku 4.5：4,096 个 token

如果您认为某个请求应当命中缓存，但两个计数器都显示为 0，请先检查前缀长度。这也是最便宜的模型不一定最适合缓存工作负载的原因。Haiku 4.5 需要的前缀长度是 Opus 5 的 8 倍，缓存才会生效。因此，长度为 2,000 个 token 的系统提示词可以在其中一个模型上缓存，但在另一个模型上会被静默忽略。

Claude Code 会为您缓存哪些内容，以及哪些内容无法缓存

Claude Code 会缓存自己的前缀。系统提示和工具定义位于每个请求的开头，内容不会移动，因此只需写入一次，之后在本次会话中重复读取即可。这就是为什么长会话的每轮成本远低于上下文大小所显示的成本；相关数据会显示在Claude Code 报告令牌使用量的方式所述的计数器中。

如果编辑的是上下文开头附近的内容，缓存就无法提供帮助。对话历史只能追加，因此普通的新回合会扩展已缓存的前缀。在会话早期读取的文件发生变化时，前缀中间的内容也会变化，变化位置之后的每个令牌都必须重新写入。长时间空闲也会产生相同结果，因为缓存条目会过期，下一回合必须完整写入。这两种情况都不是错误，而是前缀规则按设计运行的结果。

如果您改为编写自己的客户端，应从第一个请求开始采用正确的布局，而不是事后调整。请按照在 VPS 上构建第一个 Claude API 应用的方式构建请求，先放置稳定区块，最后放置易变区块。

故障模式及其表现

每次调用都是一次写入。 每个请求中，cache_creation_input_tokens 都是非零值，而 cache_read_input_tokens 保持为 0。断点处或断点之前的内容在不同调用之间发生了变化。连续发送两次请求，分别输出组装后前缀的前 200 个字符，然后直接比较。

两个计数器都是 0。 前缀未达到模型要求的最小长度，或者 cache_control 字段从未发送到 API。先统计前缀的 token 数量，再记录实际发送的请求正文。

读取先正常，然后停止。 先连续命中，随后发生一次写入，然后又恢复命中。两次请求之间的间隔超过了缓存的生命周期。可以接受这次写入；确认命中率超过 53 percent 后，也可以改用 1 hour TTL。

部署后命中率下降。 工具描述被编辑，或模型发生了更改。这两种情况都会使整个前缀失效。每次部署修改提示词后，都应预期出现一轮高成本的写入。

启用缓存后账单增加。 命中率低于盈亏平衡点。在 5 minute cache 下，命中率低于约 22 percent 时，不使用缓存发送前缀的成本更低；在 1 hour cache 下，低于约 53 percent 时也是如此。

FAQ

提示词需要重复使用多少次，缓存才值得？

在 5 分钟缓存中，使用 1 次就值得。写入成本是基础输入成本的 1.25x，读取成本是 0.1x。因此，N 次未缓存请求的成本为 N，而 N 次缓存请求的成本为 1.25 加上 0.1 乘以 N 减 1。两者在 N = 1.28 时相等，因此第 2 次请求就已经节省成本。1 小时缓存的写入成本为 2x，在 N = 2.11 时达到成本平衡，因此需要读取 2 次。

为什么 cache_read_input_tokens 始终为 0？

先检查前缀长度：低于模型最低要求时，缓存会静默跳过，两个计数器都会显示 0。截至 2026 年 8 月，Claude Opus 5 的最低长度为 512 个 token，Claude Haiku 4.5 的最低长度为 4,096 个 token。如果前缀足够长，请检查断点处或断点之前是否存在每次调用都会变化的内容，例如 system prompt 中的时间戳或会话标识符。如果计数器之前正常、后来停止工作，说明两次请求之间的间隔超过了缓存生命周期。

提示词缓存会改变 Claude 的回答吗？

不会。缓存保存的是已发送 token 的处理结果，模型看到的提示词仍然相同。缓存只影响计费和延迟，不会改变行为。这也意味着，您可以在现有提示词正常工作的情况下启用缓存，无需重新运行评估。

是否应该为 1 小时缓存付费？

只有当您的流量间隔超过 5 分钟，并且命中率仍能达到大约 53% 时才应该使用。未命中时，2x 的写入成本是 1.25x 写入成本的 2 倍。5 分钟缓存条目会在每次命中时刷新，因此稳定流量只需按读取价格付费即可保持缓存有效，无需为更长的生命周期付费。