提示缓存诊断可帮助您了解请求复用的 Token 数为何低于预期。将请求与之前的响应进行比较，找出模型、工具、设置或输入中阻碍复用的变化。
Responses API 为 GPT-5.6 及后续受支持的模型提供诊断功能。您可以使用诊断功能排查单个请求，并使用提示缓存仪表板监控整个应用的缓存性能。
工作原理
提示缓存诊断会将您当前的请求与之前的响应进行比较，帮助解释预期的提示前缀为何未被复用。前缀是提示开头的内容。复用要求前缀完全匹配，且模型、服务层级、工具等请求设置兼容。
- 选择基准响应。 从同一组织中选择一个最近已完成的响应，其前缀应是您期望当前请求复用的内容，例如上一轮对话的响应。
- 请求比较。 将
prompt_cache_options.comparison_response_id设置为基准响应的id。 - 查看结果。 检查当前响应中的
prompt_cache_diagnostics。如果诊断发现缓存未命中，结果中会包含原因，帮助您排查。使用usage.input_tokens_details.cached_tokens衡量实际的缓存复用情况。
设置 comparison_response_id 仅用于请求诊断，不会加载之前的对话，也不会改变缓存行为。当前请求仍可复用其他请求中匹配的缓存条目。
用法示例
以下示例发送两个请求，使用相同的模型、指令和输入，但将一个函数工具的名称从 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.
first = client.responses.create(
model="gpt-6-astra",
instructions=policy,
input="Reply with exactly OK.",
tools=[{"type": "function", "name": "get_time"}],
)
second = client.responses.create(
model="gpt-6-astra",
instructions=policy,
input="Reply with exactly OK.",
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，并在下一次请求的 prompt_cache_options 中将其作为 comparison_response_id 传入。第一轮请省略比较 ID。
测试修复效果时，请始终将比较 ID 设置为基准响应的 ID。
流式传输
当 stream=True 时，请从response.completed 事件的 event.response 中读取 prompt_cache_diagnostics。
理解响应
读取 prompt_cache_diagnostics.type，确定比较结果。
| 类型 | 含义 | 应对方法 |
|---|---|---|
cache_hit | 本次比较未检测到缓存未命中。 | 检查 usage.input_tokens_details.cached_tokens，衡量实际复用情况。 |
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。
对于 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 | 输出格式或其模式发生了变化。 | 当所需的输出结构不变时，请保持 text.format 和模式一致。请参阅结构化输出。 |
reasoning_effort_changed | 推理强度发生了变化。 | 对于需要共享前缀的请求，请保持 reasoning.effort 一致。请参阅影响缓存的设置。 |
verbosity_changed | 响应的详细程度发生了变化。 | 对于需要共享前缀的请求，请保持 text.verbosity 一致。请参阅影响缓存的设置。 |
context_compacted | 压缩替换了之前的对话内容。 | 保持指令稳定，让后续轮次在压缩后的上下文基础上继续。比较总输入成本：即使缓存复用减少，输入 Token 数量减少仍可能节省费用。请参阅压缩。 |
input_changed | 先前的输入发生了变化，例如指令中包含时间戳或请求 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结果，该结果不表示命中或未命中。 - 诊断绝不会阻塞您的请求、导致请求失败，或改变模型生成输出的方式。