随着 Anthropic 更新平台，缓存机制、定价层级、TTL 时长和最小 token 阈值都会变化。不要依赖任何来自第三方指南的具体数字。当前数值请始终查阅官方提示缓存文档和模型与定价页面。
提示缓存经济学
每次你调用 Claude API，都要为你发送的每一个输入 token 付费——包括你的系统提示、你的工具定义，以及你注入的任何上下文。如果你在用同一个庞大前缀发起许多次调用，那你每一次都在为从头处理那个前缀付费。
提示缓存改变了这一点。你把提示中一个稳定的部分标记为可缓存。第一次调用处理它并把它存起来。后续命中缓存的调用会跳过那部分处理——并且为那些 token 只支付正常费率的一个零头。
这种节省并非装点门面。对于拥有庞大、稳定系统提示或重度上下文的应用，缓存能把一个功能的经济账从"贵到没法交付"变成"运行起来基本免费"。
思维模型：稳定前缀，易变后缀
把每次 API 调用想成两部分：
稳定前缀——在多次调用之间不变的内容。这是缓存适用的地方。示例：
- 你的系统提示
- 工具定义
- 一份你每次调用都注入的庞大参考文档或代码库
- 一大块长的少样本示例
易变后缀——每次调用都变化的内容。这是缓存不适用的地方。示例：
- 当前的用户消息
- 你每个请求注入的实时数据
- 随每一轮增长的对话历史
规则很简单：组织你的提示，让稳定内容排在最前，让变化的内容排在最后。 缓存断点是按位置划定的——被标记断点之前的一切都有资格被缓存；之后的一切都没有。
如果你把动态内容放在静态内容之前，你就破坏了缓存，因为前缀在每个请求上都变了。
成本模型如何运作
提示缓存为输入 token 的定价引入了一种三向拆分：
| token 类型 | 何时发生 | 相对于正常输入的成本 |
|---|---|---|
| 缓存写入 | 首次调用，或缓存过期之后 | 高于正常输入 |
| 缓存读取 | 后续命中缓存的调用 | 远低于正常输入 |
| 常规输入 | 最后一个缓存断点之后的 token | 正常费率 |
确切的倍数在官方定价页面上，且会波动——请直接核对。不变的是结构：写入比正常贵，读取便宜得多。盈亏平衡点——当你做了足够多的缓存调用、收回了写入开销之时——在任何含有可观稳定内容的提示上都来得很快。
延迟遵循同样的模式。缓存读取跳过了被缓存部分的完整处理，这在带有庞大前缀的调用上显著缩短了首 token 时间。
提示缓存何时有帮助
当两个条件同时成立时，缓存才划得来：
- 你有一个可观的稳定前缀（存在一个最小 token 阈值，低于它就无法使用缓存——确切数字按模型查阅当前文档）。
- 那个前缀被复用得足够频繁，能不只是偶尔地命中缓存。
缓存天然契合的场景：
- 文档问答——同一份庞大文档被为许多个用户问题注入。
- 编码助手——一个庞大的代码库或文件树被包含在每个请求中。
- 智能体循环——同样的系统提示和工具定义在一个多步工作流的每一步上被发送。
- 带长指令的对话式智能体——一份详尽的人设、规则集或知识库，在调用之间从不变化。
- 批处理——许多输入跑在同一个模板上。
提示缓存何时没有帮助
缓存在以下情况下没用：
- 你的提示很短（低于最小可缓存 token 阈值）。
- 你的前缀在每次调用上都变化——把时间戳、用户专属上下文或任何个性化内容注入到"稳定"部分，都会使缓存失效。
- 你发起的调用不频繁，且彼此间隔很久。被缓存的内容在一个 TTL 后过期（一个你可以在 API 支持的限度内配置的时长）。如果你的流量稀疏，你大多数时候会在支付写入成本，而读取寥寥无几。
- 你的前缀相对于每次调用的动态内容很小。节省随被缓存内容的大小而成比例增减。
把提示组织得对缓存友好
唯一的结构性要求是顺序：稳定内容必须排在易变内容之前。
在实践中：
[System prompt — instructions, persona, rules]
[Tool definitions — if static]
[Large injected documents or context — if the same across calls]
--------- cache breakpoint here ---------
[Dynamic per-call content — user message, retrieved chunks specific to this request]
你在想要纳入缓存的最后一个块上用一个 cache_control 字段来标记断点。那个标记之前的一切都有资格被缓存；之后的一切都是常规输入。
你可以在单个请求中放置至多四个显式断点。当你提示的不同部分以不同频率变化时，这很有用——例如，工具定义很少变，对话历史每一轮都变。每个部分可以有它自己的断点。
缓存失效规则
缓存对顺序敏感。对一个被缓存的块、或对提示中排在它之前的任何块的任何改动，都会使该断点及其之后所有断点处的缓存失效。
对工具定义的改动使所有缓存失效。对系统提示的改动使系统缓存和消息缓存失效。对话中途的改动只影响消息缓存。
实际含义是：如果你正在注入任何每个请求都变化的东西，务必绝对确保它位于最后一个缓存断点之后，而不是在它之前或之内。
预热与监控
你可以在用户流量到来之前预热缓存，方法是发送一个带 max_tokens: 0 的请求——这会写入缓存而不生成输出。对批处理作业、或在非高峰时段前置承担写入成本，都很有用。
API 响应的 usage 字段会告诉你有多少 token 是从缓存读取的（cache_read_input_tokens）、写入缓存的（cache_creation_input_tokens）、以及按常规输入计费的。监控这些数据，以验证你的缓存确实在命中，并测量你实现的节省。
在投入一套缓存架构之前，使用成本计算器来对预期节省建模。
结论
提示缓存不是一个微优化。对于任何反复发送同一个庞大前缀的应用，它是一个结构性的经济决策。思考它的模型很直接：稳定内容排在前面，易变内容排在最后，把断点放在边界上。
如果你正基于 API 构建，却还没看过缓存，那就检查一下你当前的提示有没有庞大的稳定部分。如果有，启用缓存通常代价很低，而节省是实实在在的。