提示缓存

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

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调用中重复使用这个大文本，而无需每次都重新处理它。仅更改用户消息就可以让您询问关于这本书的各种问题，同时利用缓存的内容，从而获得更快的响应和提高效率。

提示缓存的工作原理

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

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

这对以下情况特别有用：

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

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

如果您发现5分钟太短，Anthropic还提供1小时的缓存持续时间。有关更多信息，请参阅1小时缓存持续时间。

提示缓存缓存完整前缀提示缓存引用整个提示 - tools、system和messages（按此顺序），直到并包括标记为cache_control的块。

定价

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

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output Tokens
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
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 (deprecated)	$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 (deprecated)	$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.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个内容块的内容进行缓存

重要限制：自动前缀检查只会从每个显式断点向后查看大约20个内容块。如果您的提示在缓存断点之前有超过20个内容块，除非您添加额外的断点，否则早于该点的内容不会被检查缓存命中。

缓存限制

最小可缓存提示长度为：

Claude Opus 4.1、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分钟。

理解缓存断点成本

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

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

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

可以缓存的内容

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

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

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

不能缓存的内容

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

思考块不能直接使用cache_control缓存。但是，当思考块出现在之前的助手轮次中时，它们可以与其他内容一起缓存。以这种方式缓存时，它们在从缓存读取时确实算作输入令牌。
子内容块（如引用）本身不能直接缓存。相反，缓存顶级块。在引用的情况下，作为引用源材料的顶级文档内容块可以被缓存。这允许您通过缓存引用将引用的文档来有效地使用提示缓存与引用。
空文本块不能被缓存。

什么会使缓存失效

对缓存内容的修改可能会使部分或全部缓存失效。如构建您的提示中所述，缓存遵循层次结构：tools → system → messages。每个级别的更改都会使该级别和所有后续级别失效。下表显示了不同类型的更改会使缓存的哪些部分失效。✘表示缓存失效，而✓表示缓存保持有效。

更改内容	工具缓存	系统缓存	消息缓存	影响
工具定义	✘	✘	✘	修改工具定义（名称、描述、参数）会使整个缓存失效
网络搜索切换	✓	✘	✘	启用/禁用网络搜索会修改系统提示
引用切换	✓	✘	✘	启用/禁用引用会修改系统提示
工具选择	✓	✓	✘	对`tool_choice`参数的更改只影响消息块
图像	✓	✓	✘	在提示中任何地方添加/删除图像都会影响消息块
思考参数	✓	✓	✘	扩展思考设置的更改（启用/禁用、预算）会影响消息块
传递给扩展思考请求的非工具结果	✓	✓	✘	当在启用扩展思考时传递非工具结果时，所有先前缓存的思考块都会从上下文中剥离，并且上下文中跟随这些思考块的任何消息都会从缓存中删除。有关更多详细信息，请参阅使用思考块缓存。

跟踪缓存性能

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

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

有效缓存的最佳实践

要优化提示缓存性能：

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

针对不同用例的优化

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

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

常见问题故障排除

如果遇到意外行为：

确保缓存部分相同，并在调用之间在相同位置标记cache_control
检查调用是在缓存生命周期内进行的（默认为5分钟）
验证tool_choice和图像使用在调用之间保持一致
验证您至少缓存了最小数量的令牌
系统会自动检查先前内容块边界的缓存命中（直到断点前约20个块）。对于超过20个内容块的提示，您可能需要在提示中更早的位置添加额外的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小时的缓存持续时间。要使用扩展缓存，请在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时，我们确定提示中的三个计费位置：

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

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

您将被收费：

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

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

提示缓存示例

为了帮助您开始使用提示缓存，我们准备了一个提示缓存手册，其中包含详细的示例和最佳实践。下面，我们包含了几个代码片段，展示了各种提示缓存模式。这些示例演示了如何在不同场景中实现缓存，帮助您理解此功能的实际应用：

大型上下文缓存示例

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

此示例演示了基本的提示缓存使用，将法律协议的完整文本作为前缀缓存，同时保持用户指令未缓存。对于第一个请求：

input_tokens：仅用户消息中的令牌数
cache_creation_input_tokens：整个系统消息中的令牌数，包括法律文档
cache_read_input_tokens：0（第一个请求没有缓存命中）

对于缓存生命周期内的后续请求：

input_tokens：仅用户消息中的令牌数
cache_creation_input_tokens：0（没有新的缓存创建）
cache_read_input_tokens：整个缓存系统消息中的令牌数

缓存工具定义

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

在此示例中，我们演示了缓存工具定义。cache_control参数放置在最后一个工具（get_time）上，以将所有工具指定为静态前缀的一部分。这意味着所有工具定义，包括get_weather和在get_time之前定义的任何其他工具，都将作为单个前缀缓存。当您有一组一致的工具，希望在多个请求中重复使用而不每次都重新处理它们时，这种方法很有用。对于第一个请求：

input_tokens：用户消息中的令牌数
cache_creation_input_tokens：所有工具定义和系统提示中的令牌数
cache_read_input_tokens：0（第一个请求没有缓存命中）

对于缓存生命周期内的后续请求：

input_tokens：用户消息中的令牌数
cache_creation_input_tokens：0（没有新的缓存创建）
cache_read_input_tokens：所有缓存工具定义和系统提示中的令牌数

继续多轮对话

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Good to know."
                },
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

在此示例中，我们演示了如何在多轮对话中使用提示缓存。在每一轮中，我们用cache_control标记最后一条消息的最后一个块，以便对话可以增量缓存。系统将自动查找并使用最长的先前缓存前缀进行后续消息。也就是说，先前标记为cache_control块的块后来没有标记为此，但如果它们在5分钟内被命中，它们仍将被视为缓存命中（也是缓存刷新！）。此外，请注意cache_control参数放置在系统消息上。这是为了确保如果这从缓存中被驱逐（在超过5分钟未使用后），它将在下一个请求时被添加回缓存。这种方法对于在持续对话中维护上下文而不重复处理相同信息很有用。当正确设置时，您应该在每个请求的使用响应中看到以下内容：

input_tokens：新用户消息中的令牌数（将是最小的）
cache_creation_input_tokens：新助手和用户轮次中的令牌数
cache_read_input_tokens：对话中直到上一轮的令牌数

综合应用：多个缓存断点

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document ID"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

这个综合示例演示了如何使用所有4个可用的缓存断点来优化提示的不同部分：

工具缓存（缓存断点1）：最后一个工具定义上的cache_control参数缓存所有工具定义。
可重用指令缓存（缓存断点2）：系统提示中的静态指令单独缓存。这些指令在请求之间很少更改。
RAG上下文缓存（缓存断点3）：知识库文档独立缓存，允许您更新RAG文档而不使工具或指令缓存失效。
对话历史缓存（缓存断点4）：助手的响应标记为cache_control，以启用对话随着进展的增量缓存。

这种方法提供了最大的灵活性：

如果您只更新最终用户消息，所有四个缓存段都会被重用
如果您更新RAG文档但保持相同的工具和指令，前两个缓存段会被重用
如果您更改对话但保持相同的工具、指令和文档，前三个段会被重用
每个缓存断点可以根据应用程序中的更改独立失效

对于第一个请求：

input_tokens：最终用户消息中的令牌
cache_creation_input_tokens：所有缓存段中的令牌（工具+指令+RAG文档+对话历史）
cache_read_input_tokens：0（没有缓存命中）

对于仅有新用户消息的后续请求：

input_tokens：仅新用户消息中的令牌
cache_creation_input_tokens：添加到对话历史的任何新令牌
cache_read_input_tokens：所有先前缓存的令牌（工具+指令+RAG文档+先前对话）

这种模式对以下情况特别强大：

具有大型文档上下文的RAG应用程序
使用多个工具的代理系统
需要维护上下文的长时间运行对话
需要独立优化提示不同部分的应用程序

常见问题

我需要多个缓存断点还是末尾一个就足够了？

缓存断点会增加额外成本吗？

缓存的生命周期是多长？

我可以使用多少个缓存断点？

提示缓存是否适用于所有模型？

提示缓存如何与扩展思考配合工作？

如何启用提示缓存？

我可以将提示缓存与其他API功能一起使用吗？

提示缓存如何影响定价？

我可以手动清除缓存吗？

如何跟踪我的缓存策略的有效性？

什么会破坏缓存？

提示缓存如何处理隐私和数据分离？

我可以将提示缓存与批处理API一起使用吗？

为什么我在Python中看到错误`AttributeError: 'Beta' object has no attribute 'prompt_caching'`？

此错误通常在您升级了SDK或使用过时的代码示例时出现。提示缓存现在已普遍可用，因此您不再需要beta前缀。而不是：

python client.beta.prompt_caching.messages.create(...)

只需使用：

python client.messages.create(...)

为什么我看到'TypeError: Cannot read properties of undefined (reading 'messages')'？

此错误通常在您升级了SDK或使用过时的代码示例时出现。提示缓存现在已普遍可用，因此您不再需要beta前缀。而不是：

TypeScript

client.beta.promptCaching.messages.create(...)

只需使用：

client.messages.create(...)

入门步骤

模型与定价

了解 Claude

功能

工具

模型上下文协议 (MCP)

使用案例

提示工程

测试与评估

加强防护措施

法律中心

提示缓存的工作原理

定价

如何实现提示缓存

支持的模型

构建您的提示

自动前缀检查的工作原理

何时使用多个断点

缓存限制

理解缓存断点成本

可以缓存的内容

不能缓存的内容

什么会使缓存失效

跟踪缓存性能

有效缓存的最佳实践

针对不同用例的优化

常见问题故障排除

使用思考块缓存

缓存存储和共享

1小时缓存持续时间

何时使用1小时缓存

混合不同的TTL

提示缓存示例

常见问题

入门步骤

模型与定价

了解 Claude

功能

工具

模型上下文协议 (MCP)

使用案例

提示工程

测试与评估

加强防护措施

法律中心

​提示缓存的工作原理

​定价

​如何实现提示缓存

​支持的模型

​构建您的提示

​自动前缀检查的工作原理

​何时使用多个断点

​缓存限制

​理解缓存断点成本

​可以缓存的内容

​不能缓存的内容

​什么会使缓存失效

​跟踪缓存性能

​有效缓存的最佳实践

​针对不同用例的优化

​常见问题故障排除

​使用思考块缓存

​缓存存储和共享

​1小时缓存持续时间

​何时使用1小时缓存

​混合不同的TTL

​提示缓存示例

​常见问题

提示缓存的工作原理

定价

如何实现提示缓存

支持的模型

构建您的提示

自动前缀检查的工作原理

何时使用多个断点

缓存限制

理解缓存断点成本

可以缓存的内容

不能缓存的内容

什么会使缓存失效

跟踪缓存性能

有效缓存的最佳实践

针对不同用例的优化

常见问题故障排除

使用思考块缓存

缓存存储和共享

1小时缓存持续时间

何时使用1小时缓存

混合不同的TTL

提示缓存示例

常见问题