Prompt Caching 成本指南：缓存命中、前缀与实际 API 支出

Prompt Caching（提示词缓存）的成本取决于三个变量：你的提示词中有多少是可重用的前缀、该前缀在缓存活跃窗口内重复出现的频率，以及特定提供商对缓存写入与缓存命中的定价方式。如果这三个数字把握得当，缓存可以显著降低重复性工作负载的输入 token 账单；如果把握不当，你可能会因为缓存从未被重用而支付额外的写入溢价。

本指南将区分提供商的文档说明、你可以在公共 API 界面验证的内容，以及在将生产环境开销投入到缓存策略之前你应该进行测试的内容。

关键要点

• Prompt Caching 成本包含两个部分：写入成本（通常在创建新的缓存条目时收取）和命中成本（通常在请求重用该条目时收取）。Anthropic 的文档明确描述了这种写入与命中的区别；在建立成本模型之前，你应该在文档页面确认当前的乘数。
• 缓存命中需要精确或近乎精确的前缀匹配，直到定义的断点（breakpoint）。在断点之前重新排序系统指令、工具定义或少样本（few-shot）示例会使缓存失效并强制重新写入。
• 缓存条目在提供商定义的生存时间（TTL）后过期。如果针对特定前缀的请求量过于稀疏，无法落在该窗口内，你将支付重复的写入成本，而不是积累命中节省。
• OpenRouter 的文档指出，Prompt Caching 的行为和定价因底层提供商和模型而异，因此在一个后端上节省成本的缓存策略不会自动转移到另一个后端。在根据预期的节省额路由流量之前，请检查每个模型的支持情况。

Prompt Caching 到底向你收取什么费用

Prompt Caching 允许 API 提供商存储提示词前缀的处理表示，以便后续共享该前缀的请求跳过冗余计算。随之而来的计费模式并不是“缓存的 token 是免费的”。它更接近于“缓存的 token 在重用时更便宜，但首次写入的成本高于标准的输入 token”。

Anthropic 的 Prompt Caching 文档直接列出了这种结构：创建新缓存条目的请求与命中现有缓存条目的请求计费方式不同。确切的乘数会随时间和模型而变化，因此请将你在博客文章（包括本文）中看到的任何数字视为需要根据当前文档进行验证的内容，而不是固定的常量。

实际的含义是，Prompt Caching 是一场关于重用的赌注。如果你的系统提示词、工具模式或检索到的上下文块只发送一次且从不重复，缓存会增加写入溢价，而没有任何抵消的命中节省。如果同一块内容在缓存的活跃窗口内被发送了数百次，命中节省的金额可能会远超写入成本。

缓存命中如何工作：前缀、前缀与断点

缓存命中是基于前缀的，而不是模糊意义上的基于内容。提示词的缓存部分必须与传入的请求在 token 级别上完全匹配，直到设置缓存边界（有时称为断点）的位置。Anthropic 的文档将其描述为一种显式机制，开发人员在此标记提示词的哪一部分符合缓存条件，通常是不会在调用之间更改的稳定系统指令、工具定义和长参考文档。

这有一个直接的工程后果：你在缓存断点之前放置的任何内容在请求之间必须是字节完全一致的，包括空格和顺序。一个常见的错误是将每个请求的变量（如时间戳或用户 ID）插入到缓存边界之前的系统提示词中。那一个变量就会破坏整个前缀的缓存，你每次调用都要支付写入成本，而不是积累命中。

解决方法很简单：将真正静态的内容（工具定义、公司风格指令、大型参考文档）保留在缓存前缀中，并将任何特定于请求的内容推送到未缓存的后缀中，通常是用户消息。

缓存寿命与前缀设计同样重要。Anthropic 的文档描述了以分钟为单位的默认缓存持续时间，并为需要它的工作负载提供了更长持续时间的选项。如果你的流量模式每隔几分钟才发送一次共享前缀，短寿命的缓存可能会在下一个请求到达之前过期，最终你将反复支付写入成本。高频工作负载（聊天会话、智能体循环、连续运行的批处理管道）是比低频、零星调用更好的候选者。

模拟实际 API 开销：一种可行的方法

与其断言节省百分比，不如用以下形式模拟你自己的工作负载。此示例在概念上说明了请求结构；在实施之前，请检查提供商文档中的确切字段名称和当前定价。

{
  "model": "claude-sonnet-5",
  "system": [
    {
      "type": "text",
      "text": "You are a support agent. Full policy document follows...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the refund window for order 48213?" }
  ]
}

系统块上的 cache_control 标记表示此内容是缓存候选对象。会话中的第一次调用支付该块的写入成本。在缓存活跃窗口内重用相同前缀的每次后续调用，支付的是命中率，而不是这些 token 的全额输入费率。

要评估这是否值得为你的服务实施，请从你自己的日志中收集四个数字：

1. 前缀大小：你打算缓存的稳定内容的 token 计数（系统提示词、工具模式、参考文档）。
2. TTL 窗口内的调用频率：在缓存的活跃持续时间内，有多少请求重用了该精确前缀。
3. 写入和命中费率：从当前的提供商文档中获取，而不是凭记忆假设。
4. 后缀可变性：提示词的非缓存部分相对于缓存部分是否较小，因为节省额取决于总提示词中有多少位于缓存断点之后。

如果你的前缀很大，TTL 窗口内的调用频率很高，且后缀很小，缓存很可能会减少开销。如果这三个条件中任何一个较弱，请在广泛推广缓存之前进行并行的成本比较。TokenLab 关于削减 AI API 成本的指南探讨了除缓存之外更广泛的杠杆，包括模型选择和批处理，详见 /blog/cut-ai-api-costs-30-percent。

决策表：Prompt Caching 何时见效

工作负载模式	缓存是否可能有所帮助	备注
在会话中多次调用重用的长系统提示词或工具模式	是	经典案例；写入成本分摊到多次命中中
在短时间内重用的大型检索文档	是，如果调用落在 TTL 内	在假设重用窗口之前，请根据当前文档确认 TTL
没有重复流量的一次性提示词	否	写入溢价且没有命中来抵消它
“稳定”部分不断变化的高可变性提示词	否	断点前的任何变化都会使缓存失效
在多轮对话中重复工具定义的智能体循环	是	工具模式是主要的缓存候选对象
间隔超过缓存 TTL 的低频批处理作业	否	缓存会在重用前过期；每次都支付写入成本
仅部分后端支持缓存的多提供商路由	按模型验证	不要假设缓存支持会在提供商之间转移

将此表用作初步检查清单，而不是最终答案。针对你计划使用的特定模型，根据提供商文档确认 TTL、写入/命中定价和断点机制，因为这些细节会随模型系列而变化。

在投入使用前你应该验证的提供商差异

Prompt Caching 在各处的实现并不完全相同，如果你在多个提供商或模型之间路由流量，这一点很重要。OpenRouter 关于 Prompt Caching 最佳实践的文档指出，缓存支持和行为因底层提供商而异，这意味着针对一个模型缓存机制调整的策略在切换模型或通过不同后端路由时不会自动适用。

如果你的架构使用模型路由来控制成本（例如，将常规分类任务发送到成本较低的模型，如 DeepSeek V4 Flash、GLM-5.2 或 Gemini 3.5 Flash，同时为较难的推理任务保留 Claude Sonnet 5 或 GPT-5.5），你需要为路由表中的每个模型独立检查缓存支持。针对一个模型文档验证的缓存策略对于另一个模型来说不是一个安全的假设。TokenLab 的排名页面跟踪了你可以作为参考起点的模型级差异，详见 /models/rankings，而 /blog/ai-model-routing-benchmark-cost-per-task 上的路由基准分析涵盖了路由决策如何与每任务成本相互作用，这与缓存决策是复合关系，而不是替代关系。

本分析的局限性

本指南描述了 Anthropic 记录并由 OpenRouter 引用的 Prompt Caching 的一般机制（截至上述观察日期）。它不包含确切的写入/命中乘数、确切的 TTL 持续时间或按模型定价，因为这些数字会发生变化且因模型而异。在你为生产流量建立成本模型之前，请直接从上述链接的提供商文档中获取当前数字，而不是依赖第三方内容（包括本文）中引用的任何固定数字。针对推理导向模型、多模态提示词和超长上下文窗口的缓存行为可能也与此处描述的一般前缀缓存模式不同；请针对你计划使用的特定模型查阅文档。

常见问题解答

Prompt Caching 是否总是能减少 API 开销？ 不。只有当稳定的前缀在缓存的活跃窗口内被足够频繁地重用以抵消写入成本时，它才会减少开销。零星或高度可变的提示词在启用缓存时往往比不启用时成本更高。

什么会破坏缓存命中？ 缓存断点之前的提示词内容发生任何变化，包括空格、token 顺序，或插入到原本静态的系统提示词中的单个变量。匹配必须在断点之前完全一致。

所有提供商的 Prompt Caching 实现方式都一样吗？ 不。Anthropic 记录了一种具有明确写入和命中定价的显式缓存控制机制。OpenRouter 的文档指出，缓存支持和定价因底层提供商和模型而异，因此你应该按模型验证支持情况，而不是假设它会自动转移。

如果你正在评估 Prompt Caching、模型路由或两者的组合是否适合你的流量模式，请从 TokenLab 开始，在投入生产开销之前比较模型选项和成本结构。