提示词缓存

提示词缓存通过允许从提示词中的特定前缀恢复来优化您的 API 使用。这显著减少了重复任务或具有一致元素的提示词的处理时间和成本。

启用提示词缓存有两种方式：

• 自动缓存：在请求的顶层添加一个 cache_control 字段。系统自动将缓存断点应用于最后一个可缓存块，并随着对话增长向前移动。最适合需要自动缓存不断增长的消息历史的多轮对话。
• 显式缓存断点：将 cache_control 直接放置在各个内容块上，以精细控制缓存的具体内容。

最简单的入门方式是使用自动缓存：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

使用自动缓存时，系统会缓存直到最后一个可缓存块（含）的所有内容。在后续具有相同前缀的请求中，缓存内容会被自动复用。

提示词缓存的工作原理

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

1. 系统检查提示词前缀（直到指定的缓存断点）是否已从最近的查询中缓存。
2. 如果找到，则使用缓存版本，减少处理时间和成本。
3. 否则，处理完整提示词，并在响应开始后缓存前缀。

这对以下情况特别有用：

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

默认情况下，缓存的生命周期为 5 分钟。每次使用缓存内容时，缓存都会免费刷新。

定价

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

支持的模型

提示词缓存（自动和显式）目前支持以下模型：

• Claude Opus 4.6
• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.6
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7（已弃用）
• Claude Haiku 4.5
• Claude Haiku 3.5（已弃用）
• Claude Haiku 3

自动缓存

自动缓存是启用提示词缓存的最简单方式。无需在各个内容块上放置 cache_control，只需在请求体的顶层添加一个 cache_control 字段。系统会自动将缓存断点应用于最后一个可缓存块。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are a helpful assistant that remembers our conversation.",
    "messages": [
      {"role": "user", "content": "My name is Alex. I work on machine learning."},
      {"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},
      {"role": "user", "content": "What did I say I work on?"}
    ]
  }'

自动缓存在多轮对话中的工作方式

使用自动缓存时，缓存点会随着对话增长自动向前移动。每个新请求都会缓存直到最后一个可缓存块的所有内容，之前的内容则从缓存中读取。

缓存断点会自动移动到每个请求中最后一个可缓存块，因此您无需随着对话增长更新任何 cache_control 标记。

TTL 支持

默认情况下，自动缓存使用 5 分钟的 TTL。您可以以基础输入 token 价格的 2 倍指定 1 小时的 TTL：

"cache_control": {"type": "ephemeral", "ttl": "1h"}

与块级缓存结合使用

自动缓存与显式缓存断点兼容。当两者一起使用时，自动缓存断点会占用 4 个可用断点槽中的一个。

这允许您结合两种方式。例如，使用显式断点独立缓存系统提示词和工具，同时自动缓存处理对话：

{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [...]
}

保持不变的内容

自动缓存使用相同的底层缓存基础设施。定价、最小 token 阈值、上下文排序要求以及 20 块回溯窗口的应用方式与显式断点相同。

边缘情况

• 如果最后一个块已经有具有相同 TTL 的显式 cache_control，则自动缓存为空操作。
• 如果最后一个块有具有不同 TTL 的显式 cache_control，API 将返回 400 错误。
• 如果已存在 4 个显式块级断点，API 将返回 400 错误（没有剩余槽位用于自动缓存）。
• 如果最后一个块不符合自动缓存断点目标的条件，系统会静默地向后查找最近的符合条件的块。如果未找到，则跳过缓存。

显式缓存断点

为了更精细地控制缓存，您可以将 cache_control 直接放置在各个内容块上。当您需要以不同频率缓存不同部分，或需要精细控制缓存的具体内容时，这非常有用。

构建提示词结构

将静态内容（工具定义、系统指令、上下文、示例）放在提示词的开头。使用 cache_control 参数标记可重用内容的结尾以进行缓存。

缓存前缀按以下顺序创建：tools、system，然后是 messages。此顺序形成一个层次结构，每个级别都建立在前一个级别之上。

自动前缀检查的工作原理

您可以在静态内容末尾只使用一个缓存断点，系统将自动找到最长的匹配缓存块序列。了解其工作原理有助于优化您的缓存策略。

三个核心原则：

1. 缓存键是累积的：当您使用 cache_control 显式缓存一个块时，缓存哈希键是通过按顺序哈希对话中所有前面的块生成的。这意味着每个块的缓存取决于其之前的所有内容。

2. 向后顺序检查：系统通过从您的显式断点向后工作来检查缓存命中，按逆序检查每个前面的块。这确保您获得尽可能长的缓存命中。

3. 20 块回溯窗口：系统只检查每个显式 cache_control 断点之前最多 20 个块。在检查 20 个块未找到匹配后，它停止检查并移动到下一个显式断点（如果有）。

示例：理解回溯窗口

考虑一个有 30 个内容块的对话，您只在第 30 块设置 cache_control：

• 如果您发送第 31 块且之前的块没有变化：系统检查第 30 块（匹配！）。您在第 30 块获得缓存命中，只有第 31 块需要处理。

• 如果您修改第 25 块并发送第 31 块：系统从第 30 块向后检查 → 29 → 28... → 25（不匹配）→ 24（匹配！）。由于第 24 块没有变化，您在第 24 块获得缓存命中，只有第 25-30 块需要重新处理。

• 如果您修改第 5 块并发送第 31 块：系统从第 30 块向后检查 → 29 → 28... → 11（第 20 次检查）。在 20 次检查未找到匹配后，停止查找。由于第 5 块超出了 20 块窗口，没有缓存命中，所有块都需要重新处理。但是，如果您在第 5 块设置了显式 cache_control 断点，系统将从该断点继续检查：第 5 块（不匹配）→ 第 4 块（匹配！）。这允许在第 4 块获得缓存命中，说明了为什么应该在可编辑内容之前放置断点。

关键要点：始终在对话末尾设置显式缓存断点，以最大化缓存命中的机会。此外，在可能被编辑的内容块之前设置断点，以确保这些部分可以独立缓存。

何时使用多个断点

如果您想要以下功能，可以定义最多 4 个缓存断点：

• 以不同频率缓存不同部分（例如，工具很少更改，但上下文每天更新）
• 更精细地控制缓存的具体内容
• 确保缓存最终断点之前超过 20 块的内容
• 在可编辑内容之前放置断点，以保证即使在 20 块窗口之外发生更改时也能命中缓存

理解缓存断点成本

缓存断点本身不增加任何成本。 您只需为以下内容付费：

• 缓存写入：当新内容写入缓存时（5 分钟 TTL 比基础输入 token 多 25%）
• 缓存读取：当使用缓存内容时（基础输入 token 价格的 10%）
• 常规输入 token：对于任何未缓存的内容

添加更多 cache_control 断点不会增加您的成本——您仍然根据实际缓存和读取的内容支付相同金额。断点只是让您控制哪些部分可以独立缓存。

缓存策略和注意事项

缓存限制

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

• Claude Opus 4.6、Claude Opus 4.5 为 4096 个 token
• Claude Sonnet 4.6 为 2048 个 token
• Claude Sonnet 4.5、Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4 和 Claude Sonnet 3.7（已弃用）为 1024 个 token
• Claude Haiku 4.5 为 4096 个 token
• Claude Haiku 3.5（已弃用）和 Claude Haiku 3 为 2048 个 token

较短的提示词无法被缓存，即使标有 cache_control。任何缓存少于此数量 token 的请求都将在不缓存的情况下处理。要查看提示词是否被缓存，请参阅响应使用字段。

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

目前，"ephemeral" 是唯一支持的缓存类型，默认生命周期为 5 分钟。

可以缓存的内容

请求中的大多数块都可以被缓存。这包括：

• 工具：tools 数组中的工具定义
• 系统消息：system 数组中的内容块
• 文本消息：messages.content 数组中的内容块，适用于用户和助手轮次
• 图像和文档：messages.content 数组中的内容块，在用户轮次中
• 工具使用和工具结果：messages.content 数组中的内容块，在用户和助手轮次中

这些元素中的每一个都可以被缓存，无论是自动缓存还是通过标记 cache_control。

不能缓存的内容

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

• 思考块不能直接用 cache_control 缓存。但是，当思考块出现在之前的助手轮次中时，它们可以与其他内容一起被缓存。以这种方式缓存时，从缓存读取时它们确实计为输入 token。

• 子内容块（如引用）本身不能直接缓存。应缓存顶层块。

  对于引用，作为引用来源材料的顶层文档内容块可以被缓存。这允许您通过缓存引用将引用的文档与提示词缓存有效结合使用。

• 空文本块不能被缓存。

使缓存失效的内容

对缓存内容的修改可能会使部分或全部缓存失效。

如构建提示词结构中所述，缓存遵循以下层次结构：tools → system → messages。每个级别的更改会使该级别及所有后续级别失效。

下表显示了不同类型的更改会使缓存的哪些部分失效。✘ 表示缓存失效，✓ 表示缓存保持有效。

跟踪缓存性能

使用响应中 usage 内的以下 API 响应字段监控缓存性能（如果流式传输，则在 message_start 事件中）：

• cache_creation_input_tokens：创建新条目时写入缓存的 token 数量。
• cache_read_input_tokens：此请求从缓存中检索的 token 数量。
• input_tokens：未从缓存读取或用于创建缓存的输入 token 数量（即最后一个缓存断点之后的 token）。

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

使用思考块进行缓存

当将扩展思考与提示词缓存一起使用时，思考块具有特殊行为：

与其他内容一起自动缓存：虽然思考块不能显式标记 cache_control，但当您使用工具结果进行后续 API 调用时，它们会作为请求内容的一部分被缓存。这通常发生在工具使用期间，当您传回思考块以继续对话时。

输入 token 计数：当思考块从缓存读取时，它们在您的使用指标中计为输入 token。这对于成本计算和 token 预算很重要。

缓存失效模式：

• 仅提供工具结果作为用户消息时，缓存保持有效
• 添加非工具结果用户内容时，缓存失效，导致所有之前的思考块被剥离
• 即使没有显式 cache_control 标记，也会发生此缓存行为

有关缓存失效的更多详情，请参阅使缓存失效的内容。

工具使用示例：

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

当包含非工具结果用户块时，它指定了一个新的助手循环，所有之前的思考块都从上下文中删除。

有关更详细的信息，请参阅扩展思考文档。

缓存存储和共享

• 组织隔离：缓存在组织之间是隔离的。不同的组织永远不会共享缓存，即使它们使用相同的提示词。

• 精确匹配：缓存命中需要 100% 相同的提示词段，包括直到并包含标有缓存控制的块的所有文本和图像。

• 输出 token 生成：提示词缓存对输出 token 生成没有影响。您收到的响应与不使用提示词缓存时完全相同。

有效缓存的最佳实践

为优化提示词缓存性能：

• 对于多轮对话，从自动缓存开始。它会自动处理断点管理。
• 当您需要以不同变化频率缓存不同部分时，使用显式块级断点。
• 缓存稳定的、可重用的内容，如系统指令、背景信息、大型上下文或频繁使用的工具定义。
• 将缓存内容放在提示词开头以获得最佳性能。
• 策略性地使用缓存断点来分隔不同的可缓存前缀部分。
• 在对话末尾和可编辑内容之前设置缓存断点，以最大化缓存命中率，特别是在处理超过 20 个内容块的提示词时。
• 定期分析缓存命中率并根据需要调整策略。

针对不同用例的优化

根据您的场景定制提示词缓存策略：

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

常见问题排查

如果遇到意外行为：

• 确保缓存部分在各次调用中完全相同。对于显式断点，验证 cache_control 标记位于相同位置
• 检查调用是否在缓存生命周期内进行（默认为 5 分钟）
• 验证 tool_choice 和图像使用在各次调用之间保持一致
• 验证您缓存的 token 数量至少达到最小值
• 系统自动检查之前内容块边界处的缓存命中（断点之前最多约 20 个块）。对于超过 20 个内容块的提示词，您可能需要在提示词早期添加额外的 cache_control 参数，以确保所有内容都可以被缓存
• 验证您的 tool_use 内容块中的键具有稳定的排序，因为某些语言（例如 Swift、Go）在 JSON 转换期间会随机化键顺序，从而破坏缓存

1 小时缓存时长

如果您发现 5 分钟太短，Anthropic 还提供 1 小时的缓存时长，需额外付费。

要使用扩展缓存，请在 cache_control 定义中包含 ttl，如下所示：

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

响应将包含如下详细的缓存信息：

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 456,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

请注意，当前的 cache_creation_input_tokens 字段等于 cache_creation 对象中值的总和。

何时使用 1 小时缓存

如果您的提示词以固定频率使用（即系统提示词使用频率超过每 5 分钟一次），请继续使用 5 分钟缓存，因为这将继续免费刷新。

1 小时缓存最适合以下场景：

• 当您的提示词使用频率可能低于每 5 分钟一次，但高于每小时一次时。例如，当代理子代理需要超过 5 分钟时，或者存储与用户的长聊天对话且您通常预期该用户可能在接下来的 5 分钟内不会回复时。
• 当延迟很重要且您的后续提示词可能在 5 分钟后发送时。
• 当您想提高速率限制利用率时，因为缓存命中不会从您的速率限制中扣除。

混合不同的 TTL

您可以在同一请求中同时使用 1 小时和 5 分钟缓存控制，但有一个重要约束：具有较长 TTL 的缓存条目必须出现在较短 TTL 之前（即 1 小时缓存条目必须出现在任何 5 分钟缓存条目之前）。

混合 TTL 时，我们在提示词中确定三个计费位置：

1. 位置 A：最高缓存命中处的 token 计数（如果没有命中则为 0）。
2. 位置 B：A 之后最高 1 小时 cache_control 块处的 token 计数（如果不存在则等于 A）。
3. 位置 C：最后一个 cache_control 块处的 token 计数。

您将为以下内容付费：

1. A 的缓存读取 token。
2. (B - A) 的 1 小时缓存写入 token。
3. (C - B) 的 5 分钟缓存写入 token。

以下是 3 个示例。这描述了 3 个请求的输入 token，每个请求具有不同的缓存命中和缓存未命中。由于结果不同，每个请求的计算定价也不同，如彩色框所示。

提示缓存示例

为了帮助您开始使用提示缓存，我们准备了一个提示缓存使用手册，其中包含详细示例和最佳实践。

以下是几个展示各种提示缓存模式的代码片段。这些示例演示了如何在不同场景中实现缓存，帮助您了解此功能的实际应用：

数据保留

提示缓存存储 KV（键值）缓存表示和缓存内容的加密哈希值，但不存储提示或响应的原始文本。缓存条目的最短生命周期为 5 分钟（标准）或 60 分钟（扩展）。缓存条目在组织之间相互隔离。由于 Anthropic 不存储原始提示或响应文本，此功能可能适合需要 ZDR 类型数据保留承诺的客户。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

常见问题