Gemini API context caching怎样复用长文档上下文

Gemini API 复用长文档的关键，是先创建显式 context cache，后续请求只提交新问题并引用缓存名称。长文档、固定系统指令和工具配置放进缓存，变化的提问留在 generate_content 调用中；这样可以减少重复传输和重复处理，但缓存不是跨模型通用的永久知识库。

官方地址：https://ai.google.dev/gemini-api/docs/generate-content/caching

先区分显式缓存和隐式缓存

Gemini API 有两种 context caching。隐式缓存由平台根据相似前缀自动尝试，代码不需要创建缓存对象；显式缓存则由应用主动创建、命名和设置生命周期，适合一本手册、接口文档、会议转录或规则库会被连续提问的场景。需要可控地复用一份长文档时，优先使用显式缓存。

当前文档还说明，Interactions API 只支持隐式缓存；下面的手动创建方式使用 generateContent API 和 Google GenAI SDK。缓存资源创建后绑定具体模型，不能创建一次再随意换模型使用。

先把长文档变成可复用的缓存资源

下面示例把本地文本上传到 Files API，再创建一个带系统指令的缓存。ttl 用秒表示，示例中的一小时只是演示，生产环境应按文档更新频率和请求高峰调整。

from google import genai
from google.genai import types
import os

# API key 从环境变量读取，避免把凭据写进源码或缓存配置。
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# 先上传会被反复引用的长文档，返回的文件对象交给缓存资源。
document = client.files.upload(file="docs/product-manual.txt")

# 缓存资源绑定模型；TTL 到期后需要重新创建或续期。
cache = client.caches.create(
    model="gemini-2.5-flash",
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="只根据缓存文档回答，并指出无法从文档确认的内容。",
        ttl="3600s",
        display_name="product-manual-v1",
    ),
)

print(cache.name)  # 保存 cachedContents/{id}，后续请求只引用这个名称。

这里的 contents 是固定上下文，system_instruction 也属于缓存资源的一部分。不要把会频繁变化的用户问题放进创建阶段，否则每个问题都要重新建立缓存。文档更新时也不要继续沿用旧的 display_name 作为版本依据，建议在应用数据库中保存源文件摘要、缓存名称和创建时间。

后续请求只发送新问题

拿到 cache.name 后，每个问题都通过 cached_content 关联同一份上下文。请求仍然需要指定与缓存一致的模型；回答内容不会自动写回缓存，因此“复用长文档”与“保存多轮对话状态”是两件事。

from google import genai
from google.genai import types
import os

# 生产环境应从持久化配置中读取缓存名称，而不是每次重新创建缓存。
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
cache_name = "cachedContents/replace-with-your-cache-id"

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="请列出退款流程中的人工审核条件，并按文档章节给出依据。",
    config=types.GenerateContentConfig(cached_content=cache_name),
)

print(response.text)
# usage metadata 用于观察输入 token 与缓存命中情况，字段以 SDK 版本为准。
print(response.usage_metadata)

需要注意的是，缓存只保存可复用的输入上下文，不等于把所有后续问题和答案永久累积。若业务需要连续对话，应另外保存 previous_interaction_id 或自己的会话记录；不要把会话状态和显式 context cache 混成一条数据。

TTL、版本和命中情况怎么排查

缓存的过期可以用创建时的 ttl，也可以使用绝对的 expireTime。长期运行的服务应在应用侧保存“源文档版本 → cache.name”的映射，在到期前预热新缓存；不要等第一个用户请求失败后再同步上传大文件。确认不再使用的资源则调用删除接口释放管理负担。

# 续期或删除前，先从配置中心取出真实 cache_name，避免误操作其他文档版本。
cache = client.caches.get(name=cache_name)
print(cache.name, cache.model, cache.expire_time)

# 文档版本废弃后删除对应资源；删除动作应放在发布确认之后。
client.caches.delete(name=cache.name)

落地前的最小检查清单

• 长文档和固定规则确实会被多次查询，短文档不要为了“使用缓存”强行接入。
• 创建和调用使用同一个模型，应用持久化 cache.name、源文档版本和过期时间。
• 把新问题放在请求内容中，定期读取 usage metadata，不把一次成功调用当成命中率证明。
• 文档变更先创建新缓存，再切换流量；旧缓存到期或确认无引用后再删除。

相关问题

显式缓存能不能跨模型复用？

不能把它当成跨模型资源。缓存创建时已经绑定模型，调用时应保持同一模型；需要换模型时重新创建对应缓存。

每次提问都要重新上传长文档吗？

不需要。上传和创建缓存是准备阶段，后续请求使用 cache.name 引用固定上下文，只传新的问题和必要的临时参数。

为什么用了缓存仍然要关注 TTL？

缓存是有生命周期的资源，不是永久知识库。TTL 到期后引用可能失效，文档更新也可能让旧缓存产生过时回答，因此必须把过期和版本切换纳入应用逻辑。

以上示例围绕 Gemini API 的显式 context caching 展开，实际可用的模型、输入限制和计费规则应以官方文档与当前项目配置为准。