Claude提示词缓存详解：前缀复用机制与失效场景分析

如果你构建过任何与Claude进行多次交互的应用，例如聊天机器人、编码智能体或文档问答工具，你可能一直在为重复处理相同的文本付费。每个API请求都是无状态的：模型每次都会重新读取你的系统提示词、工具定义以及整个对话历史。提示词缓存正是Anthropic针对这种资源浪费给出的解决方案。它允许API复用先前已处理过的前缀提示词，而无需再次进行计算。

这并非一个不同的模型或新的端点，而是一种将请求的一部分标记为可复用的机制。本文将详细探讨其工作原理、实际成本以及它在何时会悄然失效。

理解缓存架构

缓存条目会覆盖请求的起始部分，一直延伸到你标记的断点处。Anthropic的官方文档指出，前缀是按固定顺序构建的：首先是工具定义，接着是系统提示词，最后是消息历史。从第一个Token一直到断点之间的所有内容共同构成一个可缓存的单元。

这种顺序是整个设计规范的核心。请将极少变动的内容放在最前面，例如你的工具、系统指令、背景文档以及少样本示例；而将每次请求都会改变的内容放在最后。如果易变部分位于缓存前缀内部，那么每次请求的前缀都会不同，从而导致没有任何内容能够被复用。

为了在多模型或自定义管道中高效实现这一点，开发人员通常会选择集成诸如 n1n.ai 这样的API聚合平台，它能够在保留原生API特性的同时，大幅简化流量管理与模型路由。

自动断点与显式断点

自动缓存

自动缓存是最简单的起点：只需在请求的最顶层添加一个单字段 cache_control，系统就会自动将断点放置在最后一个可缓存的块上。随着多轮对话的不断增长，断点会自动向前移动，因此每个新请求都会从缓存中读取先前的对话轮次，并仅写入最新的交互内容。

显式断点

显式断点则能为你提供更精细的控制。你可以将 cache_control 直接放置在单个内容块上，例如在系统提示词之后设置一个断点，在每日更新的大型参考文档之后设置另一个断点。你可以在一个请求中定义最多4个断点，这在长对话超出文档描述的20个块的回溯窗口时非常有用：每个断点都会独立进行向后搜索以查找先前的缓存条目。

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "你是一位资深的软件工程师...",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    }
  ]
}

定价经济学与TTL生命周期

断点本身是免费的。你只需要为缓存写入、缓存读取以及每个请求中的未缓存Token付费。

默认情况下，缓存条目的生存时间为5分钟，读取缓存会免费刷新该生存时间。生命周期是从写入或读取该条目的请求开始计算的，而不是从响应结束时算起。因此，如果一个响应需要4分钟来流式传输，那么后续请求就只有大约1分钟的时间来复用同一前缀。

具体示例：对于Claude Sonnet模型，基础输入为每百万Token 3美元，5分钟缓存写入为3.75美元，1小时写入为6美元，缓存读取则仅需0.30美元。当通过像 n1n.ai 这样的聚合平台扩展高并发应用时，这种读写比将转化为巨大的成本削减优势。

最小Token阈值与缓存失效陷阱

并非所有提示词都符合缓存条件。系统规定了最低可缓存的提示词长度，该长度因模型而异。例如，早期的Sonnet版本需要1,024个Token，而较新的模型如Claude Sonnet 5.5、Opus 5.5和Haiku 5.5则降低至512个Token。如果系统提示词过短，它将悄无声息地永远无法被缓存。

动态内容陷阱

文档中还记录了一种最常见的失败模式：如果将断点放置在一个每次请求都会发生变化的块上，例如包含最新时间戳的消息，那么每次都会产生不同的前缀 hash 值。回溯机制会向后查找先前请求实际写入的条目，由于没有任何先前的请求在更早的位置写入过该条目，因此会直接导致缓存未命中。这意味着你每次请求都要为新鲜的缓存写入付费，却永远享受不到读取优惠。正确的做法是将断点移动到在多次请求间保持完全一致的最后一个块上。

最佳实践检查清单

• 规范请求结构：静态内容在前，变化内容在后。
• 优先使用自动缓存：在没有不同频率变化区间的场景下，使用顶层的 cache_control 字段即可。
• 合理放置显式断点：将其放在每个稳定部分的末尾，绝不要放在包含时间戳或每请求动态数据的块上。
• 验证Token阈值：确保稳定的前缀能够清除模型的最小Token阈值，否则将无法实现任何缓存。
• 应对长对话：如果对话轮次较长，请添加第二个断点，以防止不断增长的对话将最后的缓存写入推出20个块的回溯窗口之外。
• 选择合适的TTL：活跃对话选择5分钟TTL，仅在请求间隙足够长、足以支撑2倍写入价格时才选择1小时TTL。

提示词缓存不会让模型变得更聪明，也不会改变模型的输出结果。它只是阻止了你为第一百次重复阅读相同指令支付全价。结合上述的前缀管理规范，这是生产环境中构建LLM应用时成本效益最高的高级技巧之一。若想进一步优化你的多模型工作流，立即在 n1n.ai 获取免费的API密钥吧。