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

提示词缓存节省成本前的开销

提示词缓存可以重复使用提示词的前段，而不必在每次调用时重新读取。整个判断取决于模型基础输入价格的两个倍率。截至 October 2026，5 minute 有效期的缓存写入费用是基础输入价格的 1.25x，1 hour 有效期则是 2x，适用于所有模型。大多数模型的缓存读取费用是 0.1x，但读取倍率已不再完全相同。Claude Fable 5.1 和 Claude Mythos 5.1 的读取倍率是 0.025x；这两个模型于 September 1, 2026 以该费率发布。Claude Opus 5.5 和 Claude Sonnet 5.5 的读取倍率是 0.05x；其中 Sonnet 5.5 于 October 7, 2026 从 0.1x 下调至该费率。下面的计算示例使用标准的 0.1x 读取倍率。较低的读取费用会让盈亏平衡点略微向有利于您的方向移动，下一节将说明具体幅度。

这项机制的本质是现在支付附加费用，以换取之后的折扣。您需要先支付一次额外费用来存储前缀。之后每个请求只要以完全相同的字节开头，该部分就按正常输入价格的十分之一计费；对于上述模型，费用还会更低。如果前缀在有效期内从未被重复使用，您就会白白多支付 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。长时缓存需要 2 次读取才能达到盈亏平衡，这也是它不是默认选项的原因。

读取成本更低时，结果会变化，但幅度不大。读取成本为 0.05x 时，5 分钟缓存的计算为 0.95N = 1.2，因此 N = 1.26；读取成本为 0.025x 时，计算为 0.975N = 1.225，同样得到 N = 1.26。1 小时缓存对应的 N 分别降至 2.05 和 2.03。实际结论在所有模型上都相同：5 分钟缓存从第二个请求开始节省成本，1 小时缓存从第三个请求开始节省成本。

下图计算了 Claude Opus 5 上 20,000 token 前缀的成本。截至 October 2026，其基础输入费率为每百万 token $5，自 August 起未变。Opus 5 现已是旧版模型，但仍可用。其后继模型 Claude Opus 5.5 的价格为每百万 $4，读取成本为 0.05x，因此相同前缀的写入成本为 $0.10，读取成本为 $0.004。对于采用标准 0.1x 读取成本、每百万 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"
  }
]

单独发送 1 个请求时，不使用缓存的成本为 $0.10，使用缓存的成本为 $0.125，因此对只发送 1 次的提示词使用缓存只会增加成本。到第二个请求时，5 分钟缓存的成本为 $0.135，而不使用缓存的成本为 $0.20。此时 1 小时缓存仍处于劣势，成本为 $0.21，而不使用缓存的成本仍为 $0.20；它直到第三个请求才低于不使用缓存的成本：$0.22，而不使用缓存的成本为 $0.30。到 20 个请求时，两者之间的差距为 $2.00 和 $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 percent 时，费用为 $125.00，而不是 $100.00；1 hour 缓存会将费用提高一倍，达到 $200.00。解方程 1.25 minus 1.15h = 1 可知，5 minute 缓存的命中率达到约 22 percent 后才开始节省费用，这也是 25 percent 命中率已经显示为 $96.25 的原因。对 2x 写入使用相同的计算，1 hour 缓存的临界命中率约为 53 percent，因此 50 percent 命中率仍需 $105.00，高于不使用缓存的费用。在 90 percent 命中率下，两者的费用分别为 $21.50 和 $29.00。在 99 percent 命中率下，短期缓存的费用降至 $11.15，接近不使用缓存时价格十分之一的下限。

在读操作价格为 0.05x 的模型中，5 minute 缓存和 1 hour 缓存的临界命中率分别降至约 21 percent 和 51 percent。在读操作价格为 0.025x 的模型中，两者分别降至约 20 percent 和 51 percent。读操作价格越低，下限也越低，分别为不使用缓存时成本的二十分之一或四十分之一。

命中率是需要监控的指标，因为在前缀大小确定后，它是唯一由您控制的输入。

哪些前缀值得设置断点

一次请求最多可以携带 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。

节省金额只随前缀大小和命中率增加，不受其他因素影响。这也改变了哪些内容值得放入提示词：对于任何发送次数超过 1 次的内容，一百万个 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 个。先从这里开始。只有在需要精确决定边界位置时，再改用显式断点。

会导致缓存命中率归零的排序规则

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

这可以归纳为一条没有例外的规则：每次调用都会变化的内容，必须放在所有不会变化的内容之后。

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

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

第三个问题是您没有将某些参数变化视为提示内容。不同模型使用不同的缓存。更改 tool_choice 会使消息历史失效，但工具和系统提示仍会保持缓存。添加或删除工具会使所有内容失效。

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

短于模型最小长度的前缀不会被缓存，而且不会有任何提示。没有错误，也没有警告。请求会成功，两个计数器的值都为 0。截至 October 2026，已公布的最小值如下：

• Claude Opus 5、Claude Fable 5，以及较新的 Opus 5.5、Sonnet 5.5、Fable 5.1 和 Haiku 5.5：512 tokens
• Claude Sonnet 5 和 Claude Opus 4.8：1,024 tokens
• Claude Haiku 4.5：4,096 tokens

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

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

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

上下文开头附近发生变化时，缓存无法提供帮助。对话历史只能追加，因此普通的新一轮对话会扩展已经缓存的前缀。在会话早期读取的文件后来被编辑，并不会破坏这一点，因为 Claude Code 会追加一条文件已更改的说明，而不是重写之前的读取内容。切换模型则会破坏缓存，因为每个模型都有自己的缓存。连接一个工具会加载到前缀中的 MCP 服务器也会破坏缓存；压缩对话同样如此。这些操作都会导致下一轮重新写入前缀。长时间空闲也会产生同样的结果，因为缓存条目会过期，下一轮需要完整写入。这些都不是错误，而是前缀规则按预期运行的结果。

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

故障模式及其表现

每次调用都会产生写入。 每次请求中，cache_creation_input_tokens 都不为 0，而 cache_read_input_tokens 始终为 0。断点处或之前的某项内容在请求之间发生了变化。连续发送两次请求，并分别打印组装后前缀的前 200 个字符，然后人工比较。

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

读取先正常，随后停止。 先连续命中，随后发生一次写入，然后再次命中。请求之间的间隔超过了缓存生命周期。可以接受这次写入；也可以在确认命中率超过 53% 后切换到 1 hour TTL。对于读取成本为 0.05x 或 0.025x 的模型，所需命中率约为 51%。

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

启用缓存后账单增加。 命中率低于盈亏平衡点。在 5 minute 缓存下，命中率低于约 22% 时，不使用缓存直接发送前缀更便宜；在 1 hour 缓存下，低于约 53% 时也是如此。对于读取成本更低的模型，这两个临界值约为 20% 至 21% 和 51%。

FAQ

提示词需要重复使用多少次，缓存才能收回成本？

在 5 分钟缓存中，使用 1 次即可收回成本。大多数模型的写入成本是基础输入价格的 1.25 倍，读取成本是 0.1 倍。因此，N 次未缓存请求的成本为 N，而 N 次缓存请求的成本为 1.25 加上 0.1 乘以 N 减 1。两者在 N = 1.28 时相等，因此第 2 次请求就已经更划算。对于读取成本为 0.05 倍或 0.025 倍的模型，临界点为 N = 1.26，结论相同。1 小时缓存的写入成本为 2 倍，临界点为 N = 2.11；使用更低读取价格时约为 2.05，因此需要读取 2 次。

为什么 cache_read_input_tokens 始终为 0？

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

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

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

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

仅当您的流量间隔会超过 5 分钟，且命中率仍能达到约 53%，或者在读取价格更低的模型上达到约 51% 时，才值得使用。缓存未命中时，2 倍的写入成本是 1.25 倍写入成本的 4 倍。1 小时缓存写入未命中会浪费该前缀完整的基础输入价格，而 5 分钟缓存写入未命中只会浪费其中的四分之一。5 分钟缓存条目会在每次命中时刷新，因此稳定流量可以按读取价格保持缓存有效，无需为更长的生命周期付费。