提示词缓存

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

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

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

最简单的开始方式是使用自动缓存：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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'.",
        }
    ],
)
print(response.usage.model_dump_json())

使用自动缓存，系统缓存所有内容直到并包括最后一个可缓存块。在后续请求中使用相同前缀时，缓存的内容会自动重用。

提示词缓存如何工作

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

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

这对以下情况特别有用：

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

默认情况下，缓存的生命周期为 5 分钟。每次使用缓存的内容时，缓存都会刷新，无需额外成本。

定价

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

支持的模型

提示词缓存（自动和显式）在所有 活跃 Claude 模型 上受支持。

自动缓存

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

自动缓存在多轮对话中的工作原理

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

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

TTL 支持

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

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

与块级缓存结合

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

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

{
  "model": "claude-opus-4-7",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

保持不变的内容

自动缓存使用相同的底层缓存基础设施。定价、最小令牌阈值、上下文排序要求和 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 个块。 系统每个断点最多检查 20 个位置，将断点本身计为第一个。如果系统在该窗口中找不到匹配的条目，检查停止（或从下一个显式断点恢复，如果有的话）。

示例：在不断增长的对话中回溯

您在每个轮次追加新块，并在每个请求的最后一个块上设置 cache_control：

• 轮次 1： 10 个块，断点在块 10。不存在先前的缓存条目。系统在块 10 处写入条目。
• 轮次 2： 15 个块，断点在块 15。块 15 没有条目，所以系统向后走到块 10 并找到轮次 1 的条目。在块 10 处缓存命中；系统仅新鲜处理块 11 到 15，并在块 15 处写入新条目。
• 轮次 3： 35 个块，断点在块 35。系统检查 20 个位置（块 35 到 16）并找不到任何内容。轮次 2 在块 15 处的条目在窗口外一个位置，所以没有缓存命中。添加第二个断点在块 15 处启动第二个回溯窗口，该窗口找到轮次 2 的条目。

常见错误：断点在每个请求都变化的内容上

您的提示词有大量静态系统上下文（块 1 到 5），后跟包含时间戳和用户消息的每个请求块（块 6）。您在块 6 上设置 cache_control：

• 请求 1： 在块 6 处缓存写入。哈希包括时间戳。
• 请求 2： 时间戳不同，所以块 6 处的前缀哈希不同。回溯走过块 5、4、3、2 和 1，但系统从未在任何这些位置写入条目。没有缓存命中。您在每个请求上支付新的缓存写入，永远不会获得读取。

回溯不会找到您的断点后面的稳定内容并缓存它。它找到先前请求已写入的条目，而写入仅在断点处发生。将 cache_control 移到块 5，即跨请求保持相同的最后一个块，每个后续请求都会读取缓存的前缀。自动缓存 陷入同样的陷阱：它将断点放在最后一个可缓存块上，在这个结构中是每个请求都变化的块，所以改为使用块 5 上的显式断点。

关键要点： 在最后一个块上放置 cache_control，其前缀在您想要共享缓存的请求中是相同的。在不断增长的对话中，只要每个轮次添加少于 20 个块，最后一个块就可以工作：较早的内容永远不会改变，所以下一个请求的回溯找到先前的写入。对于具有变化后缀的提示词（时间戳、每个请求的上下文、传入消息），将断点放在静态前缀的末尾，而不是在变化块上。

何时使用多个断点

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

• 缓存以不同频率变化的不同部分（例如，工具很少变化，但上下文每天更新）
• 对缓存的内容有更多控制
• 当不断增长的对话将您的断点推过最后一次缓存写入 20 个或更多块时，确保缓存命中

理解缓存断点成本

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

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

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

缓存策略和注意事项

缓存限制

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

• 4096 令牌用于 Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Opus 4.5
• 2048 令牌用于 Claude Sonnet 4.6
• 1024 令牌用于 Claude Sonnet 4.5、Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4 和 Claude Sonnet 3.7 (已弃用)
• 4096 令牌用于 Claude Haiku 4.5
• 2048 令牌用于 Claude Haiku 3.5 (已弃用) 和 Claude Haiku 3

较短的提示词无法缓存，即使用 cache_control 标记也是如此。任何缓存少于此令牌数的请求将在没有缓存的情况下处理，不会返回错误。要验证提示词是否被缓存，请检查响应使用 字段：如果 cache_creation_input_tokens 和 cache_read_input_tokens 都为 0，则提示词未被缓存（可能是因为它未满足最小长度要求）。

如果您的提示词略低于您使用的模型的最小值，扩展缓存的内容以达到阈值通常是值得的。缓存读取的成本远低于未缓存的输入令牌，因此达到最小值可以降低频繁重用的提示词的成本。

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

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

可以缓存的内容

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

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

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

无法缓存的内容

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

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

• 子内容块（如 引用）本身无法直接缓存。相反，缓存顶级块。

  在引用的情况下，作为引用源材料的顶级文档内容块可以被缓存。这允许您通过缓存引用将引用的文档来有效地使用带有引用的提示词缓存。

• 空文本块无法缓存。

什么使缓存失效

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

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

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

跟踪缓存性能

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

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

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

使用思考块进行缓存

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

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

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

缓存失效模式：

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

有关缓存失效的更多详情，请参阅什么会使缓存失效。

工具使用示例：

请求 1：用户："巴黎的天气如何？"
响应：[thinking_block_1] + [tool_use block 1]

请求 2：
用户：["巴黎的天气如何？"],
助手：[thinking_block_1] + [tool_use block 1],
用户：[tool_result_1, cache=True]
响应：[thinking_block_2] + [text block 2]
# 请求 2 缓存其请求内容（不是响应）
# 缓存包括：用户消息、thinking_block_1、tool_use block 1 和 tool_result_1

请求 3：
用户：["巴黎的天气如何？"],
助手：[thinking_block_1] + [tool_use block 1],
用户：[tool_result_1, cache=True],
助手：[thinking_block_2] + [text block 2],
用户：[文本响应, cache=True]
# 非工具结果用户块导致所有思考块被忽略
# 此请求的处理方式就像思考块从未存在过一样

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

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

缓存存储和共享

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

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

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

有效缓存的最佳实践

为了优化提示缓存性能：

• 从自动缓存开始进行多轮对话。它会自动处理断点管理。
• 当您需要使用不同的更改频率缓存不同的部分时，使用显式块级断点。
• 缓存稳定的、可重用的内容，如系统指令、背景信息、大型上下文或频繁的工具定义。
• 将缓存内容放在提示的开头以获得最佳性能。
• 策略性地使用缓存断点来分离不同的可缓存前缀部分。
• 将断点放在跨请求保持相同的最后一个块上。对于具有静态前缀和变化后缀（时间戳、每个请求的上下文、传入消息）的提示，那就是前缀的末尾，而不是变化的块。
• 定期分析缓存命中率并根据需要调整您的策略。

针对不同用例进行优化

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

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

故障排除常见问题

如果遇到意外行为：

• 确保缓存的部分在调用中相同。对于显式断点，验证 cache_control 标记位于相同位置
• 检查调用是否在缓存生命周期内进行（默认为 5 分钟）
• 验证 tool_choice 和图像使用在调用之间保持一致
• 验证您正在缓存至少您正在使用的模型的最小令牌数（请参阅缓存限制）。基于长度的缓存失败是无声的：请求成功，但 cache_creation_input_tokens 和 cache_read_input_tokens 都将为 0
• 确认您的断点位于跨请求保持相同的块上。缓存写入仅在断点处发生，如果该块更改（时间戳、每个请求的上下文、传入消息），前缀哈希永远不会匹配。回溯不会在断点后面找到稳定内容；它只会找到早期请求在其自己的断点处写入的条目
• 验证您的 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 时，API 在您的提示中确定三个计费位置：

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

您将被收费：

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

这里有 3 个示例。这描绘了 3 个请求的输入令牌，每个请求都有不同的缓存命中和缓存未命中。每个都有不同的计算定价，如彩色框所示。

提示词缓存示例

为了帮助您开始使用提示词缓存，提示词缓存食谱提供了详细的示例和最佳实践。

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

数据保留

提示词缓存（自动和显式）符合 ZDR 资格。Anthropic 不存储您的提示词或 Claude 响应的原始文本。

KV（键值）缓存表示和缓存内容的加密哈希仅保存在内存中，不存储在磁盘上。缓存条目的最短生命周期为 5 分钟（标准）或 60 分钟（扩展），之后它们会被迅速（但不是立即）删除。缓存条目在组织之间是隔离的。

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

常见问题

这对于理解成本和速率限制都很重要，因为在有效使用缓存时，input_tokens 通常会比您的总输入小得多。