Gemini API 上下文缓存(Context Caching)与 Files API 解析长视频音频实战

用 Gemini API 反复追问同一段一小时会议录像或几百页 PDF,每次重传太慢又烧钱怎么办?本文按官方 google-genai Python SDK 文档详解 Files API 状态轮询、显式上下文缓存创建、TTL 管理与清理代码。

NNathaniel bigo··原创首发·AI 辅助撰写
8 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

  1. 传大体积音视频或长 PDF 必走 Files API(client.files.upload):单次内联请求塞不下大媒体文件;通过 Files API 上传的文件会在谷歌服务端免费暂存最长 48 小时,拿到文件句柄即可反复引用。
  2. 视频上传完不能马上提问,必须先轮询等待 PROCESSING 结束:长视频需要几秒到几十秒提取帧与音轨,等 state.name 变为就绪状态再往下走才不会报错。
  3. 只问一两次别开缓存;围绕同一大文件连问五次以上必开 Context Caching:把几十万 Token 的视频和系统指令锁进 client.caches.create,后续追问只传几十字问题并附带 cached_content=cache.name,首字延迟和输入 Token 单价双双大降。
  4. 用完随手删缓存或设短 ttl:显式缓存默认存活 1 小时(3600s) 并按存活时长收存储费,批处理跑完立即调 client.caches.delete 释放最划算。
  5. 谷歌账号与多工具订阅直达入口:体验 Jules 异步提 PR、Stitch 生 UI 与 AI Studio 需登录合规个人谷歌账号,缺号可前往本站 谷歌账号购买页 选购 2FA 谷歌邮箱成品号;跨平台开发与设计订阅对比见 AI 会员充值中心。

Files API 配合上下文缓存省钱四步

图:本站根据 Gemini API 官方缓存文档 整理的四步流程示意图

本文根据 Google Gemini API 官方文档(ai.google.dev/gemini-api/docs/caching、docs/files)整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。

适用于谁

  • 要用代码解析几十分钟的课程录像、播客录音或整本英文技术手册,并围绕这份材料连续追问十几个问题的开发者;
  • 刚上传完视频立刻调生成接口却报错失败,不知道视频在后台有 PROCESSING 转码状态的工程师;
  • 想搞懂什么时候该开显式缓存(Context Caching)、怎么设 ttl 才不会被闲置存储费反撸的人。

一、完整 Python 实战代码(上传轮询 → 建缓存 → 多轮追问 → 释放)

请认准官方现行维护的新版 google-genai SDK(安装命令 pip install google-genai,基础环境准备见 Gemini API Python 快速入门 与 Gemini API Key 获取教程):

python
import pathlib
import time
from google import genai
from google.genai import types

# 初始化客户端(默认自动读取环境变量 GEMINI_API_KEY)
client = genai.Client(http_options={"api_version": "v1beta"})

# 1. 通过 Files API 上传长视频或大体积 PDF
video_path = pathlib.Path("tech_keynote_60min.mp4")
uploaded_file = client.files.upload(file=video_path)

# 2. 轮询等待音视频后台转码完成(关键防报错步骤)
while uploaded_file.state.name == "PROCESSING":
    time.sleep(3)
    uploaded_file = client.files.get(name=uploaded_file.name)

if uploaded_file.state.name != "ACTIVE":
    raise RuntimeError(f"文件处理未就绪,当前状态: {uploaded_file.state.name}")

# 3. 创建显式上下文缓存(存活期设为 10 分钟 = 600s)
model_id = "models/gemini-2.5-flash"
cache = client.caches.create(
    model=model_id,
    config=types.CreateCachedContentConfig(
        display_name="keynote_video_cache",
        system_instruction="你是严谨的会议纪要分析助手,给出结论时请一并标注视频中的时间戳(MM:SS)。",
        contents=[uploaded_file],
        ttl="600s",
    ),
)

# 4. 多轮追问直接复用 cache.name,无需重传整部视频
for question in [
    "按章节列出整场演讲的核心发布要点与对应时间戳。",
    "演讲者在演示数据库架构阶段提到了哪些性能瓶颈数据?",
]:
    resp = client.models.generate_content(
        model=model_id,
        contents=question,
        config=types.GenerateContentConfig(cached_content=cache.name),
    )
    print(resp.text)

# 5. 任务全部跑完后主动删除缓存,立即停止计算存储时长费
client.caches.delete(name=cache.name)

如果你需要准备用于登录 Google AI Studio 开通 API 项目的个人谷歌账号,或对比多厂商开发会员方案,可分别查看本站 谷歌账号购买说明 与 AI 会员充值总览页。

二、什么时候开显式缓存最省钱(成本账本对比)

普通每次重传与显式上下文缓存对比

图:本站根据 Gemini API 官方定价与缓存说明 整理的对比示意图

为什么不是所有请求都无脑套一层 caches.create?算清下面三条规则你就不会花冤枉钱:

  1. 有最低 Token 起步门槛:官方文档规定,待缓存的内容总长度必须达到对应模型的最低 Token 下限(通常几千到几万 Token 不等,短文本两三百字调 caches.create 会直接报参数不满足门槛错误)。
  2. 存储时长费 vs 命中折扣费的平衡点:显式缓存由两部分计费——「缓存命中时的折扣输入单价」加上「按每小时每百万 Token 计算的驻留存储费」(最新费率口径见 Gemini API 官方价格详解)。如果一段长视频你只打算让它总结一次就再也不问了,直接把 uploaded_file 传给 generate_content 就行,建缓存反而多付一小时存储费;反之如果做成交互式问答机器人让用户连续问十几个细节,开缓存能立省大半账单。
  3. 动态续期与按需清理:如果用户还在持续追问、眼看 ttl 快到期了,可以通过 client.caches.update 延长过期时间;一旦会话关闭,立刻调 delete 销毁。若在免费层测试时遇到缓存配额受限报错,可对照 Gemini API 免费层速率与计费升级说明 检查项目档位。你也可以对比另一家主流接口的缓存设计思路,见 Claude API 提示词缓存教程。

常见问题

问:Files API 上传的文件过了 48 小时会自动消失吗?

答:会的。官方明确说明 Files API 是为模型推理设计的临时文件中转区,不是永久云盘,上传满 48 小时后服务端会自动清理,长期业务原件请保存在你自己的对象存储桶里。

问:调用 generate_content 引用缓存时,还能在 GenerateContentConfig 里再改一次 system_instruction 吗?

答:不能重复覆盖。系统指令(system_instruction)和固定工具声明应当在创建缓存(CreateCachedContentConfig)那一刻一并封进去,后续每次生成请求只传新增的用户提问文本。

问:为什么创建缓存时提示当前免费层不支持或报 429?

答:部分模型的显式上下文缓存能力或高并发缓存总容量仅对已开启付费结算(Pay-as-you-go)的项目开放,先去 AI Studio Dashboard 检查项目是否已绑定有效计费层级。

问:注册谷歌账号卡在手机号验证,或者国内没有外币卡怎么配齐 AI 开发工具?

答:本站提供支持支付宝、微信支付与 AlipayHK 自动发卡的 谷歌邮箱成品号(登录加固步骤见 谷歌账号说明页),同时支持自助获取兑换码开通 ChatGPT Plus 与 Claude Code 订阅,支持开具增值税发票。

相关教程

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同模型

  1. 01

    用 Google Takeout 单独备份导出 NotebookLM 笔记本与 Gemini 记录:只勾选指定服务不下载整个云端硬盘的步骤

    想把 NotebookLM 里的几十个研究笔记本、来源副本与音频概览,连同 Gemini 聊天记录一起备份到本地,又怕 Google Takeout 把整个云端硬盘和相册全打包?本文讲清先取消全选、精准勾选两项服务、解压目录查看与跨号迁移的做法。

    Gemini0
  2. 02

    Google Workspace 企业/教育版管理员怎么在后台给成员开启 Gemini 应用、NotebookLM 与设置年龄访问权限

    团队成员或学校师生登录 Google Workspace 账号时提示无权使用 Gemini 或打不开 NotebookLM?本文按 Google 管理控制台官方文档整理服务开关路径、组织部门(OU)与群组放行、18 岁年龄访问权限设置及对话保留合规配置。

    Gemini0
  3. 03

    安卓手机默认助手换成 Gemini 后设闹钟、发短信或控制智能家居失灵怎么办:Workspace 与实用程序扩展开启步骤

    安卓手机把默认语音助手从 Google Assistant 换成 Gemini 后,喊它定闹钟、开手电筒、发短信或开关智能灯全都没反应?本文按官方帮助中心整理实用程序(Utilities)、Google Home 与 Workspace 关联应用开启步骤及锁屏放行设置。

    Gemini0
  4. 04

    Gemini 写长代码或长文档到一半突然停住、格式截断怎么无缝续写:锚点接续指令与 Canvas 分块修改技巧

    让 Gemini 写几百行代码或万字长文时经常写到一半突然停住、Markdown 代码块没闭合,直接回「继续」又重头抄一遍?本文整理字面锚点续写指令、代码块防乱码补齐法与 Canvas 局部圈选修改工作流。

    Gemini0
  5. 05

    NotebookLM 中文音频播客(Audio Overview)高阶玩法:用自定义引导词控制对谈深度、受众水平与重点章节(附模板)

    NotebookLM 生成的中文音频播客总是泛泛而谈、漏掉核心章节或夹杂生僻英文缩写?本文按官方帮助中心整理来源勾选过滤、四种播客格式搭配与三维自定义引导词写法,附 4 套可直接复制的中文控场模板。

    Gemini0
  6. 06

    NotebookLM 添加 YouTube 视频、网页或扫描版 PDF 提示「无法导入来源」怎么办:无字幕、反爬与纯图 PDF 逐项解决

    往 NotebookLM(Gemini Notebook)塞 YouTube 链接、外文网页或扫描教材时总是亮红叹号提示无法导入来源?本文按官方帮助中心逐项排查无字幕视频、反爬动态页与加密纯图 PDF 的替代导入步骤。

    Gemini0

同产品的其他教程

  1. 01

    用 ChatGPT 速读英文产品手册、开源文档与 GitHub Issue 并沉淀团队中文内训手册

    团队引入海外 SaaS 工具或开源框架时,全英文文档晦涩冗长、真正的坑全藏在几十页 GitHub Issue 讨论里。本文分享速读拆解英文手册、归类 Issue 排障库以及重构团队中文内训 SOP 的完整实战流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 写油猴脚本(Tampermonkey)与浏览器书签小工具解决网页繁琐重复操作实战

    每天在后台系统里重复勾选几十个复选框、手工复制网页表格或清理遮挡阅读的侧边栏,既枯燥又浪费时间。本文分享不会写 JS 也能用 F12 配合 ChatGPT 写出油猴脚本与书签小工具的完整实战流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 写高质量 SQL 窗口函数(RANK / LAG / SUM OVER)做留存与漏斗分析实战

    做用户留存率、复购间隔与有序转化漏斗时,多层自连接既难读又拖垮数据库,窗口函数则是高效解法。本文整理数据库方言喂数规范、CTE 分层提示词以及用内置沙盒先验证再上线的完整实战流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 连接 Canva、Figma、Linear、Jira、Dropbox 等第三方应用搜不到数据或授权失效怎么办

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 后,明明显示已连接却搜不到文件工单,或老提示授权失效怎么办?本文拆解账号错绑、OAuth 范围漏选、权限继承与管理员拦截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  6. 06

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~