缓存与长上下文优化

当请求中包含稳定且会反复使用的长上下文时，可以使用模型缓存能力降低成本并改善响应速度。典型内容包括系统提示词、工具定义、产品知识库、长文档、代码库片段、固定示例集和多轮对话历史。

适用场景

• 多轮对话中反复引用同一份长文档。
• 批量处理多个问题，但背景材料相同。
• 客服、知识库、代码审查等需要固定系统提示词和规则的场景。
• Agent 或工具调用场景中，工具定义、系统规则和安全边界较长且稳定。
• 长上下文分析任务，希望降低重复输入成本并缩短首 token 延迟。

两类缓存方式

自动缓存更适合先快速接入；主动缓存更适合你已经明确知道哪些内容会被复用，并希望更精确控制缓存边界的场景。

缓存前缀如何组织

缓存通常依赖“稳定前缀”。前缀越稳定，越容易命中缓存；越靠后的动态内容，越不应该放入缓存范围。

推荐顺序：

工具定义 / 可用能力说明
系统提示词 / 安全规则 / 输出约束
固定背景材料 / 长文档 / 示例集
历史对话中稳定可复用的部分
本次用户问题 / 实时数据 / 临时上下文

在支持工具调用和 Anthropic 兼容主动缓存的场景中，常见的前缀层次是：

tools -> system -> messages

这意味着：工具定义变化可能影响工具、系统消息和历史消息的缓存；系统提示词变化可能影响系统消息和后续消息的缓存；用户问题如果每次都变化，通常应放在最后。

自动 Prompt 缓存

自动缓存不要求你显式传入缓存参数。只要多次请求的前缀足够长且完全一致，模型服务就有机会复用已处理的输入内容。很多 OpenAI 兼容缓存实现通常需要至少约 1024 个输入 token 的稳定共享前缀，低于阈值时即使内容重复也可能看不到缓存命中；具体阈值以目标模型能力说明为准。

适合自动缓存的内容：

• 固定系统提示词。
• 长文档、合同、规范、代码片段。
• 少样本示例和输出格式说明。
• 一组固定工具说明或业务规则。
• 多轮对话中反复出现的长历史。

不利于自动缓存的写法：

• 每次请求都在系统提示词中插入时间、随机 ID 或用户昵称。
• 把用户当次问题放在长文档前面。
• 对固定提示词做无意义的空格、换行或顺序调整。
• 每次请求都重新拼接不同顺序的工具定义。

Anthropic 兼容主动缓存

如果你使用的目标模型和接入协议支持 Anthropic 兼容主动缓存，可以在可复用内容的末尾设置缓存断点。这样可以明确告诉模型服务：断点之前的内容适合缓存，断点之后的内容通常是本次请求的动态部分。

示例结构如下，仅用于说明放置方式：

{
  "system": [
    {
      "type": "text",
      "text": "你是一个企业知识库助手，需要基于给定资料回答问题。"
    },
    {
      "type": "text",
      "text": "这里放置较长且稳定的知识库资料、规则或文档内容。",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "本次用户问题放在缓存断点之后。"
    }
  ]
}

也可以把缓存断点放在固定工具列表的最后一个工具、长系统提示词末尾，或多轮对话中已经稳定的最后一个内容块之后。具体支持位置和数量限制以目标模型能力为准。

命中与失效

缓存命中通常要求缓存范围内的内容保持一致。以下变化可能导致部分或全部缓存失效：

• 修改工具定义、工具顺序或工具参数说明。
• 修改系统提示词、安全规则或输出格式说明。
• 修改长文档内容、顺序或分块方式。
• 在缓存前缀中加入每次都会变化的时间、会话 ID、用户输入或实时数据。
• 超过目标模型的缓存有效期后再次调用。
• 内容块过多但缓存断点设置不合理，导致服务无法回溯到期望的稳定前缀。

如果要最大化命中率，应把稳定内容放前面，把动态内容放最后，并尽量让批量任务集中在缓存有效期内完成。

用量观测

接入后可以从模型响应或控制台用量明细中查看缓存相关 Token，再结合命中率、延迟和成本变化判断是否适合继续使用缓存。

OpenAI 兼容调用中，常见的缓存观测字段包括：

usage.prompt_tokens_details.cached_tokens
usage.input_tokens_details.cached_tokens

不同 API 形态返回的字段名可能不同。例如 Chat Completions 风格常见 prompt_tokens_details.cached_tokens，Responses 风格常见 input_tokens_details.cached_tokens。

Anthropic 兼容主动缓存中，常见的缓存观测字段包括：

cache_creation_input_tokens
cache_read_input_tokens
input_tokens
output_tokens

可以按下面的方式理解输入 token：

总输入 token = 缓存读取 token + 缓存写入 token + 本次新增输入 token

对账时可以从模型响应或控制台用量明细中查看模型、输入输出 Token、缓存读取/写入 Token 和请求耗时等信息。不同协议的字段名可能不同，应以实际响应格式和账单明细为准。

成本判断

缓存不是所有场景都更便宜。首次写入缓存可能按普通输入或写入价格计费，后续命中缓存通常更便宜。只有在有效期内多次复用相同长上下文时，总成本和首 token 延迟才更容易下降。

可以用下面的方式粗略评估：

缓存命中率 = 缓存读取 token / 总输入 token
单位任务成本 = 总费用 / 成功任务数

如果缓存命中率长期很低，应优先检查前缀是否稳定、输入是否足够长、调用是否集中在有效期内，以及目标模型是否支持对应缓存能力。

推荐做法

• 缓存稳定内容，不缓存用户每次都会变化的问题。
• 将长文档、知识库、规范说明放在稳定上下文中，用户问题放在最后。
• 确保可缓存内容足够长；短提示词通常不会明显降低成本。
• 对批量任务集中在缓存有效期内执行，提高命中率。
• 对 Agent 场景，尽量保持工具定义、系统规则和输出约束的顺序稳定。
• 在日志中记录缓存写入、缓存命中、输入输出 token 和耗时，用于评估收益。
• 使用缓存前，先在小流量中观察命中率、平均耗时和单位任务成本，再扩大使用范围。

不推荐缓存的内容

• 用户当次输入的问题。
• 频繁变化的实时数据。
• 含有短期敏感信息且不需要复用的内容。
• 生成中间结果或临时草稿。
• 会导致不同用户之间混淆上下文的共享内容。

排查清单