Claude提示词缓存盈亏平衡：第几次调用回本？

提示词缓存节省成本前的代价

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

这是一项现在支付附加费用、以后获得折扣的交易。您需要额外支付一次费用来存储前缀。之后每个以完全相同字节开头的请求，在该部分只需支付正常输入价格的十分之一。如果前缀在有效期内从未被重用，您就会无意义地多支付 25 percent。

用一行代数计算盈亏平衡点

将未使用缓存发送前缀时的基础输入成本记为 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 hour 缓存会将费用翻倍至 $200.00。解方程 1.25 减去 1.15h 等于 1 可知，5 minute 缓存的命中率达到约 22% 后才开始节省费用。因此，命中率达到 25% 时，费用已经是 $96.25。对 2x 写入量进行同样计算可知，1 hour 缓存的临界命中率约为 53%，因此命中率为 50% 时，费用仍为 $105.00，高于未缓存的费用。在命中率为 90% 时，两者的费用分别为 $21.50 和 $29.00。命中率为 99% 时，短期缓存的费用降至 $11.15，接近未缓存价格十分之一的下限。

应监控命中率，因为在前缀大小确定后，这是唯一可以控制的输入。

哪些前缀值得设置断点

一次请求最多可以包含 4 个缓存断点，因此关键是判断哪些块值得设置断点。候选块必须在多次调用之间保持字节级完全一致，并且足够大，能够产生实际影响。下图按 5 分钟缓存、90% 命中率，计算了 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% 的命中率计算，扩展到月度请求量。

[
  {
    "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。达到每月 1,000,000 次请求时，未缓存输入的费用为 $40,000.00，缓存可从中节省 $31,400.00。这些数字仅涉及输入 token。输出按单独价格计费，缓存不会降低输出费用。在承诺为任何人减少 90% 的账单之前，应牢记这一点。缓存只是控制 VPS 上 AI agent 账单的更广泛方法之一，详见 控制 VPS 上 AI agent 的账单。

如何证明缓存正在生效

不要只相信设计。读取响应中的用量信息块。每个 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 只统计最后一个断点之后的令牌，因此正常的第二次调用中该值应很小，通常只有新的用户消息。

在 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 小时的生命周期，断点会携带生存时间（TTL）：

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

还支持自动缓存：在请求顶层设置一个 cache_control 字段，之后由 API 随着对话增长自动管理断点。它会占用 4 个断点槽位中的 1 个。建议先使用此方式。只有在需要精确决定边界位置时，才改用显式断点。

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

缓存会从请求开头开始逐字节匹配前缀，请求按固定顺序组装：工具、系统提示词、消息。在任意层级发生更改时，该层级及其后续所有内容都会失效。编辑一个工具描述后，系统提示词和完整消息历史也会随之失效，即使您并未修改这些内容。

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

最常见的问题是时间戳。在系统提示词顶部加入一行 Current time: 2026-08-03T14:07:11Z，会使命中率固定为 0%，因为每次调用的前缀哈希都不同，之前的条目永远无法匹配。请将它移入用户消息，并放在末尾。会话标识符或每个请求使用的 nonce 也会产生同样的问题，修复方法相同。每个请求不同的检索文档也应放在缓存块之后，否则会使所有稳定内容都位于不断移动的边界之后。

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

第三个问题是您没有将某些参数变化视为提示词内容。不同模型使用不同的缓存。更改工具选择会使系统层级及其后的内容失效。添加或删除工具会使所有内容失效。

最小前缀长度，以及无提示的空操作

短于模型最小长度的前缀不会被缓存，而且系统不会告知您。不会返回错误，也不会显示警告。请求会成功，但两个计数器都显示为 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

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

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

为什么 cache_read_input_tokens 始终为0？

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

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

不会。缓存保存的是已发送 token 的处理结果，模型在两种情况下看到的提示词相同。这是计费和延迟功能，不会改变行为。因此，您可以在现有提示词上启用缓存，无需重新运行评估。

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

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