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 條評論

登入 後參與評論

還沒有評論,來搶沙發~