企业官网建设流程全解析

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 SDK（Python 侧为google-genai），初始化客户端时不传参数即可自动拾取环境变量中的认证信息，参见 SKILL.md 的 Authentication & Configuration 一节。

标准企业认证（ADC）：

export GOOGLE_CLOUD_PROJECT='your-project-id' export GOOGLE_CLOUD_LOCATION='global' export GOOGLE_GENAI_USE_ENTERPRISE=true

Express Mode（API Key）：

export GOOGLE_API_KEY='your-api-key' export GOOGLE_GENAI_USE_ENTERPRISE=true

客户端初始化与本文各示例保持一致：

from google import genai client = genai.Client() # 自动拾取上述环境变量

根据 SKILL.md 的模型清单，本文示例涉及三个核心模型，用途分工如下：

注意：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( model="gemini-3.6-flash", config=types.CreateCachedContentConfig( contents=[ types.Content( role="user", parts=[ types.Part.from_uri( file_uri="gs://your-bucket/large.pdf", mime_type="application/pdf", ) ], ) ], system_instruction="You are an expert researcher.", display_name="example-cache", ttl="86400s", ), )

各参数的作用与注意点：

• model：缓存与调用时必须使用同一模型，缓存无法跨模型复用。
• contents：要缓存的上下文内容。这里通过types.Part.from_uri直接引用 GCS 上的 PDF 文件并声明mime_type="application/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( model="gemini-3.6-flash", contents="Summarize the pdf", config=types.GenerateContentConfig(cached_content=content_cache.name), )

创建成功后只需在GenerateContentConfig中传入cached_content=content_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( model="gemini-3.6-flash", src="gs://your-bucket/prompts.jsonl", config=types.CreateBatchJobConfig(dest="gs://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(name=job.name)

代码的关键点在于用一个终态集合驱动轮询：只有JOB_STATE_SUCCEEDED、JOB_STATE_FAILED、JOB_STATE_CANCELLED三种状态表示任务已结束，其余状态（等待、运行等）则每 30 秒通过client.batches.get(name=job.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，轻量任务优先。

四个思考级别

通过 thinking_level 调节并读取思考内容

from google import genai from google.genai import types client = genai.Client() response = client.models.generate_content( model="gemini-3.1-pro-preview", contents="solve x^2 + 4x + 4 = 0", config=types.GenerateContentConfig( thinking_config=types.ThinkingConfig( thinking_level=types.ThinkingLevel.HIGH, ) ), ) # Access thoughts if returned for part in response.candidates[0].content.parts: if part.thought: print(f"Thought: {part.text}") else: print(f"Final Answer: {part.text}")

实现要点：

• thinking_config=types.ThinkingConfig(thinking_level=types.ThinkingLevel.HIGH)显式指定推理深度；
• 返回内容中，推理过程与最终答案都作为content.parts中的独立 part 返回，通过part.thought布尔标记区分：True表示思考片段，False表示最终答案；
• 若模型未返回思考内容（例如某些轻量级别下），循环会直接打印最终答案，代码无需改动即可安全降级。

选择建议

• 简单事实查询 / 高频低价值请求：MINIMAL或LOW，换取更低延迟与成本；
• 常规问答、中等推理：MEDIUM保持均衡；
• 数学证明、代码评审、复杂规划：HIGH，接受更长的首 token 延迟换取输出质量；
• 需要权衡时可先以默认级别运行，再根据任务的实际收益逐步调整。

MCP 支持（实验性）：把本地 MCP 服务器直接作为模型工具

Model Context Protocol（MCP）为模型与外部工具之间提供了标准化的通信协议。本技能内置的 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( command="npx", # Executable args=["-y", "@philschmid/weather-mcp"], # MCP Server env=None, # 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 = f"What 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( model="gemini-3.6-flash", contents=prompt, config=types.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())

关键环节拆解

1. MCP 客户端侧配置：StdioServerParameters(command="npx", args=["-y", "@philschmid/weather-mcp"], env=None)声明通过 stdio 启动的 MCP 服务器，env可用于传入可选的环境变量。
2. 建立会话：stdio_client(server_params)启动子进程并建立双向管道；ClientSession(read, write)在其上建立 MCP 会话；await session.initialize()完成客户端与服务器之间的握手初始化。
3. 会话即工具：将session直接放入GenerateContentConfig(tools=[session])——这是本特性的核心抽象，SDK 会自动把 MCP 服务器暴露的函数声明转换成模型可用的工具，并在推理过程中自动完成工具调用（automatic function calling）。
4. 异步客户端：由于 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可执行且包可拉取），否则初始化会失败。

最佳实践与注意事项汇总

1. 缓存优先于一切重复上下文：隐式缓存默认开启，先跑通再按需显式创建；显式缓存务必设置合理的ttl并复用同一模型。
2. 异步任务统一走状态机轮询：批量预测、模型微调均采用"创建 → 轮询终态集合 → 取结果"模式，为轮询补充超时与最大重试，防止死循环。
3. 思考级别按任务复杂度梯度化：MINIMAL/LOW/MEDIUM/HIGH对应从低到高的延迟与成本，默认值已是各模型的合理起点，仅在明确收益时上调。
4. MCP 支持定位为实验特性：适合快速把外部工具接入 Gemini，但生产环境需额外关注协议版本兼容与进程生命周期管理。
5. 遵循统一 SDK 约束：本技能要求统一使用google-genai（Python）等新一代 SDK，不要混用已弃用的google-cloud-aiplatform、@google-cloud/vertexai、google-generativeai，详见 SKILL.md 的 SDK 说明。
6. 多模态上下文可复用同一套 API：Part.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.md
• Embeddings、安全设置等其余能力：references/embeddings.md、references/safety.md

以上四个高级特性覆盖了从"单次生成"走向"生产级规模化使用"的完整路径：用缓存压缩成本、用批量预测消化吞吐、用 Thinking 控制质量、用 MCP 打通外部工具生态，配合本技能的基础能力文档即可构建完整的企业级 Gemini 应用。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills