Gemini API 显式 Context Caching 怎么验收：cachedContents、TTL 与命中统计

同一批产品手册、客服规则或代码仓库说明反复提交给 Gemini API 的时候，真正浪费资源的往往不是生成的回答本身，而是每次发起请求都要全量传一遍长上下文内容。显式 Context Caching 的核心作用就是把这段公共内容预先存成可复用的缓存资源，后续请求只需要带上用户问题和缓存的引用标识就行；做验收的时候别光看响应速度变快，要同步核对缓存对象状态、过期时长设置和 token 命中统计这三块内容。

显式缓存解决的是哪一段重复输入

假设一个智能问答服务每次调用都要先上传80页产品手册，再追加一句用户的实际问题。产品手册内容在一小时内基本不会改动，用户的问题却随时在变化。把手册内容放进缓存之后，后续请求就只需要引用缓存资源，再提交本轮用户的问题就够了。这套逻辑的核心不是把生成的回答永久存下来，而是复用输入侧的公共上下文部分。

Google AI 官方文档把缓存分成隐式和显式两条路径：隐式缓存由平台后台自动尝试匹配命中；显式缓存由业务侧主动创建并管理缓存对象。需要稳定控制公共材料内容、有效期和版本迭代的场景，用显式方式做校验排查会更方便。

先把 cachedContents 和 TTL 设成可检查的固定规则

显式缓存的最小校验规则可以整理成下面这张表：

缓存内容最好附带独立的版本标识，例如 manual-v20260822。产品手册更新之后，新建一份缓存再切流量过去就好，不要在已经存了旧规则的原有缓存上追加内容，不然出问题排查的时候根本没法判断模型调用的是哪一份材料。

用一个最小请求验证创建、引用和命中全流程

下面的 Python 代码片段展示基础调用逻辑，具体使用的模型名、可缓存 token 下限和客户端版本要以官方最新文档为准：

from google import genai

client = genai.Client()

cache = client.caches.create(
    model="gemini-2.5-flash",
    config={
        "display_name": "manual-v20260822",
        "system_instruction": "只依据给定手册回答，并指出手册未覆盖的内容。",
        "contents": ["产品手册：退货、换货、保修和客服处理规则……"],
        "ttl": "3600s",
    },
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="用户问：超过七天的未拆封商品怎么处理？",
    config={"cached_content": cache.name},
)

print(response.text)
print(response.usage_metadata)

第一轮操作只需要核对三件事：创建缓存接口返回合法的缓存资源名；生成内容的请求确实携带了 cached_content；返回结果的 usage 字段能读到对应缓存 token 或者等价的命中统计数据。如果第三项数据拿不到，先检查当前使用的客户端版本和响应对象结构，不要直接把“看不到统计”等同于“缓存没有命中”。

命中统计比接口耗时更适合作为验收凭据

网络波动、模型侧排队、输出内容长度都会影响接口响应耗时，所以“第二次请求速度更快”只能当成辅助参考信号。更稳妥的验收方案是固定同一份长上下文素材，连续提交多条不同的问题，每次都记录请求对应的缓存资源名、输入token量、缓存命中token量和总耗时。

如果第二次及之后的请求里 total_cached_tokens 持续大于0，而且缓存资源名没有被意外切换，说明请求确实成功复用了公共上下文内容。要是命中量一直为0，可以按照“资源是否过期、当前模型是否支持缓存、请求有没有误传完整的重复上下文、缓存前缀有没有改动”的顺序逐步排查。

缓存失效和内容更新要按版本切换

TTL 到期之后，业务侧要把缓存失效当成可自动恢复的状态处理：重新创建一份新缓存、写入新的版本号，再重试当前业务请求就行，不要无限次重试同一个已经过期的资源名。遇到产品手册或者知识库内容变更的场景，可以先创建新缓存，用预设的固定问题做一轮对照问答，确认新规则生效之后再切全部流量。

还有一个容易被忽略的边界：缓存只负责输入上下文的复用功能，不会自动判断文档内容是不是已经过时，也没法替代内容的权限隔离逻辑。不同租户的私有材料哪怕内容相似，也不能共用同一个缓存对象。

常见问题

显式缓存和隐式缓存应该怎么选？

只是想让平台自动利用请求里的重复前缀内容，可以先试用隐式缓存观察效果；需要自主控制缓存对象、TTL、版本迭代和流量切换的场景，选显式缓存做校验会更顺畅。

开了缓存为什么总耗时没有降低？

缓存主要减少的是重复输入内容的处理耗时，网络延迟、排队等待时间和输出内容长度带来的开销依然存在，优先确认缓存token命中正常，再判断有没有继续优化的必要。

产品手册更新后能不能直接修改旧缓存？

更稳妥的操作是按新版本创建全新缓存，用固定的测试问题做对照验证，确认所有引用都切换完成之后，让旧缓存自然过期就行。

Interactions API 可以直接使用显式缓存对象吗？

官方缓存文档对不同接口的支持边界有明确说明，接入前要核对对应接口的最新文档，不要直接把 Generate Content API 的参数原样套用到其他接口上。

把缓存验收逻辑写进业务日志之后，排查问题就从“感觉速度变快了”变成了可回溯的完整证据链：缓存版本清晰、TTL状态可见、请求引用标识正确，最后靠缓存token命中量确认公共上下文确实被成功复用。