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），仅供参考