缓存长前缀

每个长提示词都必须支付预填充成本，在生成之前编码其中的令牌。当相同的长前缀在多次调用中重复出现时——例如系统提示词、工具规范或大型参考文档——提示词缓存可以让提供商复用已经计算出的注意力状态，而不必重新计算。

• 缓存命中可以大幅降低延迟和输入成本。
• 节省的成本会随前缀大小和重复使用频率增加。

缓存依据从提示词开头开始的完全匹配的令牌前缀建立索引。缓存范围从开头延伸到首个分歧点。只要在前面更改任何内容，之后的全部内容都会无法命中缓存。

这意味着，要最大化命中率，布局应将最稳定的内容放在前面，将变化最多的内容放在最后。

请按从最稳定到最不稳定的顺序排列内容：先是不可变的系统规则和工具定义，然后是大型稳定参考材料，接着是会话内稳定的上下文，最后是每次请求中易变的输入和问题。

• 稳定内容 -> 前部（可缓存）。
• 易变内容 -> 后部（唯一需要重新计算的部分）。

这一条排序原则推动了大多数缓存收益。

有些提供商允许您标记明确的缓存断点。请将断点放在每个稳定片段的末尾，使系统能够缓存截至该位置的内容。请将最大的稳定块（参考语料库或较长的系统提示词）标记为可缓存。

即使没有明确的标记，也应按稳定性顺序组织结构，这样隐式的前缀匹配仍然可以发挥作用。

细微且无意的更改会悄悄破坏缓存：系统提示词中的时间戳、提前注入的每次请求标识符、重新排序的工具定义，或非确定性的 JSON 键顺序。每一项都会使前缀发生偏移，并迫使系统进行完整重新计算。

请审查您的前缀，找出调用之间会发生变化的任何内容，并将其移到缓存区域之后。

缓存会在提供商定义的生存时间到期后失效，并且通常会在每次命中时刷新。调用过于稀疏时，冷未命中会反复出现。对于突发的高频工作负载，使用缓存很有价值；对于少量且分散的调用，缓存可能会在两次使用之间过期。

请让流量模式与 TTL 相匹配，并考虑为有价值的前缀发送保活请求。

缓存通常会对写入缓存条目收取少量额外费用，而对读取缓存条目提供大幅折扣。经济性有利于重复使用：一次写入的成本分摊到多次读取上，能够带来显著的净节省；只写入而只使用一次的情况，成本可能会略高。

• 高重复使用率 → 积极缓存。
• 一次性前缀 → 缓存可能不划算。

请让系统提示词和工具规范具有确定性，并固定其版本。请按规范顺序排列工具定义，避免嵌入动态数据，并且只在经过审慎的版本发布中修改它们。稳定的系统区块会成为一个长期存在且高命中的缓存条目，供所有请求共享。

请将缓存前缀视为带有版本的产物，而不是可以随意调整的字符串。

在智能体循环中，不断增长的对话天然就是一种缓存：每一轮都会扩展一个供下一轮重复使用的前缀。请将新轮次追加到尾部，绝不要改写较早的轮次，这样之前的缓存才能保持有效。

必须压缩时，请采用能够为后续轮次创建新稳定前缀的方式，而不是反复修改旧前缀。

请为缓存添加监测。大多数提供商都会报告每次调用中的已缓存输入令牌数和未缓存输入令牌数。请跟踪命中率；如果命中率较低，请检查前缀是否发生漂移。命中率回归通常意味着提示词前部最近引入了动态值。

• 记录 cached_tokens / total_input_tokens。
• 部署后命中率下降时发出警报。

要控制长前缀的成本，请按稳定性排列内容，将最大的稳定区块标记为缓存断点，消除隐藏漂移，固定系统区块和工具区块的版本，在智能体循环中仅追加，并监控命中率。目标是建立一个大型可复用前缀，以及一个每次调用都重新计算的小型易变尾部。

您会在每天数千次查询中重复使用一个包含 100k 个令牌的参考语料库，但缓存命中率却接近于零。

提示词缓存会重复使用精确且稳定前缀的预填充内容，在重复使用频繁时大幅降低延迟和输入成本。请将最稳定的内容放在最前面，把大型稳定区块标记为断点，并将所有易变内容推到尾部。请消除隐藏漂移，固定系统区块和工具区块的版本，在智能体循环中仅追加，并监控命中率，使回归能够标记出新引入的前部变化值。