简介
提示词缓存（Prompt Caching） 允许你将输入中的大段稳定内容（如长文档、背景信息、系统指令等）缓存起来。这样后续请求只要内容不变，就能直接复用缓存，避免重复处理，显著提升响应速度并节省费用。适用于多轮对话、长文档分析、批量问答等场景。
什么时候考虑使用
类似 Redis 等缓存策略，当有大量重复利用的上下文时，建议启用提示词缓存。
不同的是，提示词缓存更偏好长内容，因为缓存读取只要基础输入的10%的费用。
比如可以针对以下场景进行针对性的优化：
• 对话型机器人：对于包含长指令或需要上传文档的持续对话，缓存能有效降低每轮对话的成本和延迟。 • 代码助手：将代码库摘要或相关代码片段缓存后，可以更高效地实现代码自动补全和问答。 • 大文档处理：可以将整本书、长论文或包含图片的文档一次性缓存，后续多次提问时无需重复上传，提升响应速度且不增加延迟。 • 复杂指令和示例：如果需要让模型参考大量指令、流程或示例，缓存后可以在每次调用时直接复用，支持更丰富和多样化的高质量案例。 • 多工具和多步骤流程：在涉及多次工具调用或代码迭代的场景中，缓存可减少每一步的重复输入，提高整体处理效率。 • 知识库互动：如与书籍、论文、文档、播客转录等长文本内容交互时，将整个文档缓存后，用户可以多次提问，体验更流畅。
通过结合自身场景，合理利用缓存，可以显著优化API调用的成本和响应速度。
价格
官方针对价格描述的很清楚，所以你要多输入少输出，因为输出是输入的 5 倍，没有变。
• 5分钟缓存写入比基础输入贵25%，1小时缓存写入贵100%，缓存读取只要基础输入的10%。 • 输出token（模型生成内容）价格最高。
特别说明下： 每当你在5分钟内再次用到这份缓存（比如用相同的内容发起请求），缓存的有效期会重新变成5分钟，并且 这个“刷新”不会产生额外费用。
如何使用
只需在API请求中用 cache_control 标记要缓存的内容，后续同样内容会自动复用缓存，无需手动管理缓存生命周期。这样可以大幅降低大输入场景下的API成本和延迟。
以下是如何使用 cache_control 块通过 Messages API 实现提示缓存的示例：
import Anthropicfrom'@anthropic-ai/sdk';
const client = newAnthropic();
const response = await client.messages.create({
model: "claude-opus-4-20250514",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
type: "text",
text: "<the entire contents of 'Pride and Prejudice'>",
cache_control: { type: "ephemeral" }
}
],
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
});
console.log(response.usage);
// Call the model again with the same inputs up to the cache checkpoint
const new_response = await client.messages.create(...)
console.log(new_response.usage);response
{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}使用时注意事项
• 提示词缓存有最小长度要求，大部分内容块都能缓存，但有少数例外。 • 比如模型要求最少输入的 Token 要 1024 • 思考块（thinking block）不能直接用 cache_control 缓存，但如果和其他内容一起出现，可以被间接缓存。 • 子内容块（如引用）不能直接缓存，只能缓存其顶级块（如文档本身）。 • 默认情况下，缓存的生命周期为5分钟。每当你在5分钟内再次用到这份缓存（比如用相同的内容发起请求），缓存的有效期会重新变成5分钟，并且这个“刷新”不会产生额外费用。 • 假设你在12:00创建了缓存，缓存会在12:05失效。如果你在12:03又用了一次缓存，有效期会被延长到12:08。 • 缓存只在本组织内有效，只有完全相同的内容才能复用缓存，缓存不会改变模型的输出结果。 • 每个组织的缓存都是独立的。即使不同组织用完全一样的提示内容，也不会共享缓存数据，保证数据安全和隐私。 • 只有当你的请求内容（包括所有文本和图片）和之前缓存时一模一样，缓存才会被命中。哪怕有一个字或一张图片不同，也不会用到缓存。 • 缓存时间支持混合使用，计费会根据你命中缓存的位置和每个缓存段的类型分段计算。
提示词缓存常见问题
1. 缓存的生命周期有多久？
默认缓存有效期为5分钟。如果5分钟内再次命中缓存，有效期会自动延长5分钟。也可以通过参数设置为1小时。
2. 我可以定义多少个缓存断点？
每个请求最多可设置4个缓存断点（即4个 cache_control 标记）。
3. 哪些模型支持提示词缓存？
目前支持 Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5、Claude Haiku 3.5、Claude Haiku 3、Claude Opus 3。
4. 缓存最小长度是多少？
• Opus/Sonnet 系列：至少1024 tokens • Haiku 系列：至少2048 tokens
短于这个长度的内容不会被缓存。
5. 缓存对输出内容有影响吗？
没有影响。缓存只优化输入部分，输出内容和不使用缓存时完全一致。
6. 缓存会在不同组织之间共享吗？
不会。缓存严格隔离在各自组织内，不同组织即使内容完全相同也不会共享缓存。
7. 什么情况下缓存会失效？
• 缓存内容有任何变动（文本、图片等） • 超过缓存生命周期未被使用 • 修改工具选择、图片内容等 • 子内容块（如引用）或思考块无法直接缓存
8. 如何判断请求是否命中缓存？
查看API响应的 usage 字段，cache_read_input_tokens 大于0表示命中缓存。
9. 可以手动清除缓存吗？
不可以。缓存只能在生命周期结束后自动过期。
10. 缓存可以和哪些API功能一起用？
可以和工具调用、视觉能力等功能结合使用。但更改是否包含图片或工具设置会使缓存失效。
11. 缓存读取和写入如何计费？
• 写入缓存：比基础输入token贵25%（5分钟）或100%（1小时） • 读取缓存：只需基础输入token的10% • 输出token始终单独按标准价计费
12. 缓存安全性如何？
缓存采用加密哈希，且组织隔离，保证数据安全和隐私。
以上是关于所有内容，感觉还是贵，希望 Anthropic 能针对输出也能做缓存。不知道国内厂商是不是有类似功能，毕竟给 Agent 加缓存，就像给软件加缓存，又快有高效。
