Claude Prompt缓存机制深度解析：从定价逻辑到生产避坑指南

在Claude Opus 5上做一次缓存写入，每百万tokens要花6.25美元，而同样的缓存读取只需0.50美元——读写之间差了12.5倍，这个数字就明晃晃写在Anthropic自己的定价页上。然而当你真正去查那些备考指南或者技术博客时，会发现这块内容的缺失远比想象中严重。大多数资料要么只讲概念不讲定价，要么讲定价但跳过了那些会让缓存“静默失效”的边界条件。Prompt缓存看起来是把cost写死在API里的确定项，但实际运行时它更像一个需要主动管理的状态机——任何你以为在省的money，都可能因为一个没有报错的小细节悄悄蒸发。本文就来系统梳理Prompt缓存的运作机制，帮你避开那些在生产环境里才会暴露的高频陷阱。

缓存的本质：前缀匹配而非区间复用

Prompt缓存作用的对象是前缀（prefix），不是请求里随便哪段连续的文本。当你调用缓存时，系统会把你请求中从开头到指定breakpoint为止的全部内容拿来做哈希匹配，这个顺序是严格固定的：先是tools定义，然后是system prompt，最后是messages历史。如果两个请求之间你的tool定义发生了变化，那么排在它后面的system prompt和message历史也都无法复用缓存，因为前缀的哈希值已经对不上了。Anthropic自己在文档里给出的失效表把这个逻辑写得很清楚：tool定义的改动会让tools、system、messages三个区块全部失效，而像切换web search这类更小范围的改动，则只会让tools块失效。标记cache breakpoint有两种主流方式：顶层cache_control字段用于自动缓存，或者在各个内容块上显式声明cache_control以实现更细粒度的控制。大多数团队的做法是先在多轮对话上开自动缓存，等到prompt里出现变化频率明显不同的区块——比如静态的system prompt和不断累积的tool结果历史——再切换到显式breakpoint模式。

读写定价：12.5倍价差背后的成本逻辑

这是最容易让开发者产生幻觉的地方。5分钟的cache write成本是基础输入价的1.25倍，1小时的cache write是2倍，而cache read不管当初用哪个TTL写入，在当前大多数模型上都只有基础输入价的0.1倍。在Claude Sonnet 5上，2美元的基础输入价会变成2.50美元的write和0.20美元的read；在Haiku 4.5上，1美元的基础输入对应1.25美元的write和0.10美元的read。这笔账只有在复用次数足够多的情况下才算得过来——一次写完却从来没被读过的缓存，比压根不缓存还贵，因为白白支付了1.25倍或2倍的溢价。盈亏平衡点取决于你在TTL窗口内会重读这个前缀多少次，这也是1小时选项存在的原因：对于agentic任务或者节奏很慢的对话，5分钟窗口很可能在两次读取之间就已经过期，这时候write付双倍仍然比每次重读都吃满输入价划算。

静默失效：那些没有报错的缓存杀手

缓存失效会沿着tools→system→messages这个层级向下级联，而breakpoint的位置选择远比想象中严格：必须放在前缀在所有请求间逐字节相同的那最后一个块上，绝不能放在会变化的块之前。一个时间戳、一个每请求都不同的user ID，或者任何一小段动态内容，只要你把它放在breakpoint前面，哈希就永远匹配不上之前的写入，于是你又回到每个请求都付全价的境地，同时还以为自己开着缓存。这和context drift以及lost-in-the-middle问题属于同一个家族——静默失败，只不过发生在成本层而不是准确率层。另外还有一个在生产上撞到之前很少有人知道的约束：同一个请求里，1小时的缓存块必须出现在任何5分钟缓存块之前，不能放在后面。混合请求的计费按三个位置来算：缓存读取算到已有命中的最高点，从那一点到1小时breakpoint之间的新内容按1小时写入计费，更新的部分按5分钟写入计费。对于“很少变化的超长system prompt加每轮都在变的tool结果历史”这种组合，它确实是个很好用的模式，但第一次上手很容易把顺序搞反。

从文档到生产：缓存使用的最佳实践

综合以上分析，在实际项目中正确使用Prompt缓存需要建立几个关键认知。首先，永远要把缓存和预算这两件事放在构建阶段对着实时文档去核实，而不是当作一次性背下来的静态知识——Anthropic的定价页更新节奏很快，具体乘数会随模型版本变化。其次，对于任何需要在API里拿结构化保证的场景，应该使用schema强约束的structured outputs，而不是指望一段prompt每次都表现得一模一样。再次，在设计长对话或多轮交互时，提前规划breakpoint的分布，避免落入lookback window的陷阱。最后，对于短于token下限的prompt片段，与其强行使用缓存，不如优化prompt本身的压缩效率，或者接受按全价计费这个更简单的选择。缓存是个好工具，但它只有在被正确理解和管理的时候才能真正发挥作用。

Prompt缓存的读写成本差异达到12.5倍，但这个数字本身并不重要，重要的是它背后那套需要主动管理的状态逻辑。Token下限、lookback window、顺序敏感性、TTL混用规则——这些细节每一个都可能让你的缓存“静默失效”而不自知。在生产环境中，与其相信缓存会按照预期工作，不如建立完整的监控机制来验证cache_creation_input_tokens和cache_read_input_tokens的实际值。毕竟，在AI应用的成本控制这场持久战里，最危险的从来不是花出去的钱，而是你以为省下来却其实没有省的那部分。