上下文缓存
Gemini 的上下文缓存用于缓存重复的长上下文，适合固定系统提示词、大段知识库上下文、长文档问答和重复业务规则。它可以降低重复输入的成本，并改善部分长上下文场景的延迟。
什么是上下文缓存
上下文缓存会缓存请求中可复用的大段内容，例如系统提示词、文档材料、工具定义和固定业务规则。后续请求围绕同一批材料提问时，可以复用缓存内容。
常见缓存内容包括：
- 长系统提示词
- 业务规则
- 知识库材料
- 大型文档内容
- 长对话中的稳定历史
- 多模态材料
适合哪些场景
| 场景 | 适合原因 |
|---|---|
| 长系统提示词 | 多次请求中保持不变 |
| 大段知识库上下文 | 用户围绕同一资料连续提问 |
| 固定背景资料 | 规则、合同、产品手册重复使用 |
| 多轮文档问答 | 文档内容稳定，用户问题变化 |
| 大型多模态材料 | 图片或文档材料重复分析 |
长系统提示词缓存
可以把稳定系统提示词、业务规则或文档材料创建为缓存内容，再在生成请求中引用。
text
Create the cache first:
Fixed system prompt + long document content -> cachedContent
Later generation:
cachedContent + current user question -> Gemini response大段知识库上下文缓存
当多个问题围绕同一份文档时，可以缓存文档正文，把用户问题放在后续请求中。
json
{
"cachedContent": "cachedContents/example-cache-id",
"contents": [
{
"parts": [
{ "text": "Answer this: how do I configure an API key?" }
]
}
]
}固定背景资料缓存
固定背景资料应与动态问题分开。不要把当前时间、请求 ID、用户临时状态混入缓存内容，否则会降低复用价值。
如何设计缓存边界
- 把稳定内容放进缓存
- 把每次变化的用户问题放在生成请求里
- 避免把动态字段放进缓存
- 对大型上下文按变化频率拆分缓存
- 根据业务过期时间设置缓存生命周期
成本优化
缓存适合重复使用的长内容。短 prompt 或一次性请求通常不需要缓存。使用前应评估：
- 上下文是否足够长
- 是否会被多次复用
- 多次请求是否能引用同一缓存
- 业务是否能接受缓存创建和存储成本
延迟优化
命中缓存后，长上下文重复处理的开销会降低。对于文档问答、长规则客服、复杂工具定义等场景，可以改善连续请求体验。
注意事项
- 缓存适合稳定内容，不适合每次都变化的输入
- 缓存有生命周期，过期后需要重新创建
- 不要缓存不应长期保存的敏感信息
- 通过 usage 或后台日志观察缓存使用效果