Anthropic API/Claude 提示词缓存 Prompt Caching

在 Messages API 中使用 cache_control 断点、临时 TTL 与用量统计指标实现提示词缓存。

Claude 提示词缓存 Prompt Caching

本文档详细说明通过 UniGateway 使用 Anthropic Messages API(POST /v1/messages)的提示词缓存(Prompt Caching)能力,包括缓存断点设置、TTL 策略、最小可缓存 Token 阈值及用量监控诊断。


章节导引

本篇为 Anthropic Messages API 参考的第 4 章节:

  1. Messages 概述与快速开始
  2. 请求参数与消息格式
  3. 扩展推理 Thinking
  4. 提示词缓存 Prompt Caching(当前章节)
  5. 工具调用与 Computer Use
  6. 响应、流式与错误处理

提示词缓存原理

Claude Messages API 支持前缀提示词缓存(Prefix Prompt Caching)。当开发者在请求中对稳定的上下文(如大型系统提示词、长篇参考文档、大量工具定义或历史对话)设置缓存断点后,UniGateway 与底层上游会缓存该断点之前的所有 Token。

在随后的请求中,只要前缀内容与顺序完全一致且处于缓存存活期内,系统将直接复用已缓存状态:

  • 大幅降低延迟:命中缓存时的首字生成时间(TTFT)最高可缩短至原有的 1/5 至 1/10;
  • 显著降低成本:读取缓存内容的 Token 费率通常享有高达 90% 的折扣。

缓存断点设置(cache_control)

通过在特定内容块后附加 cache_control 对象即可声明缓存断点:

字段名类型必填取值与说明
typestring是固定为 "ephemeral"(临时缓存)
ttlstring否缓存存活时间。支持 "5m"(默认 5 分钟)或 "1h"(1 小时扩展缓存)

断点数量限制:官方限制单次请求中最多允许定义 4 个 cache_control 断点。超出时将触发 400 校验错误。


各模型最小可缓存长度对照表

为避免对琐碎短文本进行低效缓存,官方规定只有当断点累积的上下文超过模型设定的最小 Token 阈值时,才会真正触发缓存写入:

Claude 模型族最小可缓存长度说明
Claude Sonnet 5.5 / 5.0 / 4.6 / 4.51,024 Tokens最常用的长上下文与编码模型档位
Claude Opus 5.5 / 5.0 / 4.81,024 Tokens新代际高智能前沿推理模型
Claude Opus 4.72,048 Tokens4.7 代际模型中档阈值
Claude Opus 4.5 / 4.64,096 Tokens早期高算力模型阈值
Claude Haiku 5.5 / 4.54,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);

下一步