如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

提示词缓存诊断

比较响应,查明提示词缓存未能复用的原因。

如果某次请求复用的 Token 数量少于预期,提示词缓存诊断可以帮助您找出原因。将该请求与先前的响应进行比较,即可识别模型、工具、设置或输入中哪些变化阻碍了复用。

在 Responses API 中,GPT-5.6 及支持此功能的后续模型均可使用诊断功能。您可以用它排查单个请求,也可以通过提示词缓存仪表板监控整个应用的缓存性能。

工作原理

提示词缓存诊断将当前请求与先前的响应进行比较,帮助您了解为什么某个提示词前缀未能按预期复用。前缀是提示词开头的一段内容。要复用前缀,前缀内容必须完全匹配,模型、服务层级和工具等请求设置也必须兼容。

  1. 选择基准响应。 从同一组织近期已完成的响应中,选择一个其前缀预计会被当前请求复用的响应,例如上一轮对话的响应。
  2. 请求比较。 将 prompt_cache_options.comparison_response_id 设为基准响应的 id。
  3. 查看结果。 检查当前响应中的 prompt_cache_diagnostics。如果诊断检测到缓存未命中,结果会给出原因,方便您排查。使用 usage.input_tokens_details.cached_tokens 查看实际复用的 Token 数量。

设置 comparison_response_id 只会请求诊断,不会加载先前的对话或改变缓存行为。当前请求仍可复用其他请求留下的匹配缓存条目。

使用示例

两个请求都将相同的支持政策写入第一条 developer 消息,并将该消息放在 input 中。第二个请求将函数名从 get_time 改为 get_date,并以第一个请求为基准比较缓存复用情况。

请将您自己的政策文档保存在 support-policy.txt 中。可复用前缀必须达到模型的最短可缓存长度。对于 GPT-5.6 及后续模型,该长度为 1,024 个 Token。

比较两次响应的提示词缓存复用情况
from pathlib import Path

from openai import OpenAI

client = OpenAI()
policy = Path("support-policy.txt").read_text()  # At least 1,024 tokens.

messages = [
    {"role": "developer", "content": policy},
    {"role": "user", "content": "Reply with exactly OK."},
]

first = client.responses.create(
    model="gpt-6-astra",
    input=messages,
    tools=[{"type": "function", "name": "get_time"}],
)

second = client.responses.create(
    model="gpt-6-astra",
    input=messages,
    tools=[{"type": "function", "name": "get_date"}],
    prompt_cache_options={"comparison_response_id": first.id},
)

diagnostics = second.prompt_cache_diagnostics
if diagnostics is not None and diagnostics.type == "cache_miss":
    print(diagnostics.reason)
    print(diagnostics.comparison_reusable_tokens)
    print(diagnostics.cache_missed_tokens)

如果工具变更导致缓存未命中,结果可能如下所示。Token 数量因输入而异。

{
  "prompt_cache_diagnostics": {
    "type": "cache_miss",
    "reason": "tools_changed",
    "comparison_reusable_tokens": 5629,
    "cache_missed_tokens": 5629
  }
}

要继续复用缓存,请在各次请求中保持工具定义和顺序不变。请参阅以仅追加的方式更新工具。

多轮对话

要比较相邻的两轮对话,请保存每个已完成响应的 id,并在下一次请求中将其作为 comparison_response_id 传入 prompt_cache_options。第一轮请省略用于比较的响应 ID。

测试修复效果时,请继续使用基准响应的 ID 进行比较。

流式传输

当 stream=True 时,请读取 prompt_cache_diagnostics。该字段位于 event.response 中,可在收到 response.completed 事件时读取。

解读响应

查看 prompt_cache_diagnostics.type 以确定比较结果。

类型 含义 后续操作
cache_hit 本次比较未检测到缓存未命中。 查看 usage.input_tokens_details.cached_tokens,了解实际复用的 Token 数量。
cache_miss 某项差异导致预期的前缀未能复用。结果包含 reason 和 cache_missed_tokens,还可能包含 comparison_reusable_tokens。 在解决缓存未命中问题一节查找对应原因和建议的解决方法。
comparison_response_not_found 用于比较的响应没有可用的诊断记录。记录可能缺失或已过期。 从同一组织中另选一个近期已完成的响应。
unavailable 本次比较无法得出明确结论,或模型不支持诊断。 确认模型支持诊断,然后尝试与另一个近期响应进行比较。您仍可正常使用当前响应。

解读 Token 数量

cache_hit 表示本次比较未检测到缓存未命中。新输入仍可能需要处理。例如,一个包含 2,500 个输入 Token 的请求,如果复用了基准响应中长度为 2,000 个 Token 的前缀,并处理了 500 个新 Token,仍可报告 cache_hit。

从 GPT-6.2 开始,模型复用符合条件的前缀时可以报告 cache_hit,而顶层 instructions 仍按未缓存输入费率计费。查看 usage.input_tokens_details.cached_tokens 即可了解按缓存输入费率计费的 Token 数量。

对于 cache_miss:

  • comparison_reusable_tokens(如有)表示用于比较的响应中可复用前缀的原始 Token 数量。
  • cache_missed_tokens 是对其中未被复用的 Token 数量的估算。

这些诊断计数可能与用量统计不同。要了解实际报告的缓存复用量及计费情况,请以当前响应的用量字段为准。

解决缓存未命中问题

根据 prompt_cache_diagnostics.reason 的值,在下表中查找缓存未命中的原因和建议的解决方法。

有些变更是有意为之的,例如切换模型或压缩对话。即使这些变更会降低缓存复用率,您也可以选择保留它们。

原因 发生了什么变化 如何提高复用率
model_changed 处理请求的模型发生了变化,例如路由规则、A/B 测试或回退机制选择了另一个模型。 检查模型选择逻辑,确认是否发生了意外切换。对于需要共享缓存前缀的请求,请使用同一模型。请参阅影响缓存的设置。
prompt_cache_key_changed 两次请求提供的键不同。即使底层缓存实际命中,响应的 usage 也可能将其计为缓存未命中。 除非您的应用需要按客户或用户分别统计缓存用量,否则请省略 prompt_cache_key。如果使用缓存键,请在每个组内使用固定的键。请参阅使用缓存键分别统计缓存用量。
service_tier_changed 处理请求时使用的服务层级发生了变化。 对于预计会共享前缀的请求,请保持服务层级一致。检查返回的 service_tier,其值可能与请求中指定的值不同。有关支持的值和行为,请参阅 service_tier。
tools_changed 添加或移除了工具,调整了工具顺序,或更改了工具的描述、模式或配置。 保持工具定义和顺序不变。无需更改提供的工具列表,即可使用 tool_choice: "none" 禁用工具,或使用 allowed_tools 限制哪些工具可以运行。请参阅以仅追加的方式更新工具。
text_format_changed 输出格式或其模式发生了变化。 对于支持此功能的 GPT-6 及后续模型,请保持顶层 text.format 设置不变。需要使用不同的模式时,请追加格式更新。
reasoning_effort_changed 推理强度发生了变化。 对于支持此功能的 GPT-6 及后续模型,请追加一个 configuration_update 输入项,以在对话中调整推理强度,同时保留先前缓存的前缀。
对于较早的模型,请在需要共享前缀的请求中保持 reasoning.effort 一致。
verbosity_changed 响应的详略程度发生了变化。 对于需要共享前缀的请求,请保持 text.verbosity 一致。请参阅影响缓存的设置。
context_compacted 压缩后的内容替换了先前的对话内容。 保持稳定的指令不变,让后续对话轮次沿用压缩后的上下文。请比较输入总费用。即使缓存复用率下降,减少输入 Token 仍可能节省费用。请参阅压缩。
input_changed 先前的输入发生了变化,例如您在 developer 消息中添加了时间戳或请求 ID,或者编辑、重新排列或删除了先前的对话轮次。 将会变化的内容移到可复用前缀及其缓存断点之后。保留先前的消息和工具结果,并在末尾追加新的对话轮次。请参阅保留对话历史记录。

确认改进效果

完成更改后,请执行以下步骤:

  1. 再发送一个有代表性的请求,将其与选定的基准响应进行比较。
  2. 检查诊断结果,确认是否仍有差异。
  3. 比较多次请求的 cached_tokens、cache_write_tokens 和总费用。

有关用量指标和费用计算方法,请参阅监控缓存性能。

定价和速率限制

提示词缓存诊断不收取额外费用,也不单独计入速率限制。为获取基准响应或进行重试而向 Responses API 额外发送的请求,均按正常标准计费并计入速率限制。

零数据保留

提示词缓存诊断与零数据保留兼容。OpenAI 不会为此功能存储原始提示词或模型输出。诊断记录包含配置元数据、Token 数量估算值,以及用于比较会影响缓存复用的内容的哈希值。这些记录仅在所属组织范围内有效,保留时间很短,且仅用于解释提示词缓存命中或未命中的原因。

设置 comparison_response_id 不会检索或持久保存先前响应的内容。有关 OpenAI 的数据控制措施,请参阅您的数据。

限制

  • 在 Responses API 中,GPT-5.6 及支持此功能的后续模型均可使用诊断功能。
  • 诊断记录会在短期内过期。记录过期后,即使仍能通过 API 访问对应的响应,比较也会返回 comparison_response_not_found。
  • 诊断只报告首个归类的原因。解决该问题后,请再次比较,检查是否还有其他原因。
  • 诊断会尽可能对未命中的原因进行归类,但可能无法涵盖所有情况。比较结果尚未就绪时,会返回 unavailable。该结果无法说明缓存是否命中。
  • 诊断绝不会阻塞请求、导致请求失败或改变模型生成输出的方式。