OpenAI 提示词缓存诊断

提示词缓存诊断解释请求为什么复用了少于预期的词元。与此前响应比较，可识别阻碍复用的模型、工具、设置或输入变化。

诊断适用于Responses API中受支持的GPT-5.6及以后模型，用于调查单次请求；整体表现用缓存控制台监控。

工作方式

前缀是提示词开头的内容，复用要求精确匹配，并有兼容的模型、服务层级和工具等设置。

选择近期、同组织、已经完成且预期可复用前缀的响应，例如上一轮。
将其id设为prompt_cache_options.comparison_response_id。
查看当前响应的prompt_cache_diagnostics。未命中时给出原因；实际复用用usage.input_tokens_details.cached_tokens衡量。

比较ID只请求诊断，不加载旧对话、不改变缓存行为。当前请求仍能复用其他请求的匹配条目。

使用示例

两次使用相同模型、指令和输入，只把函数工具get_time改名为get_date，第二次与第一次比较。support-policy.txt应换成自己的政策文档，可复用前缀需达到最小长度，新模型为1,024词元。

代码中的任务Reply with exactly OK.完整译为“仅回复OK，内容必须完全一致”；文件行尾注释表示“至少1,024个词元”。

使用示例（来源示例1，python）

## [中文] 政策文件至少包含1,024个词元；先用get_time建立基线，再改名get_date发送比较请求。
## [中文] comparison_response_id只请求诊断，不加载旧对话；只在cache_miss时读取未复用原因。
## [中文] 任务字符串要求恰好回复OK；实际缓存读取量仍以usage为准。
from pathlib import Path

from openai import OpenAI

client = OpenAI()
## [中文] 文件内容至少包含1,024个词元。
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)

工具改变造成未命中时，结果可能如下，实际词元数依输入而变。

使用示例（来源示例2，json）

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

为保留复用，跨请求保持工具定义和顺序，见只追加工具更新。

多轮对话

保存每个完成响应的ID，下一轮作为比较ID；首轮省略。测试修复时，仍使用原基线响应作为比较对象。

流式处理

stream=True时，在response.completed事件的event.response读取诊断。

理解响应

`type`	含义	处理
`cache_hit`	比较未发现缓存未命中	仍用usage的缓存词元衡量实际复用
`cache_miss`	某项差异阻碍预期前缀复用，包含reason和cache_missed_tokens，可能含comparison_reusable_tokens	按原因调查
`comparison_response_not_found`	比较记录不可用，可能不存在或已过期	选择同组织近期已完成响应
`unavailable`	无确定比较结果，或模型不支持	确认支持情况，尝试其他近期基线；响应本身仍可使用

理解词元数量

cache_hit不代表所有输入都被复用。例如总输入2,500，复用基线2,000词元并处理500新词元，仍可报告命中。

未命中时，comparison_reusable_tokens若存在，是基线可复用前缀的原始词元数；cache_missed_tokens估算其中未复用的数量。诊断估算可能与usage不同，应以当前usage衡量报告用量和计费。

修复未命中

读取prompt_cache_diagnostics.reason。有些变化如切模型或压缩是有意的，即使降低复用也可能保留。

原因	变化	改善方式
`model_changed`	路由、A/B测试或回退选择不同模型	排查意外切换，期望共享前缀的请求用同模型
`prompt_cache_key_changed`	键改变；usage可报告未命中，但未必实际物理缓存未命中	不需分开客户账目可省略键；需要则组内保持稳定
`service_tier_changed`	实际服务层级变化	保持一致，检查返回的service_tier，可能与请求值不同
`tools_changed`	工具增删、重排、说明/Schema/配置变化	稳定定义与顺序，用tool_choice:none或allowed_tools控制调用，不改列表
`text_format_changed`	输出格式或Schema改变	需求未变时保持text.format与Schema
`reasoning_effort_changed`	推理力度变化	支持的新模型用configuration_update保留原前缀；旧模型保持请求级力度一致
`verbosity_changed`	回答详细度改变	共享前缀的请求保持text.verbosity一致
`context_compacted`	压缩替换旧上下文	保持稳定指令，在压缩上下文上继续增长；比较总成本，输入减少仍可能省钱
`input_changed`	时间戳、请求ID或旧消息编辑、重排、删除	动态内容放可复用前缀和断点后，保留历史、追加新轮次

确认改进

修改后，再发代表性请求与预期基线比较，检查剩余差异，并跨多个请求比较cached_tokens、cache_write_tokens与总成本，计算方法见监控缓存。

价格与速率限制

诊断本身不额外收费，也不单独计入速率限制。额外基线或重试请求仍正常计费、计限额。

零数据保留

诊断兼容ZDR，不为此功能存储原始提示词或模型输出。记录包含配置元数据、词元数估算和比较缓存敏感内容的哈希，只在组织内有效，短期后过期，仅用于解释命中或未命中。比较ID不检索或持久化旧响应内容，见数据控制。

限制

仅适用于Responses中受支持的新模型。
诊断记录短期过期；即使旧响应仍可从API读取，也可能返回comparison_response_not_found。
只报告首个分类原因，修复后再比较排查其他原因。
尽力而为，不保证分类所有未命中；unavailable不表示命中或未命中，也可能是比较未准备好。
不阻塞或使请求失败，不改变输出生成。