Gemini API 隐式缓存怎么提高命中：公共前缀与 total_cached_tokens 核对法

团队把同一份产品手册反复发给 Gemini API，却发现请求看起来一样，缓存命中并不稳定。Gemini 2.5 及更新模型默认启用隐式缓存，不需要创建缓存对象；真正需要调整的是输入顺序：把大段、公共、稳定的内容放在最前面，把每次变化的问题放在后面，再从 usage.total_cached_tokens 判断是否命中。

隐式缓存改变了什么

Google 官方文档将隐式缓存描述为 Gemini API 的默认优化：Gemini 2.5 及更新模型均可使用，状态式对话和无状态请求都支持。命中后，平台会自动传递相应的成本节省；调用方不用显式创建、命名或续期缓存对象。

这不等于“任何重复文字都会缓存”。文档当前列出的最低输入门槛是：Gemini 2.5 Flash 与 Gemini 2.5 Pro 为 2048 tokens，Gemini 3.1 Pro Preview 及文档所列的 3.5/3.6/3.7/3.8 Flash 为 4096 tokens。模型列表会更新，接入时应以对应模型页面为准。

隐式缓存为什么要把公共前缀放前面

隐式缓存匹配的是请求开头的相似内容。更稳的组织方式是：公共前缀先放固定文档与固定规则，末尾再拼用户问题 A 或用户问题 B。若把时间戳、随机 ID、会话摘要等变化字段塞在最前面，即使后面是同一份长文档，前缀也会过早分叉。

另一个条件是短时间窗口。官方建议相似前缀的请求尽量在较短时间内发送，所以批量评测、文档问答和同一知识包的集中流量更容易利用隐式缓存；一天只来一个请求的低频场景，不应把成本预算建立在必然命中上。

用 total_cached_tokens 判断有没有命中

最小验证不需要猜。准备带同一公共前缀的请求 A 与请求 B，只改变末尾问题，并在短时间内连续发送。每个响应对象都读取 usage.total_cached_tokens，同时保存模型名、输入 token 数和前缀版本。该值记录命中的缓存 token 数，适合直接形成命中记录。

如果字段为零或没有增长，就保存为未命中记录，再检查三个地方：输入是否达到当前模型门槛；公共内容是否真的位于最前；前缀中是否混入动态值。不要为了提高数值而删除必要上下文，先保证语义正确，再优化重复部分。

Interactions API 与显式缓存的边界

Interactions API 只支持隐式缓存，不支持手工创建和管理显式缓存对象；需要显式缓存时，应改用 generateContent API。隐式缓存则同时适用于通过 previous_interaction_id 续接的状态式对话，以及自行重传上下文的无状态模式。

迁移时先做一周观测：按模型、公共前缀版本和业务场景汇总 usage.total_cached_tokens，再决定是否值得调整输入布局。若前缀经常变化或输入长期低于门槛，继续维持清晰的请求结构，比追求一个不稳定的命中率更实际。

常见问题

公共前缀相同就一定命中吗？

不一定。还要满足模型的最低输入 token 门槛，并尽量让相似请求在短时间内出现。最终仍以 usage.total_cached_tokens 为准。

状态式对话才能使用隐式缓存吗？

不是。官方文档明确说明状态式与无状态式请求都支持隐式缓存；区别只在上下文如何传递，不在缓存是否可用。