Gemini API Agent Platform 高級特性實戰內容緩存、批量預測、Thinking 推理與 MCP 工具集成【免費下載鏈接】skillsAgent Skills for Google products and technologies項目地址: https://gitcode.com/GitHub_Trending/skills29/skills在 Gemini API in Agent Platform 技能體系中基礎文本生成、多模態輸入、結構化輸出與函數調用解決的是日常對話與單次推理場景而本指南聚焦于生產環境中真正拉開差距的四個高級能力內容緩存Content Caching、批量預測Batch Prediction、思考推理Thinking/Reasoning與MCP 工具集成。讀完本文你將掌握如何用google-genaiPython SDK 為大型文檔建立緩存以降低成本與延遲、異步處理海量數據集、按任務復雜度精確調控模型的思考深度以及通過實驗性的 MCP 支持把本地工具直接接入 Gemini 的自動函數調用鏈路。本文內容以倉庫文檔 references/advanced_features.md 為骨架展開并結合 SKILL.md 中的模型選擇、認證配置與 SDK 規范以及同級參考文檔中的多模態輸入與工具用法進行縱深補充。前置準備SDK、認證與模型選擇高級特性均基于統一的 Gen AI SDKPython 側為google-genai初始化客戶端時不傳參數即可自動拾取環境變量中的認證信息參見 SKILL.md 的 Authentication Configuration 一節。標準企業認證ADCexport GOOGLE_CLOUD_PROJECTyour-project-id export GOOGLE_CLOUD_LOCATIONglobal export GOOGLE_GENAI_USE_ENTERPRISEtrueExpress ModeAPI Keyexport GOOGLE_API_KEYyour-api-key export GOOGLE_GENAI_USE_ENTERPRISEtrue客戶端初始化與本文各示例保持一致from google import genai client genai.Client() # 自動拾取上述環境變量根據 SKILL.md 的模型清單本文示例涉及三個核心模型用途分工如下模型定位備注gemini-3.6-flash快速、均衡的多模態主力模型1M token緩存、批量預測示例的默認模型Thinking 默認MEDIUMgemini-3.1-pro-preview復雜推理、編碼與研究1M token深度思考首選Thinking 默認HIGH/動態gemini-3.5-flash-lite高頻、輕量任務1M tokenThinking 默認MINIMAL注意gemini-2.0-*、gemini-1.5-*、gemini-1.0-*、gemini-pro等舊模型已被標記為遺留legacy并棄用請勿在新代碼中使用生產環境應查閱官方文檔確認穩定的正式版模型。內容緩存Content Caching降低大規模上下文場景的成本與延遲內容緩存用于把大型文檔或長上下文預先處理并復用從而減少重復的輸入 token 計費與處理延遲是 RAG 摘要、長文檔分析、多輪對話等場景下的關鍵成本優化手段。完整的創建與使用示例見 advanced_features.md 的 Content Caching 小節。顯式緩存與隱式緩存隱式緩存默認開啟當請求命中已有緩存時自動獲得成本節省開發者無需任何額外代碼。顯式緩存只有在你被明確要求或明確需要精確控制緩存生命周期時才使用client.caches.create手動創建緩存。創建緩存參數逐項拆解from google import genai from google.genai import types client genai.Client() content_cache client.caches.create( modelgemini-3.6-flash, configtypes.CreateCachedContentConfig( contents[ types.Content( roleuser, parts[ types.Part.from_uri( file_urigs://your-bucket/large.pdf, mime_typeapplication/pdf, ) ], ) ], system_instructionYou are an expert researcher., display_nameexample-cache, ttl86400s, ), )各參數的作用與注意點model緩存與調用時必須使用同一模型緩存無法跨模型復用。contents要緩存的上下文內容。這里通過types.Part.from_uri直接引用 GCS 上的 PDF 文件并聲明mime_typeapplication/pdf同樣的from_uri模式也支持圖片、視頻、音頻等任意多模態對象參見 references/text_and_multimodal.md 的多模態輸入小節。system_instruction隨緩存一起固化的系統指令調用時無需重復傳入。display_name緩存的顯示名稱便于在控制臺與列表接口中識別。ttl存活時間格式為帶單位的時長字符串如86400s即 24 小時。到期后緩存失效需要重新創建通過client.caches.get/client.caches.list可以查詢狀態用client.caches.update可調整 TTL 延長生命周期。消費緩存一行參數接入# Use the cache response client.models.generate_content( modelgemini-3.6-flash, contentsSummarize the pdf, configtypes.GenerateContentConfig(cached_contentcontent_cache.name), )創建成功后只需在GenerateContentConfig中傳入cached_contentcontent_cache.name后續所有攜帶相同上下文的請求都會命中緩存。注意傳入緩存的contents需要與創建緩存時的內容一致通常更簡短如僅提問緩存本體已包含完整文檔上下文。使用建議適合同一大文檔被反復分析/提問的場景一次性短查詢不必緩存。創建緩存本身有一次性成本收益來自后續的緩存命中次數先評估復用頻率再決定是否顯式創建。隱式緩存默認開啟即使不寫任何緩存代碼重復請求也可能自動受益。批量預測Batch Prediction異步處理大規模數據集批量預測面向一次性處理大批量數據的異步工作負載無需逐條實時調用而是把請求文件提交到批次任務Batch Job由平臺在后臺執行任務完成后將結果寫入指定的 GCS 輸出目錄。完整示例見 advanced_features.md 的 Batch Prediction 小節。創建批次任務import time from google import genai from google.genai import types client genai.Client() job client.batches.create( modelgemini-3.6-flash, srcgs://your-bucket/prompts.jsonl, configtypes.CreateBatchJobConfig(destgs://your-bucket/outputs), )src輸入文件路徑格式為 JSONL每一行對應一個獨立的生成請求及其可選配置存放在 GCS 上。dest任務完成后的輸出目錄GCS平臺會將每條請求的結果寫入其中。config通過types.CreateBatchJobConfig統一指定輸出目的地等任務級配置。輪詢等待任務完成completed_states { types.JobState.JOB_STATE_SUCCEEDED, types.JobState.JOB_STATE_FAILED, types.JobState.JOB_STATE_CANCELLED, } while job.state not in completed_states: time.sleep(30) job client.batches.get(namejob.name)代碼的關鍵點在于用一個終態集合驅動輪詢只有JOB_STATE_SUCCEEDED、JOB_STATE_FAILED、JOB_STATE_CANCELLED三種狀態表示任務已結束其余狀態等待、運行等則每 30 秒通過client.batches.get(namejob.name)重新拉取一次任務狀態直到落入終態。這種創建任務 → 輪詢終態 → 拉取結果的異步模式與本技能中模型微調的寫法高度同構在 references/model_tuning.md 中client.tunings.tune之后同樣通過running_states集合與client.tunings.get(name...)以 60 秒為間隔輪詢微調任務直到進入非運行態。理解了批量預測的狀態機就能順帶掌握整個技能的異步任務處理范式。實踐建議批量預測適合離線、非交互的吞吐型任務如歷史數據標注、全量語料翻譯、報表總結不適合需要實時返回的用戶交互。輪詢間隔 30 秒只是示例節奏可按任務規模與成本預期調整生產代碼建議加入最大重試次數與超時退出避免無限循環。任務失敗時可結合job.state與輸出目錄中的錯誤記錄定位失敗請求。Thinking思考推理按復雜度精確調控模型推理深度思考Reasoning/Thinking讓模型在輸出最終答案前先進行內部推理適用于數學、邏輯、代碼與多步規劃類任務。Thinking 默認開啟但不同模型有不同的默認深度且可以通過thinking_level參數顯式調節詳見 advanced_features.md 的 Thinking 小節。各模型默認思考級別gemini-3.1-pro-preview默認HIGH動態深度推理機型gemini-3.6-flash默認MEDIUM均衡型gemini-3.5-flash-lite默認MINIMAL輕量任務優先。四個思考級別級別含義與適用場景MINIMAL約束模型用盡可能少的 token 思考適合低復雜度、無需深度推理的任務注意gemini-3.1-pro-preview不支持該級別LOW使用較少 token 思考適合不要求大量推理的簡單任務MEDIUM均衡方案適合能從推理中受益但無需深層多步規劃的中等復雜度任務HIGH最大化推理深度到達首 token 的時間可能明顯變長但輸出經過更充分的校驗適合高價值復雜問題通過 thinking_level 調節并讀取思考內容from google import genai from google.genai import types client genai.Client() response client.models.generate_content( modelgemini-3.1-pro-preview, contentssolve x^2 4x 4 0, configtypes.GenerateContentConfig( thinking_configtypes.ThinkingConfig( thinking_leveltypes.ThinkingLevel.HIGH, ) ), ) # Access thoughts if returned for part in response.candidates[0].content.parts: if part.thought: print(fThought: {part.text}) else: print(fFinal Answer: {part.text})實現要點thinking_configtypes.ThinkingConfig(thinking_leveltypes.ThinkingLevel.HIGH)顯式指定推理深度返回內容中推理過程與最終答案都作為content.parts中的獨立 part 返回通過part.thought布爾標記區分True表示思考片段False表示最終答案若模型未返回思考內容例如某些輕量級別下循環會直接打印最終答案代碼無需改動即可安全降級。選擇建議簡單事實查詢 / 高頻低價值請求MINIMAL或LOW換取更低延遲與成本常規問答、中等推理MEDIUM保持均衡數學證明、代碼評審、復雜規劃HIGH接受更長的首 token 延遲換取輸出質量需要權衡時可先以默認級別運行再根據任務的實際收益逐步調整。MCP 支持實驗性把本地 MCP 服務器直接作為模型工具Model Context ProtocolMCP為模型與外部工具之間提供了標準化的通信協議。本技能內置的 MCP 支持屬于實驗性特性你可以把本地運行的 MCP 服務器stdio 方式直接作為工具傳給 Gemini模型會通過自動函數調用automatic function calling在需要時自動調用這些工具。完整示例見 advanced_features.md 的 MCP 小節。完整示例查詢倫敦天氣import os import asyncio from datetime import datetime from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from google import genai from google.genai import types client genai.Client() # Create server parameters for stdio connection server_params StdioServerParameters( commandnpx, # Executable args[-y, philschmid/weather-mcp], # MCP Server envNone, # Optional environment variables ) async def run(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # Prompt to get the weather for the current day in London. prompt fWhat is the weather in London in {datetime.now().strftime(%Y-%m-%d)}? # Initialize the connection between client and server await session.initialize() # Send request to the model with MCP function declarations response await client.aio.models.generate_content( modelgemini-3.6-flash, contentsprompt, configtypes.GenerateContentConfig( tools[ session # uses the session, will automatically call the tool using automatic function calling ], ), ) print(response.text) # Start the asyncio event loop and run the main function asyncio.run(run())關鍵環節拆解MCP 客戶端側配置StdioServerParameters(commandnpx, args[-y, philschmid/weather-mcp], envNone)聲明通過 stdio 啟動的 MCP 服務器env可用于傳入可選的環境變量。建立會話stdio_client(server_params)啟動子進程并建立雙向管道ClientSession(read, write)在其上建立 MCP 會話await session.initialize()完成客戶端與服務器之間的握手初始化。會話即工具將session直接放入GenerateContentConfig(tools[session])——這是本特性的核心抽象SDK 會自動把 MCP 服務器暴露的函數聲明轉換成模型可用的工具并在推理過程中自動完成工具調用automatic function calling。異步客戶端由于 MCP 會話天然是異步的示例使用client.aio.models.generate_content走 Gen AI SDK 的 async 接口并通過asyncio.run(run())驅動事件循環。與函數調用的關系MCP 支持可以看作 references/structured_and_tools.md 的 Function Calling 小節 的協議化延伸原生函數調用把 Python 函數直接作為tools傳入適合代碼內自有的工具而 MCP 路徑則把任意符合協議的外部服務器如上述天氣服務接入同一套自動調用鏈路工具聲明、參數解析與執行由 MCP 層與 SDK 協作完成模型側的使用方式tools[...]保持一致。注意事項該特性為實驗性接口與行為可能隨版本演進發生變化生產接入前需驗證目標 SDK 版本的支持情況需要安裝 MCP Python 客戶端依賴mcp包以提供ClientSession/stdio_client本地 MCP 服務器必須可用如npx可執行且包可拉取否則初始化會失敗。最佳實踐與注意事項匯總緩存優先于一切重復上下文隱式緩存默認開啟先跑通再按需顯式創建顯式緩存務必設置合理的ttl并復用同一模型。異步任務統一走狀態機輪詢批量預測、模型微調均采用創建 → 輪詢終態集合 → 取結果模式為輪詢補充超時與最大重試防止死循環。思考級別按任務復雜度梯度化MINIMAL/LOW/MEDIUM/HIGH對應從低到高的延遲與成本默認值已是各模型的合理起點僅在明確收益時上調。MCP 支持定位為實驗特性適合快速把外部工具接入 Gemini但生產環境需額外關注協議版本兼容與進程生命周期管理。遵循統一 SDK 約束本技能要求統一使用google-genaiPython等新一代 SDK不要混用已棄用的google-cloud-aiplatform、google-cloud/vertexai、google-generativeai詳見 SKILL.md 的 SDK 說明。多模態上下文可復用同一套 APIPart.from_uri既可服務于緩存大 PDF也可服務于圖片/視頻/音頻輸入見 text_and_multimodal.md理解它就能打通本技能的大多數數據接入場景。相關文檔導航技能總覽與模型、認證、SDK 規范SKILL.md本文主題權威出處references/advanced_features.md文本與多模態生成含流式、Chat、Part.from_uri多模態輸入references/text_and_multimodal.md結構化輸出、函數調用、Search Grounding、代碼執行、URL 上下文references/structured_and_tools.md實時雙向流式 Live API同屬異步編程范式references/live_api.md模型微調與批量預測同構的異步輪詢模式references/model_tuning.mdEmbeddings、安全設置等其余能力references/embeddings.md、references/safety.md以上四個高級特性覆蓋了從單次生成走向生產級規模化使用的完整路徑用緩存壓縮成本、用批量預測消化吞吐、用 Thinking 控制質量、用 MCP 打通外部工具生態配合本技能的基礎能力文檔即可構建完整的企業級 Gemini 應用。【免費下載鏈接】skillsAgent Skills for Google products and technologies項目地址: https://gitcode.com/GitHub_Trending/skills29/skills創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考