Prompt Caching 是 Claude API 中最重要的成本优化能力之一。它允许你把长系统提示、背景文档、工具定义、few-shot 示例等稳定内容缓存起来，后续请求只需要支付更低的读取成本，并减少首 token 延迟。
它解决什么问题？
很多生产级 Claude 应用都有大量重复上下文：
- 长系统提示和角色规则
- 产品文档、API 文档、规范说明
- 大量 few-shot 示例
- 工具 schema 和 MCP 工具说明
- RAG 检索后反复使用的同一批资料
如果每次请求都完整发送这些内容，成本和延迟都会很高。Prompt Caching 的思路是：稳定内容只写入一次，后续请求命中缓存。
基本用法
在内容块上加 cache_control：
json
{
"type": "text",
"text": "这里是很长、会重复使用的上下文...",
"cache_control": { "type": "ephemeral" }
}典型请求结构：
json
{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "长系统提示和团队规范...",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [
{ "role": "user", "content": "请基于上述规范生成接口文档" }
]
}第一次请求写入缓存，后续相同前缀内容可以复用。
适合缓存什么？
适合：
- 系统提示
- 团队编码规范
- API 文档
- 产品规格说明
- 大型工具 schema
- few-shot 示例
- 用户会反复查询的长文档
不适合：
- 每次都会变化的用户问题
- 当前时间、临时状态、一次性变量
- 包含短期敏感数据的内容
- 过短内容，收益不明显
缓存断点设计
缓存命中依赖前缀匹配。稳定内容应该放在前面，变化内容放在后面。
推荐顺序：
- 系统规则
- 长文档/知识库片段
- 工具定义
- few-shot 示例
- 本次用户问题
如果把用户问题放在中间，会破坏后续内容的缓存命中。
与工具调用的关系
工具 schema 也会消耗 token，尤其是工具很多、参数复杂时。对于长期不变的工具定义，Prompt Caching 可以减少重复成本。
Agent 应用中常见结构：
- 缓存：系统提示、工具定义、业务规则
- 不缓存：当前任务、工具结果、最新状态
这样可以让多轮 Agent 循环更稳定，也更便宜。
生产最佳实践
- 把稳定内容放在请求最前面
- 不要把时间戳、随机 ID 放进缓存区域
- 对文档内容做版本化，文档变更时自然刷新缓存
- 监控
cache_creation_input_tokens和cache_read_input_tokens - 大型工具 schema 尽量稳定，不要动态重排字段
- 和 Citations、Batch Processing 组合使用时，优先缓存大文档
适合场景
- 企业知识库问答
- 代码库级别 AI 助手
- 文档审查和合规分析
- 多工具 Agent 平台
- 长系统提示的客服/销售助手
- 需要反复读取同一 PDF 或规范的应用
来源：Anthropic 官方文档 - Prompt caching | 整理：ClaudeEagle