以下是如何使用 Messages API 实现提示缓存的示例：

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"stream":true,
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of 'Pride and Prejudice'>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'."
        }
    ]
}'

Response:

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

在这个例子中,《傲慢与偏见》的全文通过 cache_control 参数进行了缓存。这样就可以在多次 API 调用中重复使用这段长文本，而无需每次都重新处理。只需改变用户消息，就能针对这本书提出各种问题，同时利用缓存内容，从而获得更快的响应速度和更高的效率。

​
提示词缓存的工作原理

当你发送启用了提示词缓存的请求时：

  1. 系统会检查是否已经缓存了最近查询中指定缓存断点之前的提示词前缀
  2. 如果找到,就使用缓存版本,减少处理时间和成本
  3. 否则,系统会处理完整提示词,并在开始响应时缓存前缀部分

这在以下场景特别有用：

  • 包含大量示例的提示词
  • 大量的上下文或背景信息
  • 具有一致指令的重复任务
  • 长时间的多轮对话

缓存的最短有效期为 5 分钟，每次使用缓存内容时都会刷新。

​
提示词缓存会缓存完整前缀

提示词缓存会引用整个提示词 - 按顺序包括 tools、system 和 messages,直到并包含使用 cache_control 标记的内容块。

​
如何实现提示词缓存

​
支持的模型

目前支持提示词缓存的模型包括:

  • Claude 3.7 Sonnet
  • Claude 3.5 Sonnet
  • Claude 3.5 Haiku
  • Claude 3 Haiku
  • Claude 3 Opus

​
构建提示词结构

将静态内容(工具定义、系统指令、上下文、示例)放在提示词的开头。使用 cache_control 参数标记要缓存的可重用内容的结束位置。

缓存前缀按以下顺序创建:tools、system，然后是 messages。

使用 cache_control 参数，你可以定义最多 4 个缓存断点，允许分别缓存不同的可重用部分。对于每个断点，系统会自动检查之前位置的缓存命中情况，如果找到就使用最长的匹配前缀。

​
缓存限制

最小可缓存提示词长度为：

  • Claude 3.7 Sonnet、Claude 3.5 Sonnet 和 Claude 3 Opus 为 1024 个 Token
  • Claude 3.5 Haiku 和 Claude 3 Haiku 为 2048 个 Token

即使标记了 cache_control，更短的提示词也无法缓存。任何请求缓存少于这个数量的 Token 都会在不使用缓存的情况下处理。要查看提示词是否被缓存，请查看响应使用情况字段。

对于并发请求，注意缓存条目只有在第一个响应开始后才可用。如果需要并行请求的缓存命中，请等待第一个响应后再发送后续请求。

缓存的最短生存时间(TTL)为 5 分钟。目前，“ephemeral” 是唯一支持的缓存类型，对应这个 5 分钟的最短生存期。

​
可以缓存的内容

请求中的每个块都可以用 cache_control 指定缓存。这包括：

  • 工具：tools 数组中的工具定义
  • 系统消息：system 数组中的内容块
  • 消息：messages.content 数组中的内容块,包括用户和助手的对话轮次
  • 图片和文档：用户对话轮次中 messages.content 数组的内容块
  • 工具使用和工具结果：用户和助手对话轮次中 messages.content 数组的内容块

这些元素都可以用 cache_control 标记来启用该部分请求的缓存。

​
跟踪缓存性能

通过响应中的这些 API 响应字段(或流式传输时的 message_start 事件)监控缓存性能：

  • cache_creation_input_tokens: 创建新缓存条目时写入缓存的 Token 数
  • cache_read_input_tokens: 从缓存中检索的 Token 数
  • input_tokens: 未从缓存读取或用于创建缓存的输入 Token 数

​
有效缓存的最佳实践

要优化提示词缓存性能：

  • 缓存稳定的、可重用的内容，如系统指令、背景信息、大型上下文或常用工具定义
  • 将缓存内容放在提示词开头以获得最佳性能
  • 策略性地使用缓存断点来分隔不同的可缓存前缀部分
  • 定期分析缓存命中率并根据需要调整策略

​
针对不同用例的优化

根据你的场景调整提示词缓存策略：

  • 对话代理：减少长时间对话的成本和延迟，特别是那些有长指令或上传文档的对话
  • 编程助手：通过在提示词中保留相关部分或代码库的摘要版本，改善自动完成和代码库问答
  • 大文档处理：在提示词中包含完整的长篇材料(包括图片)，而不增加响应延迟
  • 详细指令集：共享广泛的指令、程序和示例列表来微调 Claude 的响应。开发者通常在提示词中包含一两个示例，但使用提示词缓存，你可以通过包含 20+ 个高质量答案的多样化示例获得更好的性能
  • 代理工具使用：提升涉及多个工具调用和迭代代码更改的场景性能，每个步骤通常需要新的 API 调用
  • 与书籍、论文、文档、播客记录和其他长篇内容对话：通过在提示词中嵌入整个文档，让用户能够提问

​
常见问题解决

  • 确保缓存部分在不同调用之间完全相同,并在相同位置标记了 cache_control
  • 检查调用是否在 5 分钟缓存生存期内
  • 验证 tool_choice 和图片使用在调用之间保持一致
  • 确认你缓存的 Token 数至少达到最小要求
  • 虽然系统会尝试使用缓存断点之前位置的已缓存内容,但你可以使用额外的 cache_control 参数来保证查找提示词前面部分的缓存,这对于包含很长内容块列表的查询可能很有用

注意，更改 tool_choice 或提示词中任何位置的图片存在/缺失都会使缓存失效，需要创建新的缓存条目。

​
缓存存储和共享

  • 组织隔离: 缓存在组织之间是隔离的。不同组织永远不会共享缓存，即使它们使用相同的提示词。
  • 精确匹配: 缓存命中需要 100% 相同的提示词段，包括标记有 cache control 的块之前及其本身的所有文本和图片。在缓存读取和创建期间必须用 cache_control 标记相同的块。
  • 输出 Token 生成: 提示词缓存不会影响输出 Token 生成。你收到的响应将与不使用提示词缓存时完全相同。

​
不同模型的支持情况

  • 是否支持 Prompt Caching 取决于模型本身。
  • 如果模型本身支持，并且不需要显式声明相关的参数，则通过 opanai 兼容格式转发可以支持。
  • Openai 默认支持 Prompt Caching，缓存不计费，缓存 Tokens 读取费用减半，处于未复用状态 5-10 分钟之后会自动清除。文档
  • Claude 需要原生的 cache_control: { type: "ephemeral" } 声明，缓存费率为常规输入的 1.25 倍，缓存 Tokens 读取费用为 0.1 倍，生命周期 5 分钟。文档
  • Deepseek V3 和 R1 原生支持，缓存费率为常规输入的 1 倍，缓存 Tokens 读取费用为 0.1 倍。文档
  • Gemini 暂时只支持Gemini 1.5 Pro and Gemini 1.5 Flash，字段 client.caches.create。最低要求 32,768 Tokens，缓存生命周期模式默认为 1 小时。文档