Gemini 上下文缓存
- Gemini 的缓存有两种形态：隐式与显式
- 隐式由服务端自动判断，无需操作
- 显式需要先创建缓存对象，再按对象引用，适合极大且反复使用的内容
两种形态的区别
| 形态 | 创建方式 | 适合场景 | 有效期 |
|---|---|---|---|
| 隐式 | 自动，无需操作 | 短时间内的连续同类请求 | 较短，由服务端管理 |
| 显式 | 调用创建接口 | 超长文档、视频、音频反复问 | 显式指定，按小时计 |
| Form | How to create | Best for | Lifetime |
|---|---|---|---|
| Implicit | Automatic, no action needed | Consecutive similar requests in a short window | Short, managed by the server |
| Explicit | Call the create endpoint | Repeated questions about very long documents, video, or audio | Set explicitly, measured in hours |
隐式缓存
只要连续请求的前缀一致，服务端会自动复用，无需任何参数。响应里 usageMetadata 会给出命中量。
命中缓存的 token 数。未命中时不出现。
As long as consecutive requests share the same prefix, the server reuses it automatically with no parameters. usageMetadata in the response reports the hit count.
Tokens that hit the cache. Absent when there's no hit.
显式缓存
显式缓存分两步：先创建缓存拿一个 name，之后请求里引用这个 name。
要缓存的模型 ID。
要缓存的内容，结构与 generateContent 的 contents 一致。可以是长文、图片或音视频。
有效期，写成 3600s 这样的时长字符串。到期后缓存自动删除。
便于识别的名字，仅用于管理，不参与推理。
Explicit caching is two steps: create the cache to get a name, then reference that name in later requests.
The model ID to cache.
The content to cache; the structure matches contents in generateContent. Can be long text, images, or audio/video.
Lifetime, as a duration string such as 3600s. The cache is deleted automatically when it expires.
An easy-to-recognize name, used only for management and not in inference.
使用缓存
在 generateContent 请求里传 cachedContent，填创建时返回的完整 name：
{
"cachedContent": "cachedContents/abc123xyz",
"contents": [
{ "parts": [{ "text": "这份文档的核心结论是什么？" }] }
]
}引用缓存时，contents 里只需要放新增的问题部分。如果把已经缓存的内容再贴一遍，反而可能让请求失败或重复计费。
Pass cachedContent in the generateContent request, filled with the full name returned at creation:
{
"cachedContent": "cachedContents/abc123xyz",
"contents": [
{ "parts": [{ "text": "What is the core conclusion of this document?" }] }
]
}When referencing a cache, contents should contain only the new question. Pasting the already-cached content again may make the request fail or be billed twice.
计费方式
显式缓存按「缓存存储时长」和「缓存内容大小」计费，与按 token 计费的推理分开算。命中的推理请求，输入侧按折扣计价。
缓存内容越大、使用次数越多，摊薄下来越划算。如果只问一次，显式缓存反而更贵。
Explicit caching is billed by cache storage duration and cached content size, separate from per-token inference billing. Inference requests that hit are billed at a discount on the input side.
The larger the cached content and the more often it's used, the better it amortizes. For a single question, explicit caching is actually more expensive.
使用示例
创建显式缓存
先把长内容提交成缓存，拿到 cachedContent 名称。这一步本身不计推理费，只按存储时长计费。
引用缓存发问
生成内容时用 cachedContent 字段引用上一步返回的名称，contents 里只放这次的新问题。
依赖隐式缓存
不显式创建缓存时，Gemini 会在服务端自动复用相同前缀。同一次会话里连续追问，通常能自动命中，不需要额外参数。
Create an explicit cache
Submit the long content as a cache first and get the cachedContent name. This step isn't billed as inference, only as storage time.
Query with the cache
When generating, reference the name returned above via the cachedContent field, with only the new question in contents.
Rely on implicit caching
Without creating a cache explicitly, Gemini reuses identical prefixes server-side automatically. Consecutive follow-up questions in one session usually hit without extra parameters.