提示缓存

提示缓存是一个强大的功能，通过允许从提示中的特定前缀恢复来优化您的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-1-20250805",
    "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

{"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分钟。每次使用缓存内容时，缓存都会免费刷新。

​

定价

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

​

如何实现提示缓存

​

支持的模型

提示缓存目前支持：

• Claude Opus 4.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断点时，系统会自动检查所有先前内容块边界（直到您显式断点前大约20个块）的缓存命中
• 如果这些先前位置中的任何一个与早期请求的缓存内容匹配，系统使用最长的匹配前缀
• 这意味着您不需要多个断点来启用缓存 - 末尾的一个就足够了

​

何时使用多个断点

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

• 缓存以不同频率变化的不同部分（例如，工具很少变化，但上下文每天更新）
• 对确切缓存的内容有更多控制
• 确保对最终断点前超过20个内容块的内容进行缓存

​

缓存限制

最小可缓存提示长度为：

• 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分钟。

​

理解缓存断点成本

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

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

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

​

可以缓存的内容

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

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

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

​

不能缓存的内容

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

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

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

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

• 空文本块不能被缓存。

​

什么会使缓存失效

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

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

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

​

跟踪缓存性能

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

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

​

有效缓存的最佳实践

要优化提示缓存性能：

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

​

针对不同用例的优化

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

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

​

常见问题故障排除

如果遇到意外行为：

• 确保缓存部分完全相同，并在调用之间在相同位置标有cache_control
• 检查调用是在缓存生命周期内进行的（默认为5分钟）
• 验证tool_choice和图像使用在调用之间保持一致
• 验证您至少缓存了最小数量的token
• 系统会自动检查先前内容块边界的缓存命中（直到断点前约20个块）。对于超过20个内容块的提示，您可能需要在提示中较早的位置添加额外的cache_control参数，以确保所有内容都可以被缓存

​

使用思考块进行缓存

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

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

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

缓存失效模式：

• 当仅提供工具结果作为用户消息时，缓存保持有效
• 当添加非工具结果用户内容时，缓存失效，导致所有先前的思考块被剥离
• 即使没有显式的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%相同的提示段，包括所有文本和图像，直到并包括标有缓存控制的块。

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

​

1小时缓存持续时间

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

要使用扩展缓存，请在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分钟后发送时。
• 当您想要改善速率限制利用率时，因为缓存命中不会从您的速率限制中扣除。

​

混合不同的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，每个请求都有不同的缓存命中和缓存未命中。每个都有不同的计算定价，显示在彩色框中，作为结果。

​

提示缓存示例

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

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

​

常见问题