Skip to Content

Claude 提示词缓存

Claude 提示词缓存可以大幅降低重复请求的处理时间和 token 费用，特别适合包含大量固定内容（如系统指令、参考文档、代码库）的场景。

概述

通过在请求中标记 cache_control，你可以指定哪些内容需要被缓存。后续请求如果包含相同的缓存前缀，将直接复用缓存内容，显著降低延迟和成本。

最低缓存阈值：

  • Claude Opus / Sonnet 系列：1,024 tokens
  • Claude Haiku 系列：2,048 tokens

实现示例

cURL

curl https://api.acceleai.cn/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: <ACCELE_AI_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "你是一个专业的文学分析助手。"
      },
      {
        "type": "text",
        "text": "（此处放置需要缓存的大段文本，如完整的文学作品内容...）",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "分析这部作品的主要主题"}
    ]
  }'

Python (Anthropic SDK)

import anthropic
 
client = anthropic.Anthropic(
    api_key="<ACCELE_AI_API_KEY>",
    base_url="https://api.acceleai.cn"
)
 
# 流式调用
with client.messages.stream(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {"type": "text", "text": "你是一个专业的文学分析助手。"},
        {
            "type": "text",
            "text": "（大段参考文本...）",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "分析这部作品的主要主题"}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Python (requests)

import requests
import json
 
url = "https://api.acceleai.cn/v1/messages"
headers = {
    "content-type": "application/json",
    "x-api-key": "<ACCELE_AI_API_KEY>",
    "anthropic-version": "2023-06-01"
}
 
data = {
    "stream": True,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
        {"type": "text", "text": "你是一个专业的文学分析助手。"},
        {
            "type": "text",
            "text": "（大段参考文本...）",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {"role": "user", "content": "分析主要主题"}
    ]
}
 
response = requests.post(url, headers=headers, json=data, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

缓存机制

  1. 前缀检测：系统检查当前请求的内容是否与已缓存的前缀匹配
  2. 缓存命中：匹配成功则复用缓存，降低延迟和费用
  3. 缓存写入：未匹配则处理请求并将标记的内容写入缓存

缓存有效期：

  • 默认 5 分钟，每次缓存命中会刷新计时器
  • 扩展缓存（Beta）支持 1 小时 TTL

定价

操作费率
5 分钟缓存写入基础输入价格的 1.25 倍
1 小时缓存写入基础输入价格的 2 倍
缓存读取基础输入价格的 0.1 倍
普通输入/输出平台标准价格

支持的模型

  • Claude Opus 4 / 4.6
  • Claude Sonnet 4 / 4.5 / 4.6 / 3.7 / 3.5
  • Claude Haiku 3.5 / 3
  • Claude Opus 3

可缓存的内容类型

每个请求块都可以通过 cache_control 标记缓存：

  • 工具定义：tools 数组中的工具对象
  • 系统消息：system 数组中的内容块
  • 对话消息：messages 中用户和助手的内容块
  • 图片/文档：用户消息中的多媒体内容块
  • 工具调用/结果：用户和助手消息中的工具相关内容

不可缓存的内容：

  • 思维块（thinking blocks）不能直接使用 cache_control，但出现在之前的助手消息中时会被隐式缓存
  • 子内容块（如引用）需要在顶层标记缓存
  • 空文本块不可缓存

1 小时扩展缓存 (Beta)

启用 1 小时缓存需添加 Beta 头并在 cache_control 中指定 TTL：

curl https://api.acceleai.cn/v1/messages \
  -H "x-api-key: <ACCELE_AI_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "（大段参考文本...）",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}
      }
    ],
    "messages": [...]
  }'

可以在同一请求中混合使用不同 TTL 的缓存块。适用于批量处理、长会话、大文档分析和代码库问答等场景。

缓存命中监控

通过 API 响应中的以下字段跟踪缓存使用情况：

字段说明
cache_creation_input_tokens本次写入缓存的 token 数
cache_read_input_tokens从缓存读取的 token 数
input_tokens未缓存的输入 token 数

首次请求（缓存写入）：

{"cache_creation_input_tokens": 188086, "cache_read_input_tokens": 0}

后续请求（缓存命中）：

{"cache_creation_input_tokens": 0, "cache_read_input_tokens": 188086}

最佳实践

  • 缓存稳定内容：系统指令、背景知识、参考文档等不常变化的内容
  • 固定前缀位置：缓存内容放在提示词开头，缓存创建顺序为 tools → system → messages
  • 合理设置断点：最多支持 4 个缓存断点，合理分割不同的缓存前缀段
  • 监控缓存命中率：定期分析 cache_read_input_tokens 与 cache_creation_input_tokens 的比例

故障排查

  • 确保每次调用中被缓存的部分内容完全一致，cache_control 位置不变
  • 确认调用时间在缓存有效期内（5 分钟或 1 小时）
  • 检查 tool_choice 参数和图片有无变化，这些变化会导致缓存失效
  • 验证缓存 token 数是否达到最低阈值
  • 不同组织之间的缓存相互隔离，不会共享
  • 缓存命中要求前缀内容 100% 一致，包括缓存标记之前和之内的所有文本与图片
提示词缓存LLM 联网搜索