Claude API 提示缓存完全指南：降低 90% 输入成本
如果你用 Claude API 构建多轮对话应用或处理大上下文任务，每次请求都重新发送完整的 system prompt 和历史消息，token 费用会快速累积。Prompt Caching 是 Anthropic 官方提供的解决方案——缓存命中时，输入 token 价格降低到 原价的 1/10。
本文是一份完整的实践指南，覆盖原理、两种使用方式、定价计算、以及容易踩坑的地方。
Prompt Caching 的工作原理
每次 API 请求时，系统会检查你的 prompt 前缀是否有缓存：
- 检查缓存：从 prompt 开头到指定的缓存断点位置，检查是否命中已有缓存
- 命中则复用：匹配成功则跳过该部分的处理，直接使用缓存
- 未命中则写入：完整处理 prompt，并将前缀写入缓存供后续请求使用
缓存按层级结构生效：tools → system → messages。任何一层发生变化，该层及后续所有层的缓存都会失效。
关键理解：缓存是前缀匹配。只有从 prompt 开头开始、连续不变的部分才能被缓存。中间插入变化内容会导致后续全部失效。
支持的模型与最低 Token 要求
所有当前活跃的 Claude 模型都支持 Prompt Caching：
| 模型 | 最低可缓存 Token 数 |
|---|---|
| Claude Opus 4.7 / 4.6 / 4.5、Haiku 4.5 | 4,096 tokens |
| Claude Sonnet 4.6 / 4.5、Opus 4.1 | 1,024 tokens |
低于最低要求的 prompt 即使标记了 cache_control 也不会被缓存。
两种使用方式
自动缓存（推荐多轮对话）
在请求顶层添加 cache_control 字段，系统自动将缓存断点放在最后一个可缓存的内容块上，并随对话增长自动前移：
随着对话进行，缓存行为如下：
| 请求 | 缓存行为 |
|---|---|
| 第 1 轮 | 全部内容写入缓存 |
| 第 2 轮 | 前一轮内容从缓存读取，新增部分写入 |
| 第 3 轮 | 所有历史从缓存读取，仅新消息写入 |
自动缓存是最简单的用法——一行配置搞定多轮对话的缓存优化，不需要手动管理断点位置。
手动断点（精细控制）
在特定内容块上添加 cache_control，精确控制哪些部分被缓存。最多支持 4 个断点：
适用场景：prompt 中有些部分（如代码规范）永远不变，有些部分（如用户当前问题）每次都变。手动断点让你精确切割。
缓存时长（TTL）
| 类型 | TTL | 写入价格 | 适用场景 |
|---|---|---|---|
| 默认 | 5 分钟 | 1.25x 基础输入价 | 快节奏多轮对话 |
| 长期 | 1 小时 | 2x 基础输入价 | 用户可能间隔较长再回来 |
5 分钟 TTL 意味着：如果用户超过 5 分钟没有发消息，下一条消息会触发缓存重写（1.25x 价格）而不是缓存读取（0.1x 价格）。对于低频交互场景，考虑使用 1 小时 TTL。
定价详解
以 Claude Sonnet 4.6 为例（每百万 token）：
| 操作 | 价格 | 相对基础输入价 |
|---|---|---|
| 基础输入 | $3 | 1x |
| 5 分钟缓存写入 | $3.75 | 1.25x |
| 1 小时缓存写入 | $6 | 2x |
| 缓存读取 | $0.30 | 0.1x |
| 输出 | $15 | — |
核心算术：首次写入多花 25%，后续每次读取节省 90%。只要同一缓存被读取 2 次以上，总成本就低于不缓存的方案。
监控缓存效果
每次 API 响应的 usage 字段包含三个关键指标：
总输入 token = cache_read + cache_creation + input
理想状态下，稳定对话中 cache_read_input_tokens 应该远大于 cache_creation_input_tokens。如果每次都在写入而不是读取，说明缓存频繁失效——检查是否有不该变化的内容在变化。
缓存预热（Pre-warming）
对于需要极快首次响应的场景，可以提前发一个空请求来"预热"缓存：
常见陷阱与最佳实践
陷阱：在变化内容上设置断点
最佳实践清单
- 多轮对话首选自动缓存，一行配置即可
- 稳定内容放前面：system prompt → 背景资料 → 工具定义 → 历史消息 → 当前问题
- 验证缓存命中：检查
cache_read_input_tokens > 0 - 超过 5 分钟间隔的场景用 1 小时 TTL
- 不要在 tools 数组中频繁增删工具——tools 在缓存层级最前面，变化会导致后续全部失效
完整示例：带缓存的 RAG 应用
总结
| 场景 | 推荐方式 |
|---|---|
| 多轮对话 | 顶层 cache_control（自动） |
| 大段不变的参考资料 + 变化的问题 | 手动断点 |
| 工具定义 + system prompt 固定 | 手动断点放在 system 末尾 |
| 低频交互（>5 分钟间隔） | 1 小时 TTL |
| 首次响应延迟敏感 | 预热请求 |
Prompt Caching 是 Claude API 中投入产出比最高的优化手段。配置简单（最少只需一行），收益显著（最高省 90%），且对模型输出质量完全没有影响。如果你的应用有重复的 prompt 前缀，现在就该启用它。