Prompt Cache 到底命中了没有：别只看第二次请求更快

命中的判据在 usage 里

Prompt Cache 复用的是请求开头的稳定前缀。它减少重复处理这部分输入的成本和首 Token 延迟，不会复用上一轮生成的答案。Anthropic 的缓存文档明确写明，缓存不影响输出生成，收到的响应与未使用缓存时相同。

判断一笔请求是否命中，直接看响应里的缓存读取字段：

延迟只能做旁证。一次请求少排了队、少生成几十个 Token，同样会更快；一次缓存已经命中的请求，也可能因为模型侧排队而更慢。

可复查的最小测试

测试材料需要超过所用模型的缓存下限。用一段足够长、内容固定的系统说明或文档作为前缀，把每次变化的问题放在末尾。不要在固定前缀里插入时间戳、随机 ID、用户昵称或动态工具描述。

按同一顺序发两次：

1. 第一次请求负责建立缓存。记录完整请求体、模型名、响应 usage 与发送时间。
2. 在缓存有效期内发送第二次请求。固定前缀逐字不变，只修改前缀之后的问题。
3. 检查第二次响应的缓存读取字段。字段大于 0 才能确认这笔请求读到了缓存。
4. 再比较首 Token 延迟和按官方费率计算的输入成本。这一步判断命中有没有带来可见收益。

OpenAI 的缓存指南要求精确的前缀匹配，图片和工具定义也要一致。当前文档还区分 GPT-5.6 及后续模型与更早模型：前者支持缓存断点，并要求通过断点的完整渲染前缀至少 1024 Token；更早模型的最低长度因模型而异，在 1024 到 2048 Token 之间。只重复一条几十字的用户消息，不能检验缓存。

Claude 同样有模型与平台相关的门槛。官方缓存限制列出的当前范围从 512 到 4096 Token 不等。短于门槛时，请求照常处理且不报错；cache_creation_input_tokens 和 cache_read_input_tokens 都会是 0。这类结果说明测试材料不合格，不能推断中转站改写了请求。

Gemini 同时有隐式缓存和显式缓存。Google 的上下文缓存文档说明，Gemini 2.5 及后续模型默认启用隐式缓存；显式缓存需要先创建缓存资源，再在生成请求中引用。两种方式都应从响应的 usage_metadata 查看命中 Token，不能用「SDK 没报错」代替命中证据。

为什么相同文本仍会未命中

缓存比较的是渲染后的请求前缀，肉眼看到的正文相同还不够。

动态内容放在了前缀中间

日期、追踪 ID 或一条变化的用户属性若出现在静态说明之前，从这个位置开始的后续内容都无法匹配。OpenAI 文档建议把静态指令、示例和共享上下文放在前面，把请求特有内容放到末尾。Claude 的规则也是把断点放在保持不变的末端内容块上，避开变化的块。

工具和图片发生了变化

工具的名称、描述、JSON Schema、排列顺序都属于 prompt 的一部分。OpenAI 明确要求工具和图片在命中范围内保持一致；Claude 也允许缓存 tools、system 和消息内容。若应用每次动态生成工具描述，即使业务问题相同，缓存前缀也已经不同。

缓存没有写成功或已经过期

重复内容不会自动保证读到缓存。OpenAI 当前文档说明，没有在合格断点写入匹配条目时，后续请求无法读取。Claude 的默认缓存 TTL 是 5 分钟，也支持 1 小时 TTL；Gemini 显式缓存若未指定 TTL，默认是 1 小时。测试间隔必须写进记录，否则第二次的 0 无法区分「前缀不同」和「条目过期」。

请求被分到不同的缓存隔离范围

缓存通常按组织、项目或工作空间隔离。Anthropic 文档写明 Claude API 自 2026 年 2 月 5 日起采用工作空间级隔离；同一组织里的不同工作空间不会共享缓存。中转站如果轮换上游账号或工作空间，前缀相同也可能连续未命中。

三家字段不能套同一个加法

OpenAI 的 cached_tokens 和 Gemini 的 cachedContentTokenCount 都是各自输入总量里的子集。Claude 的 input_tokens、cache_creation_input_tokens、cache_read_input_tokens 则需要相加，才能还原输入总量。完整的包含关系见三家 Token 用量字段对照。

缓存命中率可以统一定义成「缓存读取 Token ÷ 有效输入总 Token」，但分子和分母必须先按供应商口径还原。直接拿三个原始字段相除，报表会在缓存开始生效后出现假下降或超过 100% 的结果。

经过中转站时，多做两组对照

先在官方端点完成一次写入—读取测试，确认材料长度、模型与请求结构本来能够命中。然后用同一份结构测试中转站。两边都未命中，应先修测试；官方稳定命中而中转持续为 0，才值得检查中转是否修改了 system prompt、工具定义、模型名或上游路由。

还要保留原始响应。部分「OpenAI 兼容」接口只返回 prompt_tokens、completion_tokens 和 total_tokens，缓存明细可能为空。Anthropic 官方的 OpenAI SDK 兼容层就明确不支持 Prompt Caching，并始终把 usage.prompt_tokens_details 留空。这种接口缺少可观测字段，无法仅凭返回值确认命中。相关限制见“兼容 OpenAI API”到底兼容到哪一层。

该监控哪些数据

每笔请求至少留下模型完整标识、接口类型、缓存配置、有效输入总量、缓存写入量、缓存读取量、首 Token 延迟和请求结果。按小时或按模型汇总命中率时，同时显示样本数；只有两笔请求的 50% 和两千笔请求的 50%，判断力度不同。

缓存命中不是一个长期不变的开关。模型版本、缓存门槛、TTL、工具定义和上游路由都会变化。一次测试能确认某笔请求读到了缓存；要回答命中率从哪一天开始下降，需要把这组探针纳入中转站监控基线连续记录。