每次 API 请求，Claude 都要处理你发送的全部 token——包括 system prompt、工具定义、历史消息。如果你的 system prompt 有 5000 token，每次请求都重复处理这 5000 token，浪费且昂贵。Prompt Caching 解决了这个问题：缓存不变的前缀，后续请求只需处理新增内容，节省高达 90% 的输入 token 费用。
你将学到什么
- Prompt Caching 的工作原理
- 两种缓存方式（自动和手动）
- 实际的节省效果和计费方式
- 最佳实践和常见陷阱
工作原理
缓存工作原理
Prompt Caching 缓存请求的前缀（prefix）。当多次请求共享相同的前缀时：
- 首次请求：完整处理，写入缓存（多付 25% 写入费）
- 后续请求：读取缓存（只付 10% 的费用）
- 缓存有效期：5 分钟（每次命中刷新），可选 1 小时
自动缓存（最简单）
python
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
cache_control={"type": "ephemeral"}, # 一行启用
system="你是一位专业的法律顾问..." , # 长 system prompt
messages=[{"role": "user", "content": "合同违约怎么赔偿？"}]
)
手动缓存断点（精确控制）
python
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[{
"type": "text",
"text": "你是法律顾问，以下是参考法条...（5000字）",
"cache_control": {"type": "ephemeral"} # 在这里设置缓存断点
}],
messages=[
{"role": "user", "content": "违约金怎么计算？"}
]
)
费用对比
费用对比
以 Sonnet 4.6 为例（每百万 token）：
- 无缓存：输入 $3.00
- 缓存写入：$3.75（1.25 倍）
- 缓存读取：$0.30（0.1 倍）
实际场景：5000 token 的 system prompt，进行 100 次对话
- 无缓存：5000 × 100 × $3/M = $1.50
- 有缓存：5000 × $3.75/M（写入 1 次）+ 5000 × 99 × $0.30/M（读取 99 次）= $0.17
节省 89%！
查看缓存命中情况
python
print(response.usage)
# input_tokens: 50
# cache_creation_input_tokens: 5000 ← 首次：写入缓存
# cache_read_input_tokens: 0
# 第二次请求
# input_tokens: 50
# cache_creation_input_tokens: 0
# cache_read_input_tokens: 5000 ← 命中缓存！
可缓存的内容
可缓存内容
按处理顺序，前缀匹配：
- tools（工具定义）
- system（系统提示词）
- messages（对话消息）
Tip: 把最长且最不变的内容放在最前面（tools → system → 静态消息），效果最好。
最佳实践
- 长 system prompt 一定要缓存：超过 1000 token 就值得
- 多轮对话天然受益：历史消息作为前缀自动缓存
- 批量调用同一 prompt：第一次写入，后续全部命中
- 工具定义也可以缓存：如果你的 tools 数组很大
常见陷阱
常见陷阱
- 缓存只匹配完全相同的前缀，改一个字就失效
- 最小缓存内容因模型而异（通常 1024+ token）
- 5 分钟不访问就过期
实战练习
Tip: 在你的应用中启用缓存。
- 给你的 API 调用加上 cache_control，观察 usage 中的缓存指标
- 计算你的应用在有缓存和无缓存下的月度成本差异
- 优化请求结构，把静态内容放在前缀位置
关键要点
Note: 本文核心总结
- Prompt Caching 缓存请求前缀，后续只付 10% 费用
- 一行代码启用：cache_control=
{"type": "ephemeral"} - 长 system prompt + 多轮对话 + 批量调用场景收益最大
- 通过 usage 字段监控缓存命中率