在调用Claude API处理长文档、复杂Agent任务或携带大量工具定义时，提示词token的占比往往远超预期。以一份50000 token的系统提示为例，假设每分钟有20次请求，那么仅仅系统提示本身每小时就要消耗6000万token的输入额度。Prompt Caching的出现等于给这类场景装了一条专用通道：稳定的提示前缀只计费一次，后续请求直接以缓存价读取。
要理解Prompt Caching的价值，得先弄清楚Claude API的请求结构。每次调用Claude时，输入消息由system、messages和tools等字段组成。对于Agent类应用，系统提示、工具描述、少样本示例通常每轮都保持不变，只有用户消息在变化。在未启用缓存之前，这些固定内容每一轮都会完整参与token计费，而且模型在推理时还得重新处理一遍，延迟自然居高不下。
Anthropic的解决方案是引入缓存写入与命中的概念。开发者可以通过cache_control参数标记提示词中的某一段内容为可缓存区域。首次请求时，Claude服务端会把标记区域写入缓存，并返回一个缓存标识；后续请求若携带相同的缓存内容前缀，服务端直接命中缓存，这部分token按缓存读取价计费，价格仅为标准输入价的十分之一。根据Anthropic公开的定价，以Claude Sonnet为例，标准输入为每百万token 3美元，缓存写入为每百万token 3.75美元，缓存读取仅为每百万token 0.30美元。可以看到，写入价格略高于标准输入，但只要缓存内容被复用两次以上，整体成本就开始显著摊薄。
缓存标记的添加方式与代码接入
开启Prompt Caching并不需要修改模型本身，只需要在请求体中加入cache_control字段。这个字段可以出现在system内容块、messages中的内容块以及tools定义里。它的作用是告诉服务端：到此为止的内容需要写入缓存。一个典型的Python调用示例如下：
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=2048,
system=[
{
"type": "text",
"text": "你是一名资深数据库工程师，擅长SQL优化、索引设计和执行计划分析。",
},
{
"type": "text",
"text": "以下是产品数据库的表结构文档：\n\nCREATE TABLE orders (...) ...",
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "帮我分析一下这个慢查询的优化方案。"}
]
)
在这段代码里，system数组包含两个文本块。第一个块是角色设定，第二个块是冗长的表结构文档，并且在第二个块的末尾添加了cache_control标记。这个标记的含义是：将system中从开头到该标记结束的所有内容作为一个整体缓存。第二次发起请求时，只要system的内容和结构与第一次完全一致，缓存就会命中。
需要特别注意的是，缓存粒度不是任意的。Claude服务端对可缓存内容有最小长度要求：对于Claude Sonnet和Claude Haiku，缓存前缀最短为2048 token；对于Claude Opus，最短为1024 token。低于这个阈值的缓存标记不会生效，系统会直接忽略。另外，cache_control标记的位置决定了缓存边界，放置在内容块末尾表示该块结束的位置即为缓存截止点。如果希望将messages中的多轮对话历史也纳入缓存，可以在最后一轮对话的内容末尾添加标记。
缓存命中判定与失效机制
Prompt Caching遵循前缀匹配原则。服务端会比较当前请求的提示词前缀与已缓存内容是否逐字节一致，只有完全匹配的部分才能被复用。举个例子，如果第一次请求的system是「ABC」，第二次请求的system是「ABCD」，那么前三个字符「ABC」仍然可以命中缓存，新增的「D」会按标准输入价计费。但如果第二次请求的system变成了「ABD」，缓存直接失效，因为第三个字符发生了变化，前缀不再匹配。
这个机制对开发者提出了一个明确的要求：把稳定不变的内容放在前面，把频繁变化的内容放在后面。比如在构建Agent时，工具定义、系统约束、知识库文档应该排在消息序列的前部，而用户输入和动态上下文放在后部。这样做可以最大化缓存命中率，避免因为某个动态字段插入在稳定内容之前而破坏前缀匹配。
缓存的生命周期也是需要关注的点。Anthropic规定，缓存写入后默认保留5分钟，在这段时间内没有新的命中请求，缓存就会被清除。对于高频请求场景，5分钟并不短；但对于间歇性调用，比如每隔10分钟才触发一次的任务，缓存可能永远无法命中。此外，缓存是弹性的（ephemeral），不与特定的API密钥或账号强绑定，同一账号下的不同请求只要前缀一致就能共享缓存。这意味着在水平扩展的系统中，多个实例发送相同前缀的请求，同样能享受到缓存收益。
计费层面，首次写入缓存的内容按照缓存写入价计费，这比标准输入价高出25%。如果缓存从未被命中，写缓存的操作相当于多花了钱。因此对于低频调用，盲目添加cache_control反而会推高成本。一个实用的判断标准是：只有当同一段前缀在5分钟内至少被复用两次，缓存才具备经济性。如果请求频率很低，或者提示词本身很短（低于最小缓存长度），关闭缓存标记是更明智的选择。
典型应用场景与优化策略
Prompt Caching最适合的领域是长上下文的重复调用。Agent框架是一个典型例子。一个复杂的Agent通常携带数千token的工具说明、数百行系统约束以及多步推理的少样本示例，这些内容在每轮对话中保持不变。通过把这部分前缀缓存，每轮用户交互只需要为新增的对话内容付费，缓存读取价仅为标准输入价的10%。对于同时服务大量用户的Agent产品，成本下降幅度相当可观。
第二个高频场景是文档问答与知识库检索。假设有一个面向企业的合同审查工具，每次用户提问时都需要把整份合同（可能超过10万token）塞入上下文。借助缓存，合同文本在首次写入后，后续针对同一份合同的反复追问都按缓存读取价计费，用户提问和模型回答的延迟也会因为省去了重复的提示词预处理而显著降低。
第三个场景是少样本学习的重复评估。在开发阶段，团队往往需要用同一组示例反复测试不同模型参数或提示词变体。如果少样本示例部分保持一致，将其标记为缓存前缀，就能在迭代测试中持续节省token成本。需要注意的是，当提示词中某一部分发生变化时，缓存从变化点开始失效，变化点之后的内容需要重新计算。因此调试时需要把不确定的部分尽量放在提示词后段。
为了衡量缓存的实际效果，可以在API响应的usage字段中查看cache_creation_input_tokens和cache_read_input_tokens。前者表示本次请求写入缓存的token数，后者表示本次请求命中的缓存token数。通过对比这两个指标与input_tokens的关系，就能清晰地看到缓存覆盖率。例如某次请求的usage如下：
{
"input_tokens": 52000,
"cache_creation_input_tokens": 50000,
"cache_read_input_tokens": 0,
"output_tokens": 180
}
这是首次请求的典型结果，5万token被写入缓存，没有缓存命中。而第二次相同前缀的请求则会呈现：
{
"input_tokens": 54000,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 50000,
"output_tokens": 210
}
这次请求中，5万token直接命中缓存，只有新增的4000 token按标准输入价计费。如果标准输入价为每百万token 3美元，缓存读取价为0.3美元，那么本次请求的输入成本从原来的0.162美元降至0.027美元，降幅达到83%。随着请求次数增加，摊销后的成本趋近于90%的降幅。
缓存边界的工程实践细节
在实际工程接入中，有几个容易踩坑的细节值得提前考虑。首先是缓存标记的位置必须精确。一个常见的错误是只在system的最后一个文本块添加cache_control，却忽略了messages里也有一大段每轮重复的历史对话。如果历史对话确实稳定，可以在历史消息的最后一个内容块也加一个缓存标记，将缓存边界延伸到消息序列。不过要注意，对话历史一旦滚动更新，缓存前缀就会变化，需要重新写入。
另一个细节是流式响应的处理。启用缓存后，流式请求（stream=True）同样有效。缓存命中时，响应头中会包含anthropic-cache-hit: true这样的信息，但Anthropic官方推荐以usage字段为准，因为响应头的缓存标记在某些代理层可能会被剥离。
对于使用多模态输入的场景，图片内容也可以参与缓存。图片在Claude API中被编码为内容块，只要图片数据在前缀中保持稳定，同样可以标记为可缓存。不过图片的token消耗通常较高，缓存图片能带来的绝对成本节省更明显。
最后需要强调的是，Prompt Caching不是银弹。它解决的是重复前缀的计费与延迟问题，对于提示词本身的质量优化、上下文裁剪、检索增强等策略并不产生替代作用。真正有效的成本控制，应当是把缓存机制与提示词工程、上下文管理结合起来。先通过缓存降低重复调用成本，再通过合理的上下文设计减少不必要的token消耗，两者叠加才能把长文本场景的API支出压到最低。
Prompt CachingClaude API长文本成本修改时间：2026-09-29 03:42:56