NLP——Claude模型API-Prompt缓存功能

  • 注：本文主要描述 Claude 模型 API Prompt 缓存功能，也称为 前缀缓存功能、Prefix 缓存 或 Prefix Caching 功能

Claude API Prompt Caching 功能介绍

  • Claude 官方提供了前缀缓存的能力（注意是严格匹配）
  • 第一次存放缓存需要多花钱（约提升 25%），后续命中 Cache 会大幅度缩小（节省约 90%）
  • 注意：每次都要添加缓存标签才能成功

Claude API Prompt Caching 功能如何使用？

开启 Prompt Caching 的方法

  • 在 API 请求中，对需要缓存的内容块添加 cache_control 参数即可
  • 注：不需要额外开关 ，只需在 system、messages 或 tools 中标记缓存断点
代码示例1：在 System 中添加缓存点
  • Python SDK 示例： 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    import anthropic

    client = anthropic.Anthropic()

    response = client.messages.create(
    	model="claude-sonnet-4-20250514",
    	max_tokens=1024,
    	system=[
    		{
    			"type": "text",
    			"text": "你是一个很长的系统提示...(大量文本)...",
    			"cache_control": {"type": "ephemeral"}  # 标记缓存断点
    		}
    	],
    	messages=[
    		{"role": "user", "content": "你的问题"}
    	]
    )
代码示例2：在 messages 中添加缓存点（Python SDK）
  • Python SDK 示例： 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    response = client.messages.create(
    	model="claude-sonnet-4-20250514",
    	max_tokens=1024,
    	system="你是一个助手",
    	messages=[
    		{
    			"role": "user",
    			"content": [
    				{
    					"type": "text",
    					"text": "这是一篇很长的文档内容...(几万字)...",
    					"cache_control": {"type": "ephemeral"}  # 👈 缓存断点
    				}
    			]
    		},
    		{
    			"role": "assistant",
    			"content": "好的，我已阅读这篇文档。请问有什么问题？"
    		},
    		{
    			"role": "user",
    			"content": "请总结第三章的内容"  # 这条不缓存，每次变化
    		}
    	]
    )
代码示例3：多轮对话中缓存历史消息
  • Python SDK 示例 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    messages = [
    	{"role": "user", "content": [{"type": "text", "text": "长文档..."}]},
    	{"role": "assistant", "content": "回答1..."},
    	{"role": "user", "content": [{"type": "text", "text": "追问1..."}]},
    	{"role": "assistant", "content": "回答2..."},
    	{
    		"role": "user",
    		"content": [
    			{
    				"type": "text",
    				"text": "追问2...",
    				"cache_control": {"type": "ephemeral"}  # 👈 缓存到此为止的所有历史
    			}
    		]
    	},
    	{"role": "assistant", "content": "回答3..."},
    	{"role": "user", "content": "新问题（不缓存）"}
    ]
使用关键点
  • content 必须用数组格式（[{"type": "text", "text": "...", "cache_control": ...}]），不能用纯字符串
  • 缓存是前缀式的：系统会缓存从请求开头到断点之间的所有内容（包括 system、tools、以及断点之前的所有 messages）

一些要求

  • 可缓存位置包括：
    • system 消息中的内容块
    • messages 中的用户消息内容块（如包含大量上下文的对话）
    • tools 定义列表
  • 可以设置最多 4 个 cache_control 断点
    • 系统会缓存从请求开头到每个断点之间的所有内容
    • 注意：缓存是严格前缀匹配的，如果是设置了前 4 轮缓存，但只命中 前 2 轮前缀，不会触发缓存，解决方案是在第 2 轮也加一个缓存标记
  • 支持的模型
    • Claude Opus 4 / 4.5
    • Claude Sonnet 4 / 3.5
    • Claude Haiku 3.5
  • 最低 Token 要求：缓存内容必须达到最低 token 数才能生效：
    • Claude Opus 4 / 4.5 ：2048 tokens
    • Claude Sonnet 4 / 3.5 ： 1024 tokens
    • Claude Haiku 3.5 ： 1024 tokens
  • 缓存 TTL（生存时间）
    • 默认 5 分钟
    • 每次缓存命中（cache hit）会刷新 TTL
    • 即只要持续使用，缓存会一直有效
  • 每次都要添加缓存标签才能成功，举例：
    • 第一次：[system + cache_control] [user: “问题1”] → 缓存写入
    • 第二次：[system + cache_control] [user: “问题2”] → 缓存命中 (system 部分从缓存读取)
    • 第三次：[system 无标记] [user: “问题3”] → 缓存未命中 (全部按普通输入)

缓存计费方式

  • Prompt Caching 有三种 token 类型，计费不同：
    Token 类型 说明 费率（相对于基础输入价格）
    Cache Write 首次写入缓存 基础输入价格的 125%（即贵 25%）
    Cache Read 缓存命中读取 基础输入价格的 10%（即便宜 90%）
    普通 Input 未缓存的输入 基础输入价格的 100%
  • 以 Claude Sonnet 4 为例
    类型 价格（每百万 token）
    普通输入 $3.00
    Cache Write $3.75
    Cache Read $0.30
  • 首次请求多付 25%（写入缓存），后续请求节省 90%
    • 对于多轮对话、大量系统提示等场景，整体成本大幅下降

响应中如何查看缓存情况

  • API 响应的 usage 字段会返回：

    1
    2
    3
    4
    5
    6
    7
    8
    {
    "usage": {
    	"input_tokens": 50,
    	"output_tokens": 200,
    	"cache_creation_input_tokens": 1500,
    	"cache_read_input_tokens": 3000
    }
    }
    • cache_creation_input_tokens > 0 ：发生了缓存写入
    • cache_read_input_tokens > 0 ：缓存命中

缓存实现的最佳实践

  • 1）把不变的内容放前面 ：system prompt、tools 定义、长文档等放在请求开头并标记缓存
  • 2）变化的内容放后面 ：用户的具体问题放在最后
  • 3）多轮对话场景 ：在最后一个 user message 的前一条消息上设置 cache_control，这样整个对话历史都会被缓存
  • 4）大文档分析 ：将文档放入 system 或首条 user message 中缓存，后续问答极大节省成本