Prompt 缓存命中率下降时怎么查前缀是否稳定

Prompt 缓存命中率下降，通常不是“缓存突然失效”，而是请求在某个动态字段、工具定义或模型设置处提前分叉了。排查时不要只看完整 prompt 是否相似，要比较模型最终收到的渲染前缀，并把 cached_tokens、模型、工具列表和时间窗口一起记录下来。以 OpenAI API 为例，缓存复用要求可缓存前缀完整匹配；前缀前部发生变化，变化点之后就不能继续复用。

先确认命中的到底是哪一段前缀

Prompt caching 复用的是模型处理输入后形成的 KV 状态，不是把旧 token 原样拿出来拼接。一次请求可以同时包含缓存输入和未缓存输入，所以总输入 token 变大并不代表命中率变差，关键是响应 usage 里的 cached_tokens 是否稳定。

第一步是按模型、版本和业务路由分组记录指标。缓存容量、最小可缓存长度和缓存生命周期属于具体模型或服务商的规则；当前 OpenAI 文档把 GPT-5.6 及更新模型的最小可缓存长度列为 1024 token，较早模型通常是 2048 token。短 prompt 即使写法稳定，也可能没有足够长的可复用前缀。

把动态内容移到稳定前缀之后

“模板文件没改”并不等于前缀没改。常见破坏点包括把当前时间插入系统指令、按租户动态生成工具描述、随机排列工具顺序、在固定规则前插入用户历史，以及让 A/B 实验标记出现在共享前缀中。应该先生成最终消息序列，再对可复用区做摘要或 hash，而不是对源模板做 hash。

下面用 Responses API 表达一个最小结构。示例中的固定开发者指令和工具策略保持不变，地区、用户问题等请求变量放在后面的 user 消息中；prompt_cache_key 用来让同一工作流共享稳定的分区标识。模型名称需要替换成账号实际支持的模型。

from openai import OpenAI

client = OpenAI()
FIXED_PREFIX = """你是客服路由器。先判断意图，再输出 JSON。"""

def ask(user_text: str, region: str) -> int:
    response = client.responses.create(
        model="gpt-5.6",  # 使用同一模型，避免模型切换改变可命中前缀
        input=[
            {
                "role": "developer",
                "content": [{"type": "input_text", "text": FIXED_PREFIX}],
            },
            {
                "role": "user",
                # 变化内容放在固定前缀之后，不要插回 developer 指令中
                "content": [{"type": "input_text", "text": f"region={region}\\n{user_text}"}],
            },
        ],
        prompt_cache_key="support-router-v1",  # 统一同一工作流的缓存分区
    )
    # 保存命中量，供日志和看板按模型分组比较
    return response.usage.input_tokens_details.cached_tokens

cached = ask("查物流单号", "cn-east")

生产代码还应把工具列表、结构化输出 schema、parallel_tool_calls 和推理设置纳入版本管理。调用方若在 developer 消息里加入了随机 trace 文本，即使业务问题完全相同，也会从 trace 变化点开始失去复用。

用首个差异点解释命中率波动

建议为每次请求保存一份脱敏后的渲染摘要：消息角色和顺序、工具名及 schema 版本、模型、输出格式版本、缓存键、前缀 hash、总输入 token、cached_tokens 和 uncached_tokens。正文或日志不必保存用户原文，保存字段长度、稳定版本号和首个差异的位置就足够定位多数问题。

如果 prefix hash 变了，先做 diff：差异出现在固定指令、工具定义、历史消息还是请求设置。如果 hash 没变但命中量下降，再看最小缓存长度、模型缓存生命周期、流量是否切到另一模型，以及多租户是否共用同一缓存键。不要用改写同义词的方式“优化命中率”，那只会制造更多不同前缀。

• 固定 model 与工具排序，所有 schema 变更带版本号。
• 把时间、随机数、用户标识、实验分组和本轮问题放到动态区。
• 用相同请求连续发送小流量样本，分别记录冷请求和后续请求的 usage 与首 token 延迟。
• 变更前缀时提高版本号并观察一段完整缓存生命周期，不要把冷启动样本和稳定样本混在一起。

常见问题

缓存命中率下降是不是一定要增加缓存容量？

不一定。先确认前缀是否变化、是否达到最小长度、模型是否切换；容量只是可能原因之一。

把用户问题放进固定 prompt 会更省 token 吗？

通常相反。用户问题是变化内容，应放在稳定前缀之后；把它嵌入前缀会让每个问题都产生不同的可复用边界。

只固定 prompt_cache_key 就能保证命中吗？

不能。缓存键可以帮助工作流分区，但服务端仍需看到满足规则的相同渲染前缀；模型、工具和输出设置的差异仍要排查。

应该看哪些官方字段？

以 OpenAI Responses API 为例，优先记录 usage.input_tokens_details.cached_tokens，并和总输入 token、模型及请求版本一起看。

需要核对具体模型规则时，优先查看 OpenAI Prompt caching 文档及对应模型说明；不同供应商的字段名、最小长度和缓存生命周期可能不同。