当重复请求确实值得缓存时，复用大段 Gemini 上下文。
上下文缓存让应用复用文档、媒体、代码或大量系统指令等重复输入。它可能减少重复处理成本与延迟，但必须同时考虑命中率、生命周期、模型支持和数据存储风险。
快速判断是否应该缓存
隐式缓存
部分受支持模型可能自动复用相同的提示词前缀，应用无需创建或管理缓存资源。
显式缓存
主动创建可复用的 cached content 资源，在后续请求中引用，并直接管理其生命周期。
复用收益
大型稳定前缀在过期前被重复使用足够多次，能覆盖存储和创建成本时，缓存更有价值。
数据生命周期
缓存内容涉及保留和访问风险，应落实最小权限、到期、删除、地区和隐私控制。
选择合适的缓存场景
适合场景通常由大段稳定上下文和多次短问题组成，例如长手册、视频、代码库、政策资料或复杂系统指令。一次性提示和频繁变化的资料收益较低。
- 估算上下文大小、预期命中次数、有效期与请求频率。
- 保持可复用前缀稳定，将变化的用户输入放在后面。
- 比较不缓存总成本与创建、存储和缓存输入费用。
理解隐式与显式缓存
隐式缓存由受支持模型自动处理，可在用量元数据中报告缓存 token。显式缓存会创建命名资源，后续生成请求引用它，生命周期更可控。
- 不要假设所有模型、输入类型或请求都支持缓存。
- 通过 cached content token 元数据判断，不要只凭延迟猜测。
- 需要可控复用和明确 TTL 时评估显式缓存。
创建并引用 cached content
使用受支持模型和重复资料创建显式缓存，再把返回的资源名称传入后续生成配置；动态问题应保留在缓存之外。
- 设置清晰显示名称，并在应用记录中保存提供方资源名称。
- TTL 应匹配真实复用窗口，只在必要时续期。
- 处理创建、查询、过期、删除以及退回非缓存请求。
测量成本与延迟
缓存是一项需要数据证明的优化。监控创建延迟、命中率、缓存和非缓存输入 token、存储时长、端到端延迟及每个完成任务的总成本。
- 使用相同模型和内容，与非缓存基线比较。
- 流式界面分别衡量首 token 时间和总响应时间。
- 定价、token 门槛、模型支持或流量变化时重新评估。
保护缓存数据
缓存可能包含文档、媒体、源代码和系统指令，应将其视为已存储数据：减少内容、限制访问、明确删除，并审查提供方保留和地区规则。
- 不要缓存秘密或应用无权保留的数据。
- 缓存 ID 保留在服务端，每次引用都要授权。
- 删除废弃缓存，并记录事故、隐私和数据保留流程。
Python
简化示例创建一小时 TTL 的缓存并在后续请求中引用。请替换为符合条件的重复上下文，并确认当前 SDK 语法。
import os
from google import genai
from google.genai import types
client = genai.Client()
model = os.environ["GEMINI_MODEL"]
cached = client.caches.create(
model=model,
config=types.CreateCachedContentConfig(
display_name="product-manual",
contents=["<large repeated context>"],
ttl="3600s",
),
)
response = client.models.generate_content(
model=model,
contents="Summarize the upgrade procedure.",
config=types.GenerateContentConfig(cached_content=cached.name),
)
print(response.text)