OpenAI API prompt caching 怎样判断缓存命中边界

我排查 prompt caching 时，最容易误判的一点是：两次请求“意思差不多”，并不等于缓存命中。OpenAI API 复用的是请求开头的精确前缀，真正要看的证据在响应的 usage.input_tokens_details，而不是体感延迟。把稳定的开发者指令、工具定义放在前面，再把变化的用户内容放到后面，才能得到可解释的结果。

官方地址：https://developers.openai.com/api/docs/guides/prompt-caching

一、先把“缓存边界”理解成可复用前缀

缓存不是全文相似度搜索。服务会从请求开头寻找可用的最长匹配前缀；前缀中的 token、模型和相关请求设置需要保持兼容。只改了最后一句用户问题，通常仍有机会复用前面的上下文；但如果在开头插入时间戳、随机请求号，后面的内容即使完全不变，也可能整体变成新前缀。

实际组织请求时，可以按“稳定块在前、变化块在后”处理。Responses API 使用显式模式时，把 prompt_cache_breakpoint 放在稳定的 input_text 内容块末尾；动态用户问题留在 breakpoint 之后。这样做的价值是：即使后缀每次都变，也不会把它当成想长期写入缓存的共享上下文。

二、用 usage 和诊断信息确认到底命中了什么

不要只看首 token 速度。请求完成后先记录 usage，再和上一条相同工作流的响应比较。下面是一个最小的读取示例：

# 读取 Responses API 的缓存计数，区分命中与新写入
usage = response.usage
details = usage.input_tokens_details

cached = details.cached_tokens or 0
written = details.cache_write_tokens or 0

if cached > 0:
    print(f"命中缓存前缀：{cached} tokens")  # 只表示有前缀复用，不代表整条请求都命中
elif written > 0:
    print(f"本次写入缓存：{written} tokens")  # 首次请求或新边界可能走写入
else:
    print("没有可报告的缓存复用或写入")  # 还要结合模型、长度和请求设置继续排查

一次请求同时出现命中和写入并不矛盾：前面较长的一段可能被复用，后面新增的部分又被写入。判断时要看计数覆盖了哪一段，而不是把“有 cached_tokens”简单等同于“100%命中”。

三、缓存未命中时按这张清单定位

诊断接口提供的是排查线索，不会替你修改请求。尤其要注意：重写历史消息、压缩上下文、改变工具顺序，都会改变可匹配的前缀。多轮应用尽量追加新消息，不要在每轮把旧消息重新拼接成略有差异的文本。

四、把命中判断纳入上线前检查

我会用两条相邻请求做小样本验证：第一条记录 cache_write_tokens，第二条只替换动态问题，再看 cached_tokens 是否覆盖预期的稳定前缀。若要长期复用，还要记录模型、TTL、工具版本和输入 token 数；缓存命中仍受生命周期和服务端可用性影响，不能当作永久存储。

最终结论可以收敛成一句话：先确认“前缀是否逐 token 稳定”，再用 cached_tokens 量化复用范围，最后用 diagnostics 解释差异。这样既能判断缓存命中边界，也能避免为了追求命中率把动态内容错误地塞进共享缓存。

相关问题

只有 cached_tokens，没有 cache_write_tokens，说明什么？

通常表示本次请求复用了已有缓存，且没有新的可报告写入；仍需结合输入长度和模型支持情况解释。

prompt_cache_key 能保证命中吗？

不能。它用于缓存路由或分组管理，命中仍要求请求拥有兼容且精确匹配的前缀。

改变用户问题会清空整段缓存吗？

不一定。只要变化发生在稳定前缀之后，前面的匹配部分仍可能命中；如果变化发生在前缀内部，命中边界会提前结束。