如果某次请求复用的 Token 数量少于预期,提示词缓存诊断可以帮助您找出原因。将该请求与先前的响应进行比较,即可识别模型、工具、设置或输入中哪些变化阻碍了复用。
在 Responses API 中,GPT-5.6 及支持此功能的后续模型均可使用诊断功能。您可以用它排查单个请求,也可以通过提示词缓存仪表板监控整个应用的缓存性能。
工作原理
提示词缓存诊断将当前请求与先前的响应进行比较,帮助您了解为什么某个提示词前缀未能按预期复用。前缀是提示词开头的一段内容。要复用前缀,前缀内容必须完全匹配,模型、服务层级和工具等请求设置也必须兼容。
- 选择基准响应。 从同一组织近期已完成的响应中,选择一个其前缀预计会被当前请求复用的响应,例如上一轮对话的响应。
- 请求比较。 将
prompt_cache_options.comparison_response_id设为基准响应的id。 - 查看结果。 检查当前响应中的
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,或者编辑、重新排列或删除了先前的对话轮次。 |
将会变化的内容移到可复用前缀及其缓存断点之后。保留先前的消息和工具结果,并在末尾追加新的对话轮次。请参阅保留对话历史记录。 |
确认改进效果
完成更改后,请执行以下步骤:
- 再发送一个有代表性的请求,将其与选定的基准响应进行比较。
- 检查诊断结果,确认是否仍有差异。
- 比较多次请求的
cached_tokens、cache_write_tokens和总费用。
有关用量指标和费用计算方法,请参阅监控缓存性能。
定价和速率限制
提示词缓存诊断不收取额外费用,也不单独计入速率限制。为获取基准响应或进行重试而向 Responses API 额外发送的请求,均按正常标准计费并计入速率限制。
零数据保留
提示词缓存诊断与零数据保留兼容。OpenAI 不会为此功能存储原始提示词或模型输出。诊断记录包含配置元数据、Token 数量估算值,以及用于比较会影响缓存复用的内容的哈希值。这些记录仅在所属组织范围内有效,保留时间很短,且仅用于解释提示词缓存命中或未命中的原因。
设置 comparison_response_id 不会检索或持久保存先前响应的内容。有关 OpenAI 的数据控制措施,请参阅您的数据。
限制
- 在 Responses API 中,GPT-5.6 及支持此功能的后续模型均可使用诊断功能。
- 诊断记录会在短期内过期。记录过期后,即使仍能通过 API 访问对应的响应,比较也会返回
comparison_response_not_found。 - 诊断只报告首个归类的原因。解决该问题后,请再次比较,检查是否还有其他原因。
- 诊断会尽可能对未命中的原因进行归类,但可能无法涵盖所有情况。比较结果尚未就绪时,会返回
unavailable。该结果无法说明缓存是否命中。 - 诊断绝不会阻塞请求、导致请求失败或改变模型生成输出的方式。