结论先说
- 隐式缓存在 Gemini 2.5 及更新模型上默认自动开启,零代码配置、无额外存储费:只要重复前缀达到模型最低 token 门槛且命中服务端缓存,就会自动按缓存折扣价结算,但不承诺每次必中。
- 显式缓存需要手动创建缓存对象并设置
ttl,保证命中折扣但按时长收存储费:注意 Interactions API 与 Gemini 4 系列不支持显式缓存,只能在 Gemini 3 与 Gemini 2.5 模型上通过generateContent(v1beta)使用。 - 最低输入门槛按代际划分:Gemini 2.5 Flash / Pro 隐式缓存门槛为
2,048tokens,Gemini 3 系列与 Gemini 4(Hydrogen / Argon / Carbon)门槛为4,096tokens。 - 提高隐式命中率最有效的做法是「固定内容放最前、动态提问放最后」,并通过响应里的
total_cached_tokens或usage_metadata核对实际命中量。 - 谷歌账号准备与多工具订阅入口:使用 Gemini、Google AI Studio 与 Antigravity 需具备符合地区与年龄要求的个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含带 2FA 的 谷歌邮箱成品号),跨平台付费订阅总览见 AI 会员充值中心。

图:本站根据 Google Gemini API 文档:Context caching 整理的示意图
本文根据 Google Gemini API 官方文档《Context caching》《Gemini Developer API Pricing》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 每次请求都要重复传入长系统指令、整本 PDF、大型代码库或长视频,想降低 Gemini API 输入 token 成本的开发者;
- 分不清隐式缓存(Implicit caching)与显式缓存(Explicit caching)在 Gemini 2.5、Gemini 3 与 Gemini 4 上的支持差异的人;
- 想查清缓存命中字段在哪看、显式缓存存储费怎么算以及
ttl怎么设置的工程师。
一、隐式缓存与显式缓存有什么区别
按 Google 官方文档定义,两套机制在接口范围、模型支持和计费逻辑上有明确边界:
| 对比维度 | 隐式缓存(Implicit caching) | 显式缓存(Explicit caching) |
|---|---|---|
| 开启方式 | 默认自动开启,无需改代码 | 需调用 caches.create 手动创建并传引用名 |
| 支持接口 | Interactions API 与 generateContent 均支持 | 仅支持 generateContent(v1beta),Interactions API 不支持 |
| 支持模型 | Gemini 2.5、Gemini 3 与 Gemini 4 全系 | 仅受支持的 Gemini 3 与 Gemini 2.5 模型(Gemini 4 不支持) |
| 命中与费用 | 命中即省输入费,不收存储费,无必中承诺 | 存活期内保证享受缓存读取价,另按时长收缓存存储费 |
| 命中查看字段 | usage.total_cached_tokens 或 usage_metadata | usage_metadata.cached_content_token_count |
如果你同时也在对比 Anthropic 的缓存计费规则,可参考站内的 Claude 提示词缓存(Prompt Caching)入门。
二、隐式缓存门槛与提高命中率写法
隐式缓存不需要额外 API 调用,但必须跨过官方规定的最低输入 token 门槛才可能触发:
- Gemini 2.5 Flash / Gemini 2.5 Pro:最低
2,048tokens; - Gemini 3.1 Pro Preview / 3.6 Flash / 3.8 Flash:最低
4,096tokens; - Gemini 4 Hydrogen / Argon / Carbon:最低
4,096tokens。
多轮与智能体循环细节:官方文档特别注明,在 Gemini 4 的多轮对话或 Agent 工具循环中,只有当新一轮请求相比上一轮至少新增 2,050 tokens(模型输出、思考过程和函数调用返回结果均计入)时,系统才会把上一轮完整请求缓存下来;若单轮增量不足 2,050 tokens,末尾部分会按标准输入单价重算。
写法建议:
- 把固定不变的系统设定、背景知识库、少样本示例(Few-shot)统一放在提示词最开头;
- 把每次变化的用户提问、当前时间戳放在最末尾,避免动到前半段导致前缀失效;
- 同批次任务尽量在短时间内连续发送。
初次获取密钥与安装 SDK 的步骤见 Gemini API Key 怎么获取 与 Gemini API Python 调用教程。若你还没有用于登录 Google AI Studio 开通 API 的账号,可在本站查看 谷歌账号说明。
谷歌开发账号与主力编程订阅提示:若当前账号卡在地区不支持、手机核验或工作空间限制,可在本站选购已配置两步验证的 谷歌账号成品号(即时发货,质保首登,到手请按指引先登后改密);日常搭配主力模型开发,也可同步了解免境外卡自助兑换的 ChatGPT Plus 与 Claude Pro。
三、显式缓存创建、TTL 设置与省费测算
在 Gemini 2.5 或 Gemini 3 模型上反复追问同一份超大视频或长文档,且希望锁死命中率时,可通过 google-genai SDK 手动创建显式缓存并指定 ttl(默认通常为 3600s 即 1 小时):
python
from google import genai
from google.genai import types
client = genai.Client()
# 1. 上传大文件并创建显式缓存,设置 TTL 为 600 秒(10 分钟)
doc_file = client.files.upload(file="manual.pdf")
cache = client.caches.create(
model="gemini-2.5-flash",
config=types.CreateCachedContentConfig(
display_name="product_manual_cache",
system_instruction="请严格依据手册原文回答问题。",
contents=[doc_file],
ttl="600s",
),
)
# 2. 发起请求时直接引用缓存名称
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="列出第三章提到的所有故障代码",
config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
print(response.usage_metadata)
TTL 与省费控制要点:
- 按实际业务窗口设
ttl:显式缓存按「缓存 token 数 × 存活时长」计收存储费。如果一批批处理任务 15 分钟就能跑完,就把ttl设为"900s",或在任务结束时主动调用client.caches.delete(name=cache.name)立即停止计费; - 中途续期:若用户还在持续提问,可调用
client.caches.update传入新的ttl或expire_time延长有效期,无需重新上传文本; - 核对免费层与付费层:Google AI Studio 免费层不支持付费缓存特性,具体每百万 token 基准价与预充值方式见 Gemini API 价格 与 Gemini API 怎么收费。

图:本站根据 Google Gemini API 文档:Context caching 整理的示意图
常见问题
问:为什么我在 Gemini 4 或 Interactions API 里调 caches.create 报错?
答:官方文档明确说明,Interactions API 与 Gemini 4 全系模型均不支持显式缓存,它们统一走自动生效的隐式缓存。只有切换到 generateContent 接口并选用受支持的 Gemini 3 或 2.5 模型才能建显式缓存。
问:输入已经超过 4,096 tokens,为什么 total_cached_tokens 还是 0?
答:第一次发送某段新前缀时需要先写入缓存,第二条及后续共享相同前缀的请求才可能命中;另外如果在提示词开头塞入了动态时间戳或随机 ID,会导致前缀从第一个变动位置起全部失效。
问:显式缓存一定比隐式缓存更省钱吗?
答:不一定。如果一份大文档建了 2 小时显式缓存,期间只查了 1 次,省下的输入差价可能还抵不上 2 小时的存储费。低频稀疏请求直接依赖免费的隐式缓存更划算,高频密集查询才适合开显式缓存。
问:没有可用的个人谷歌账号,或者同时想开其他主流 AI 会员怎么办?
答:本站提供即买即发的 谷歌邮箱成品号(登录方法见 谷歌账号购买页),同时支持支付宝、微信支付与 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服务,实时价格与质保细则以各商品页说明为准。
相关教程
- Gemini API 价格:各模型每百万 tokens 多少钱、免费层和付费层差在哪
- Gemini API 怎么收费:按 token 计费、预付费充值(Prepay)与支出上限设置
- Gemini API Python 调用教程:安装 google-genai SDK、流式输出、多轮对话
- Claude 提示词缓存(Prompt Caching)入门:缓存时间、价格倍率与命中率
参考资料
- Google Gemini API 官方文档:Context caching(Interactions API) — https://ai.google.dev/gemini-api/docs/caching
- Google Gemini API 官方文档:Context caching(generateContent) — https://ai.google.dev/gemini-api/docs/generate-content/caching
- Google Gemini API 官方文档:Gemini Developer API Pricing — https://ai.google.dev/gemini-api/docs/pricing
0 条评论
还没有评论,来抢沙发~