Claude 提示词缓存 Prompt Caching
本文档详细说明通过 UniGateway 使用 Anthropic Messages API(POST /v1/messages)的提示词缓存(Prompt Caching)能力,包括缓存断点设置、TTL 策略、最小可缓存 Token 阈值及用量监控诊断。
章节导引
本篇为 Anthropic Messages API 参考的第 4 章节:
- Messages 概述与快速开始
- 请求参数与消息格式
- 扩展推理 Thinking
- 提示词缓存 Prompt Caching(当前章节)
- 工具调用与 Computer Use
- 响应、流式与错误处理
提示词缓存原理
Claude Messages API 支持前缀提示词缓存(Prefix Prompt Caching)。当开发者在请求中对稳定的上下文(如大型系统提示词、长篇参考文档、大量工具定义或历史对话)设置缓存断点后,UniGateway 与底层上游会缓存该断点之前的所有 Token。
在随后的请求中,只要前缀内容与顺序完全一致且处于缓存存活期内,系统将直接复用已缓存状态:
- 大幅降低延迟:命中缓存时的首字生成时间(TTFT)最高可缩短至原有的 1/5 至 1/10;
- 显著降低成本:读取缓存内容的 Token 费率通常享有高达 90% 的折扣。
缓存断点设置(cache_control)
通过在特定内容块后附加 cache_control 对象即可声明缓存断点:
| 字段名 | 类型 | 必填 | 取值与说明 |
|---|---|---|---|
type | string | 是 | 固定为 "ephemeral"(临时缓存) |
ttl | string | 否 | 缓存存活时间。支持 "5m"(默认 5 分钟)或 "1h"(1 小时扩展缓存) |
断点数量限制:官方限制单次请求中最多允许定义 4 个
cache_control断点。超出时将触发 400 校验错误。
各模型最小可缓存长度对照表
为避免对琐碎短文本进行低效缓存,官方规定只有当断点累积的上下文超过模型设定的最小 Token 阈值时,才会真正触发缓存写入:
| Claude 模型族 | 最小可缓存长度 | 说明 |
|---|---|---|
| Claude Sonnet 5.5 / 5.0 / 4.6 / 4.5 | 1,024 Tokens | 最常用的长上下文与编码模型档位 |
| Claude Opus 5.5 / 5.0 / 4.8 | 1,024 Tokens | 新代际高智能前沿推理模型 |
| Claude Opus 4.7 | 2,048 Tokens | 4.7 代际模型中档阈值 |
| Claude Opus 4.5 / 4.6 | 4,096 Tokens | 早期高算力模型阈值 |
| Claude Haiku 5.5 / 4.5 | 4,096 Tokens | 轻量级模型适用大批量前缀复用 |
注:若断点前缀未达到上述最小长度,请求仍会正常响应,但不会发生缓存写入,也不会产生 cache_creation_input_tokens 统计。
断点布局最佳实践
为了最大化缓存命中率,推荐将上下文按照“稳定性从高到低”从前至后排列:
1. 系统提示词断点(System Prompt)
适用于长期不变的业务背景、指令规则或多语言设定:
{
"model": "claude-sonnet-5-5",
"max_tokens": 4096,
"system": [
{
"type": "text",
"text": "你是一个专业的企业财务分析专家,精通 GAAP 与 IFRS 会计准则...\n[此处包含数万字详尽规则]",
"cache_control": {
"type": "ephemeral"
}
}
],
"messages": [...]
}
2. 工具定义断点(Tools Schema)
在拥有数十个复杂自定义工具的 Agent 架构中,可在最后一个工具定义上附加缓存断点:
{
"model": "claude-sonnet-5-5",
"max_tokens": 4096,
"tools": [
{"name": "fetch_balance", "...": "..."},
{"name": "query_ledger", "...": "..."},
{
"name": "generate_report",
"description": "生成综合财务报表",
"input_schema": {...},
"cache_control": {
"type": "ephemeral"
}
}
],
"messages": [...]
}
3. 多轮历史对话断点(Multi-turn Messages)
在多轮长会话中,通常将断点打在倒数第二轮(即最后一个已确认的 assistant 或 tool_result 块上),当前最新轮次的 user 输入则不加断点:
{
"model": "claude-sonnet-5-5",
"max_tokens": 4096,
"messages": [
{"role": "user", "content": "这是我们的季度销售报表:..."},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "已完整解析第一季度财务数据。请问需要重点分析哪项指标?",
"cache_control": {
"type": "ephemeral"
}
}
]
},
{"role": "user", "content": "请对比华东与华北区域的毛利率差异。"}
]
}
缓存用量分析与诊断
在完成包含缓存断点的请求后,响应体中的 usage 对象会详细列出缓存读写指标:
{
"id": "msg_01...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5-5",
"usage": {
"input_tokens": 35,
"output_tokens": 420,
"cache_creation_input_tokens": 2850,
"cache_read_input_tokens": 0
}
}
cache_creation_input_tokens:初次写入缓存的 Token 数量。此时该部分 Token 会按正常输入费率(或包含微量缓存写入费率)计费;cache_read_input_tokens:后续请求成功命中缓存并读取的 Token 数量。该部分享受超低折扣费率;input_tokens:未被缓存覆盖的非命中输入 Token 数(通常为当前轮次的新增内容)。
代码示例
Python SDK(提示词缓存请求)
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ.get("UNIGATEWAY_API_KEY"),
base_url="https://api.unigateway.ai",
)
# 模拟大型参考文档(超过 1024 Token)
large_context = "UniGateway 开发者架构白皮书...\n" * 200
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=2048,
system=[
{
"type": "text",
"text": large_context,
"cache_control": {"type": "ephemeral", "ttl": "5m"},
}
],
messages=[
{"role": "user", "content": "请根据以上白皮书内容总结系统容灾策略。"}
],
)
print(response.content[0].text)
print("\n用量诊断:")
print(f"写入缓存 Tokens: {response.usage.cache_creation_input_tokens}")
print(f"读取缓存 Tokens: {response.usage.cache_read_input_tokens}")
print(f"常规输入 Tokens: {response.usage.input_tokens}")
TypeScript SDK(提示词缓存请求)
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: process.env.UNIGATEWAY_API_KEY,
baseURL: 'https://api.unigateway.ai',
});
const largeContext = 'UniGateway 开发者架构白皮书...\n'.repeat(200);
const response = await client.messages.create({
model: 'claude-sonnet-5-5',
max_tokens: 2048,
system: [
{
type: 'text',
text: largeContext,
cache_control: { type: 'ephemeral', ttl: '5m' },
},
],
messages: [
{ role: 'user', content: '请根据以上白皮书内容总结系统容灾策略。' },
],
});
console.log(response.content[0].text);
console.log('缓存写入:', response.usage.cache_creation_input_tokens);
console.log('缓存读取:', response.usage.cache_read_input_tokens);
下一步
- 为模型配置外部工具与计算机操作:工具调用与 Computer Use
- 解析流式输出事件与标准错误处理:响应、流式与错误处理
- 回顾消息格式与内容块基础:请求参数与消息格式