提示缓存是一项强大的功能，它通过允许从提示中的特定前缀恢复，优化了您的API使用。这种方法显著减少了重复任务或具有一致元素的提示的处理时间和成本。

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

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-20250514",
    "max_tokens": 1024,
    "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"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input
JSON
{"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指定的块。

​
定价

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

ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
Claude Opus 4$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Haiku 3.5$0.80 / MTok$1 / MTok$1.6 / MTok$0.08 / MTok$4 / MTok
Claude Opus 3$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Haiku 3$0.25 / MTok$0.30 / MTok$0.50 / MTok$0.03 / MTok$1.25 / MTok

注意：

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

​
如何实现提示缓存

​
支持的模型

提示缓存目前支持以下模型：

  • 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个令牌
  • Claude Haiku 3.5和Claude Haiku 3为2048个令牌

即使使用cache_control标记，更短的提示也无法缓存。任何请求缓存少于此数量令牌的尝试将在不缓存的情况下处理。要查看提示是否已缓存，请查看响应使用情况字段。

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

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

​
什么可以被缓存

请求中的大多数块都可以使用cache_control指定缓存。这包括：

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

这些元素中的每一个都可以用cache_control标记，以启用对请求该部分的缓存。

​
什么不能被缓存

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

  • 思考块不能直接用cache_control缓存。然而，当思考块出现在之前的助手回合中时，它们可以与其他内容一起缓存。以这种方式缓存时，它们在从缓存读取时确实计入输入令牌。

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

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

  • 空文本块不能被缓存。

​
跟踪缓存性能

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

  • cache_creation_input_tokens：创建新条目时写入缓存的令牌数。
  • cache_read_input_tokens：从缓存中检索到的此请求的令牌数。
  • input_tokens：未从缓存读取或用于创建缓存的输入令牌数。

​
有效缓存的最佳实践

要优化提示缓存性能：

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

​
针对不同用例的优化

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

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

​
常见问题的故障排除

如果遇到意外行为：

  • 确保缓存部分在调用之间完全相同，并在相同位置使用cache_control标记
  • 检查调用是否在缓存生命周期内（默认为5分钟）
  • 验证tool_choice和图像使用在调用之间保持一致
  • 验证您至少缓存了最小数量的令牌
  • 虽然系统将尝试使用缓存断点之前位置的先前缓存内容，但您可以使用额外的cache_control参数来保证对提示先前部分的缓存查找，这对于具有非常长内容块列表的查询可能很有用

请注意，更改tool_choice或提示中任何位置的图像存在/不存在将使缓存无效，需要创建新的缓存条目。

​
使用思考块进行缓存

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

与其他内容一起自动缓存：虽然思考块不能显式标记为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%相同的提示段，包括标记为缓存控制的块之前和包括该块的所有文本和图像。

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

​
1小时缓存持续时间（测试版）

如果您发现5分钟太短，Anthropic还提供1小时的缓存持续时间。

要使用扩展缓存，请将extended-cache-ttl-2025-04-11作为测试版标头添加到您的请求中，然后在cache_control定义中包含ttl，如下所示：

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

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

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "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分钟后发送时。
  • 当您想要改善速率限制利用率时，因为缓存命中不会计入您的速率限制。

5分钟和1小时缓存在延迟方面表现相同。对于长文档，您通常会看到首个令牌的时间有所改善。

​
混合不同的TTL

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

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

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

如果B和/或C大于A，它们必然是缓存未命中，因为A是最高缓存命中。

您将被收取以下费用：

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

以下是3个示例。这描述了3个请求的输入令牌，每个请求都有不同的缓存命中和缓存未命中。每个都有不同的计算定价，如彩色框所示，作为结果。

​
提示缓存示例

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

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

​
常见问题