Gemini 隐式缓存cachedContentTokenCountGemini API

Gemini 隐式缓存为什么没命中：前缀、token 门槛与用量排查

用 Gemini 官方文档和一组可重放请求排查隐式缓存：确认模型门槛、固定公共前缀、读取 cachedContentTokenCount，并区分站内转发与 Google 直连结果。

关键词Gemini 隐式缓存cachedContentTokenCountGemini API缓存排障
LALondAI 内容团队发布日期 2026-11-13
6 分钟阅读模型教程
LA
Gemini 隐式缓存为什么没命中：前缀、token 门槛与用量排查
Gemini 隐式缓存官方来源与可执行检查LondAI 内容团队

Gemini API 的隐式缓存默认开启，但开启不代表每个请求都会命中。最常见的排查方向是：模型是否支持、可复用前缀是否足够长、前缀是否逐字相同，以及两次请求是否足够接近。下面的实验直接请求 Google Gemini API；若通过 LondAI 或其他中转平台调用，还需单独验证该渠道是否透传相同请求结构与用量字段。

先确认门槛与可观察字段

Google 官方说明，Gemini 2.5 及更新模型默认启用隐式缓存。以 gemini-2.5-flash 为例，文档列出的最小输入门槛是 2,048 token；其他模型门槛可能不同。把大量稳定资料放在开头，只把每次变化的问题放在末尾，可提高命中机会。REST 响应的 usageMetadata.cachedContentTokenCount 表示已缓存的输入 token 数；没有该字段或为零时，不应把请求计成已命中。直接来源：Google Gemini Context caching 指南、GenerateContent UsageMetadata 定义。

可重放的对照实验

准备一份可公开测试的长文本 reference.txt，使用 Google 的 token 计数指南确认公共部分超过所选模型门槛。不要用客户资料或密钥做样本。在本机设置环境变量 GEMINI_API_KEY，不要把值写进脚本或提交。下面用 jq 生成请求：先保留相同的长文本，只改变结尾的问题。

jq -n --rawfile r reference.txt --arg q "问题一" '{contents:[{role:"user",parts:[{text:($r+"\n问题："+$q)}]}]}' > req.json
curl -sS "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" -d @req.json | jq '.usageMetadata | {promptTokenCount,cachedContentTokenCount,candidatesTokenCount}'

第二次只把 --arg q 改为“问题二”，重新生成请求后立即调用；第三次修改 reference.txt 开头的少量字符，作为前缀变化的负例。该实验需要操作者自己的 Google API 权限与可用额度；本站未代替用户发送请求。

按顺序排查五个点

  1. 查看响应是否成功，并记录真实模型名；无权限、限流或错误响应不能用于缓存判断。
  2. 用计数接口核实公共前缀 token 数；不要把整个请求总 token 误当可缓存前缀。
  3. 比较两次请求的公共前缀字节，包括系统说明、文件内容、换行和工具定义；把变量移到末尾。
  4. 间隔较短重发，比较 promptTokenCount 与 cachedContentTokenCount。隐式命中没有保证，单次零值不足以证明功能故障。
  5. 在第三次负例后重复多轮，记录命中率、时延和账单；通过中转时另查渠道返回的 usage 是否保留缓存字段。

隐式与显式缓存的边界

隐式缓存无需创建缓存对象，但不能保证每次节省成本。若业务需要可控 TTL，可评估显式缓存：Google 文档说明显式缓存处于 Beta、使用 v1beta，且 Gemini 4 模型不支持显式缓存；显式缓存的存储时间另有费用。两种模式不要混为一谈。缓存 token 仍受通常的模型 token 与速率限制约束，敏感数据的保留和处理政策应按所用 Google 产品及合同核对。本站没有核验任何中转渠道的缓存折扣或计费实现。

验收与成本记录

保存至少两组“相同前缀、不同末尾”的请求和一组“修改前缀”的负例，记录请求时间、模型、前缀 token、cached token、总输出、时延及实际费用。只有响应显示缓存 token 且账单相符，才把折扣计入成本估算。若始终为零，先检查门槛和前缀，再到官方文档核对当前模型支持情况；若直连命中而中转不命中，再排查请求改写和用量字段透传。可参考 LondAI 接入文档确认站内请求格式。