Gemini API 的 cachedContent 怎么复用长提示词：缓存创建与请求绑定

客服知识库每天都会收到很多不同问题，但产品说明书、接口约束和合规规则并没有变化。把整份长文档随每次请求重新发送，成本和延迟都会一起上升。Gemini API 的 Context Caching 可以把稳定上下文先创建成 CachedContent，后续请求只提交新问题，并通过 cache.name 绑定这份缓存。

可复用的内容放进 cachedContents.create，变化的问题仍放在 generateContent 的 contents 中；两者靠返回的 cache.name 连接，而不是把缓存内容再复制一遍。

先把长上下文和用户问题拆成两条路径

Context Caching 解决的不是“把所有历史对话永久保存”，而是让一段会反复使用的输入只准备一次。比如一份产品手册、一个较大的代码仓库摘要，或者一组固定的客服规则，都可以成为缓存内容；“用户这次到底想问什么”则应该留在每一次生成请求里。

这个拆分很重要。缓存对象创建后，缓存的 contents[]、tools[]、systemInstruction 和 toolConfig 都是创建请求的一部分。后续问题不是去修改缓存，而是引用它并追加本轮输入。

cachedContents.create 返回的 cache.name 才是绑定凭据

下面的示例使用新版 Google GenAI SDK。代码中的文档内容是稳定上下文，请找出退款条件 是每次变化的问题。创建缓存和生成回答是两次调用，第二次通过 cached_content 传入第一步得到的 cache.name。

from google import genai
from google.genai import types

client = genai.Client()
cache = client.caches.create(
    model="gemini-3.7-flash",
    config=types.CreateCachedContentConfig(
        contents=["产品手册：退款、换货与保修规则"],
        system_instruction="只根据缓存的产品手册回答问题。",
    ),
)

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="请找出退款条件",
    config=types.GenerateContentConfig(
        cached_content=cache.name,
    ),
)
print(response.text)

不要把 cache.name 当成缓存正文。它是类似 cachedContents/... 的资源名，只负责告诉 generateContent 使用哪一个 CachedContent。真正需要变化的用户问题继续放在 contents，这样同一份规则才能服务多个问法。

模型、最小输入和 TTL 是上线前的三个检查点

创建缓存前先确认目标模型支持 createCachedContent。官方接口文档还把缓存内容标成创建时输入、不可变；如果要延长使用时间，应更新 TTL 或 expire_time，而不是重新提交一份看起来相同的缓存。

缓存也不是越大越好。若每个请求的长文本都不同，创建成本和管理复杂度可能抵消收益；若稳定内容很短，直接发送反而更简单。判断时至少观察响应使用信息里的缓存命中 token，而不是只看请求代码里出现了 cached_content。

常见问题：把缓存当成可编辑会话

缓存创建后能不能追加一段新规则？

不能直接追加。缓存内容和工具相关配置属于创建时输入；新规则应创建新的 CachedContent，或者把短期规则作为本次请求的输入，并重新评估优先级。

每次请求都要再次上传原文吗？

不需要。后续请求只需引用 cache.name 并提交本轮问题，但应用仍要保存资源名、过期策略和失败时的重建路径。

只要绑定 cache.name 就一定省钱吗？

不一定。是否节省取决于重复上下文长度、缓存命中情况、缓存生命周期和调用频率；应结合 usage metadata 与实际账单口径核对。

缓存资源过期后请求会怎样？

不能把过期当成正常回答路径。捕获请求错误后，应按业务窗口重新创建 CachedContent，再用新的资源名发起请求，并避免无限重建。

把缓存接入应用时保留一条可回退路径

实际接入可以把资源名和模型名放在应用配置中，把创建时间、过期时间和最后一次命中核对结果写入可审计的记录。请求失败时先判断是资源过期、模型不匹配还是输入格式问题，再决定重建缓存或退回普通 generateContent 请求。这样缓存只是加速层，业务回答不会被一个短期资源绑死。

最小验收顺序是：创建一次 CachedContent，记录 cache.name；使用同一资源名发送两种不同问题；查看响应使用信息中的缓存命中字段；再更新 TTL 并核对过期时间变化。四步都能解释清楚，才算真正完成了缓存绑定，而不是只把一个参数写进代码。