type
status
date
slug
summary
tags
category
icon
password
简介
提示词缓存（Prompt Caching）允许你将输入中的大段稳定内容（如长文档、背景信息、系统指令等）缓存起来。这样后续请求只要内容不变，就能直接复用缓存，避免重复处理，显著提升响应速度并节省费用。适用于多轮对话、长文档分析、批量问答等场景。
什么时候考虑使用
类似 Redis 等缓存策略，当有大量重复利用的上下文时，建议启用提示词缓存。不同的是，提示词缓存更偏好长内容，因为缓存读取只要基础输入的10%的费用。
比如可以针对以下场景进行针对性的优化：
- 对话型机器人：对于包含长指令或需要上传文档的持续对话，缓存能有效降低每轮对话的成本和延迟。
- 代码助手：将代码库摘要或相关代码片段缓存后，可以更高效地实现代码自动补全和问答。
- 大文档处理：可以将整本书、长论文或包含图片的文档一次性缓存，后续多次提问时无需重复上传，提升响应速度且不增加延迟。
- 复杂指令和示例：如果需要让模型参考大量指令、流程或示例，缓存后可以在每次调用时直接复用，支持更丰富和多样化的高质量案例。
- 多工具和多步骤流程：在涉及多次工具调用或代码迭代的场景中，缓存可减少每一步的重复输入，提高整体处理效率。
- 知识库互动：如与书籍、论文、文档、播客转录等长文本内容交互时，将整个文档缓存后，用户可以多次提问，体验更流畅。
通过结合自身场景，合理利用缓存，可以显著优化API调用的成本和响应速度。
价格
这个价格官方，已经说的很清楚，所以你要多输入少输出，因为输出是输入的 5 倍，没有变。
Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
Claude Opus 3 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
- 5分钟缓存写入比基础输入贵25%，1小时缓存写入贵100%，缓存读取只要基础输入的10%。
- 输出token（模型生成内容）价格最高。
特别说明下：每当你在5分钟内再次用到这份缓存（比如用相同的内容发起请求），缓存的有效期会重新变成5分钟，并且这个“刷新”不会产生额外费用。
如何使用
只需在API请求中用 cache_control 标记要缓存的内容，后续同样内容会自动复用缓存，无需手动管理缓存生命周期。这样可以大幅降低大输入场景下的API成本和延迟。
以下是如何使用
cache_control块通过Messages API实现提示缓存的示例：response
使用时注意事项
- 提示词缓存有最小长度要求，大部分内容块都能缓存，但有少数例外。
- 比如模型要求最少输入的 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 加缓存，就像给软件加缓存，又快有高效。
- Author:二师兄
- URL:https://cloudesx.com/article/claude-prompt-caching
- Copyright:All articles in this blog, except for special statements, adopt BY-NC-SA agreement. Please indicate the source!
