OpenAI Prompt Cache Diagnostics 正式发布：网关层不能随意丢弃的字段

在 OpenAI API 上调试 prompt cache 未命中，一直是个让人沮丧的事。系统 prompt 很长，你也开了 24 小时的 cache 窗口，但 usage.input_tokens_details.cached_tokens 总是返回零。没有任何提示说明什么地方变了，没有 diff，只有一批没命中缓存的 token 和比预期更高的账单。

2026 年 9 月 8 日，OpenAI 在 Responses API 正式发布了 Prompt Cache Diagnostics。这个功能在 response 上新增了一个结构化的 prompt_cache_diagnostics 字段，具体说明为什么某个 cache prefix 没有被复用。对于把 GPT-5.6 或 GPT-6 Astra 挂在网关或 router 后面的团队，有两件事值得立刻关注，一是 API 的接口形态，二是你的代理层不能对它做什么。

诊断接口的工作方式

这个机制刻意设计得很窄。在请求里传入 prompt_cache_options.comparison_response_id，填上你期望当前请求复用其 prefix 的那条历史 response 的 id。OpenAI 会对比两条请求，如果发现未命中，就在当前 response 上填充 prompt_cache_diagnostics。

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)                       # 例如 "tools_changed"
    print(diagnostics.comparison_reusable_tokens)   # 本应命中的 token 数
    print(diagnostics.cache_missed_tokens)           # 实际未命中的 token 数

reason 字段是这次新增的核心运营信息。官方文档给出的例子是 tools_changed，当函数工具的定义或顺序在两条请求之间发生变化时触发。OpenAI 的 prompt caching 文档一直提到，工具定义是渲染后 prefix 的一部分，只要中途改变顺序或新增一个工具，该位置之后的整个 prefix 就会失效。此前缺少的，是任何能确认这件事发生的手段。

Diagnostics 支持 GPT-5.6 及更新的模型，通过 Responses API 使用。GPT-5.6 及更新模型的最小可缓存 prefix 长度为 1024 个 token。comparison_response_id 必须来自同一个组织。传入这个字段只请求诊断，不改变当前请求的缓存行为，它仍然可以复用其他历史请求留下的匹配缓存条目。

对网关和 router 层的影响

这里是使用代理层的团队需要仔细检查的地方。很多 AI gateway，包括在转发前对请求体做规范化处理的中间件，可能会把未知或非标准字段丢掉。如果网关在请求到达 OpenAI API 之前就把 prompt_cache_options 剥离掉，prompt_cache_diagnostics 就永远不会出现在 response 里。诊断信号静默丢失，请求本身成功，缓存仍然未命中，你还是不知道原因。

工具列表的处理同样有风险。对工具定义做排序或去重的网关层，看起来只是无害的规范化操作，实际上会在每次上游顺序与规范化顺序不一致时，导致 cache prefix 失效。有了 diagnostics，这个模式现在可以被检测出来。即使应用层代码没有动过工具列表，你仍然会在连续两条请求上看到 reason: "tools_changed"。如果出现这个情况，问题发生在路由层，不在应用层。

实际的检查方法是观察网关转发的请求里是否包含 prompt_cache_options。如果这个字段在转发的请求体里不存在，把它加入网关的透传白名单。如果工具定义被网关的规范化逻辑重新排序了，改成保持插入顺序。

跨 provider 视角

Anthropic 的 prompt caching 没有等价的诊断接口。Sonnet 或 Fable 的请求缓存未命中时，usage.cache_read_input_tokens 是零，这就是全部信号。没有结构化的 reason code，没有跟基线请求的 token 级对比。对于在两条 provider 路径上分别跑 OpenAI 模型和 Anthropic 模型的团队，这是一个真实存在的可观测性差距。OpenAI 路径上的缓存未命中现在可以精确排查，Anthropic 路径上还是只能靠前后 token 数倒推。

两家的 cache TTL 行为也不同。Claude 模型默认 5 分钟缓存窗口，通过 cache_control: {"type": "ephemeral"} 可延长至 1 小时；OpenAI 模型大多数情况下是 5 到 10 分钟，非 ZDR 组织可以用 24 小时扩展窗口。在两个 provider 之间路由的网关需要跟踪各自适用的缓存模型，并据此指导下游的监控设置。Diagnostics 让 OpenAI 那条路上的监控明显更容易。

对运营监控的影响

在这个功能发布之前，常见的做法是对比一段时间内 input_token_count 与 cached_tokens 的比值，在比值低于阈值时报警。这是个总量级别的信号，适合做告警，但做不了根因定位。有了 prompt_cache_diagnostics，你现在可以在单条请求粒度上记录结构化的未命中原因，然后做聚合，统计每天有多少次未命中是 tools_changed，有多少是其他原因，以及某次部署之后这个比率有没有变化。

Diagnostics 也可以和 OpenAI 在八月发布的 Prompt Caching Dashboard 配合使用。Dashboard 展示组织和项目级别的总量缓存命中率以及每次写入对应的读取次数。当这些总量数字看起来不对时，Diagnostics 能把问题定位到具体的请求模式上。

部署层的检查项

Prompt Cache Diagnostics 正式发布对路由层来说，更多是一次检查机会，而不是需要立刻改什么。几件事值得确认。首先，你的网关对 prompt_cache_options 是透传还是忽略。其次，工具定义在从应用层到 OpenAI API 的整条路径上，顺序有没有被任何中间环节改变。第三，如果你在做 multi-turn 对话路由，转发给 OpenAI 的请求是否能携带上一条请求的 response id，用来触发诊断对比。

最后一条对于有 session 概念的 agent 路由场景尤其有用。长会话里的缓存命中率对成本影响很大，而导致命中率劣化的原因往往出现在某次工具列表变更或 model 切换之后，正好是 reason 字段能告诉你的。