提示词缓存（测试版）

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

以下是使用 Messages API 实现提示词缓存的示例，使用 cache_control 块：

在这个示例中，《傲慢与偏见》的全部文本使用 cache_control 参数进行缓存。这使得这段大文本可以在多个 API 调用中重复使用，而无需每次都重新处理。只更改用户消息就可以让您询问关于这本书的各种问题，同时利用缓存的内容，从而获得更快的响应和提高效率。

​

提示词缓存的工作原理

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

1. 系统检查提示词前缀是否已从最近的查询中缓存。
2. 如果找到，它会使用缓存版本，减少处理时间和成本。
3. 否则，它会处理完整的提示词并缓存前缀以供将来使用。

这对以下情况特别有用：

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

缓存的生命周期为 5 分钟，每次使用缓存内容时都会刷新。

​

定价

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

注意：

• 缓存写入令牌比基础输入令牌贵 25%
• 缓存读取令牌比基础输入令牌便宜 90%
• 常规输入和输出令牌按标准费率定价

​

如何实现提示词缓存

​

支持的模型

提示词缓存目前支持：

• Claude 3.5 Sonnet
• Claude 3 Haiku
• Claude 3 Opus

​

构建您的提示词

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

缓存前缀按以下顺序创建：tools、system，然后是 messages。

使用 cache_control 参数，您可以定义最多 4 个缓存断点，允许您分别缓存不同的可重用部分。

​

缓存限制

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

• Claude 3.5 Sonnet 和 Claude 3 Opus 为 1024 个令牌
• Claude 3 Haiku 为 2048 个令牌

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

缓存的生存时间 (TTL) 为 5 分钟。目前，“ephemeral” 是唯一支持的缓存类型，对应于这个 5 分钟的生命周期。

​

可以缓存的内容

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

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

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

​

跟踪缓存性能

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

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

​

有效缓存的最佳实践

要优化提示词缓存性能：

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

​

针对不同用例的优化

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

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

​

常见问题故障排除

如果遇到意外行为：

• 确保缓存部分在调用之间完全相同，并在相同位置标记了 cache_control
• 检查调用是否在 5 分钟的缓存生命周期内进行
• 验证 tool_choice 和图像使用在调用之间保持一致
• 验证您至少缓存了最小数量的令牌

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

​

缓存存储和共享

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

• 精确匹配：缓存命中需要 100% 相同的提示词段，包括标记有缓存控制的块中及之前的所有文本和图像。在缓存读取和创建期间，必须用 cache_control 标记相同的块。

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

​

提示词缓存示例

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

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

​

常见问题