Claude 提示词缓存

以下是如何使用 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-opus-4-20250514",
    "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."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [此处放置完整文本内容]",
        "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 调用中重复使用这段长文本，而无需每次都重新处理。只需改变用户消息，就能针对这本书提出各种问题，同时利用缓存内容，从而获得更快的响应速度和更高的效率。

提示词缓存的工作原理

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

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

这在以下场景特别有用：

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

缓存默认有效期为 5 分钟，每次使用缓存内容时都会刷新。我们还支持 1 小时缓存版本（Beta），适用于需要更长缓存时间的场景。

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

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

缓存定价

提示词缓存采用新的定价结构。下表显示了每个支持模型的百万 Token 价格：

模型	基础输入 Token	5 分钟缓存写入	1 小时缓存写入	缓存命中和刷新	输出 Token
Claude Opus 4	按平台定价	1.25x 基础价格	2x 基础价格	0.1x 基础价格	按平台定价
Claude Sonnet 4	按平台定价	1.25x 基础价格	2x 基础价格	0.1x 基础价格	按平台定价
Claude Sonnet 3.7	按平台定价	1.25x 基础价格	2x 基础价格	0.1x 基础价格	按平台定价
Claude Sonnet 3.5	按平台定价	1.25x 基础价格	2x 基础价格	0.1x 基础价格	按平台定价
Claude Haiku 3.5	按平台定价	1.25x 基础价格	2x 基础价格	0.1x 基础价格	按平台定价
Claude Opus 3	按平台定价	1.25x 基础价格	2x 基础价格	0.1x 基础价格	按平台定价
Claude Haiku 3	按平台定价	1.25x 基础价格	2x 基础价格	0.1x 基础价格	按平台定价

注意：

5 分钟缓存写入 Token 价格为基础输入 Token 价格的 1.25 倍
1 小时缓存写入 Token 价格为基础输入 Token 价格的 2 倍
缓存读取 Token 价格为基础输入 Token 价格的 0.1 倍
常规输入和输出 Token 按平台标准费率计价

如何实现提示词缓存

支持的模型

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

Claude Opus 4
Claude Sonnet 4
Claude Sonnet 3.7
Claude Sonnet 3.5
Claude Haiku 3.5
Claude Haiku 3
Claude Opus 3

构建提示词结构

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

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

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

缓存限制

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

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

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

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

目前支持两种缓存类型：

“ephemeral”：默认 5 分钟生存期
1 小时缓存（Beta）：适用于需要更长缓存时间的场景

1 小时缓存持续时间（Beta）

对于需要更长缓存时间的场景，我们提供 1 小时缓存选项。

要使用扩展缓存，需要在请求中添加 extended-cache-ttl-2025-04-11 作为 beta header，然后在 cache_control 定义中包含 ttl：

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

何时使用 1 小时缓存

1 小时缓存特别适用于：

批处理作业：处理大量具有共同前缀的请求
长时间会话：需要在较长时间内保持上下文的对话
大型文档分析：对同一文档进行多次不同类型的分析
代码库问答：在较长时间内对同一代码库进行多次查询

混合不同的 TTL

你可以在同一个请求中混合使用不同的缓存持续时间：

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

可以缓存的内容

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

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

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

无法缓存的内容

虽然大多数请求块都可以缓存，但有一些例外：

思考块无法直接使用 cache_control 缓存。但是，当思考块出现在之前的助手回合中时，可以与其他内容一起缓存。以这种方式缓存时，从缓存读取时它们确实计为输入 Token。
子内容块（如引用）本身无法直接缓存。相反，缓存顶级块。
空文本块无法缓存。

跟踪缓存性能

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

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

有效缓存的最佳实践

要优化提示词缓存性能：

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

针对不同用例的优化

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

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

常见问题解决

确保缓存部分在不同调用之间完全相同，并在相同位置标记了 cache_control
检查调用是否在缓存生存期内（5 分钟或 1 小时）
验证 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 倍（5 分钟）或 2 倍（1 小时），缓存 Tokens 读取费用为 0.1 倍，生命周期 5 分钟或 1 小时。文档
Deepseek V3 和 R1 原生支持，缓存费率为常规输入的 1 倍，缓存 Tokens 读取费用为 0.1 倍。文档
Gemini 模型支持隐式缓存：
- 隐式缓存：默认情况下为所有 Gemini 2.5 模型启用。如果你的请求命中缓存，会自动传递成本节省。此功能自 2025 年 5 月 8 日起生效。上下文缓存的最低输入 Token 数：Gemini 2.5 Flash 为 1,024，Gemini 2.5 Pro 为 2,048。
  - 提高隐式缓存命中率的技巧：
    - 将大块的常见内容放在提示的开头。
    - 尝试在短时间内发送前缀相似的请求。
  - 你可以在响应对象的 usage_metadata 字段中查看缓存命中的 Token 数量。
  - 成本节省是根据预填充缓存命中次数衡量的。只有预填充缓存和 YouTube 视频预处理缓存支持隐式缓存。

基础

API

隐私&条款

​提示词缓存的工作原理

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

​缓存定价

​如何实现提示词缓存

​支持的模型

​构建提示词结构

​缓存限制

​1 小时缓存持续时间（Beta）

​何时使用 1 小时缓存

​混合不同的 TTL

​可以缓存的内容

​无法缓存的内容

​跟踪缓存性能

​有效缓存的最佳实践

​针对不同用例的优化

​常见问题解决

​缓存存储和共享

​不同模型的支持情况

提示词缓存的工作原理

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

缓存定价

如何实现提示词缓存

支持的模型

构建提示词结构

缓存限制

1 小时缓存持续时间（Beta）

何时使用 1 小时缓存

混合不同的 TTL

可以缓存的内容

无法缓存的内容

跟踪缓存性能

有效缓存的最佳实践

针对不同用例的优化

常见问题解决

缓存存储和共享

不同模型的支持情况