基于 MCP 的 Gemini 多模型智能编排实战mcp_orchestration_app 客户端与服务端源码全解析【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai导读本文以 gemini/mcp/mcp_orchestration_app/README.md 为骨架深入剖析 Google Cloud 生成式 AI 示例仓库中的 MCP 多模型编排应用它用便宜的 Gemini 模型如 Gemma充当客户端大脑通过Model Context ProtocolMCP把 Gemini 2.0 Flash Lite、Gemini 2.0 Flash、Gemini 2.5 Pro 等专用模型以及 Google Cloud Translation 翻译服务封装成一个个可调用的工具由客户端根据对话上下文自主决定调用哪个模型。读完本文你将掌握如何搭建这套 MCP 客户端/服务端环境、如何配置servers_config.json与.env、服务端如何用 FastMCP 暴露工具、客户端如何解析模型输出的 JSON 并编排工具调用以及每一环的源码级实现原理。项目定位用 MCP 弥合对话与工具的鸿沟MCP 的核心思想是把语言模型的能力拆分成结构化、可复用的工具tool让客户端应用在对话中根据上下文智能决定何时调用、调用哪个工具。本项目的目标正是把 Gemini 家族的多个模型能力以 MCP 工具的形式暴露出来形成一套成本敏感的模型编排方案由便宜的 Gemma 模型担任客户端调度器由更专业的模型作为服务端执行器从而在具体业务场景下获得既专业又经济的组合。从代码结构看这个应用由两个进程构成src 目录组件文件职责MCP 服务端gemini_server.py用 FastMCP 把多个 Gemini 模型与翻译 API 封装为工具MCP 客户端gemini_client.py用 Gemma 等模型驱动对话解析工具调用并执行服务端配置servers_config.json声明服务端脚本路径与注入的环境变量环境变量模板example.env项目 ID、区域、模型名、API Key 等配置说明依赖清单requirements.txt客户端与服务端所需的全部 Python 依赖开始前的准备Prerequisites按 README 的说明运行本项目需要满足以下前提Python 3.7项目依赖asyncio、类型注解等特性需使用 3.7 或更高版本pipPython 包安装器Google Cloud 项目本项目依赖 Gemini 模型需要启用Vertex AI API与Cloud Translation API的 Google Cloud 项目凭据配置为 Google Cloud 项目配置合适的认证方式——可以设置环境变量也可以使用服务账号。结合 requirements.txt 可以看到实际依赖包括python-dotenv加载.env、mcp官方 MCP 库、google-genaiGemini 客户端 SDK、google-cloud-translate翻译 API 客户端、nest_asyncio嵌套事件循环支持以及uvicorn、requests等python-dotenv1.0.0 requests2.31.0 mcp uvicorn0.32.1 google-genai nest_asyncio google-cloud-translate搭建本地环境Setup1. 获取代码并创建虚拟环境git clone https://gitcode.com/GitHub_Trending/ge/generative-ai cd generative-ai/gemini/mcp/mcp_orchestration_app python3 -m venv .venv source .venv/bin/activate2. 安装依赖pip install -r requirements.txt3. 配置环境变量.env在项目根目录创建.env文件参考 example.env 填入真实信息GOOGLE_CLOUD_PROJECTyour-google-cloud-project-id GOOGLE_CLOUD_LOCATIONyour-google-cloud-region LLM_MODEL_NAMEgemma-3-27b-it GOOGLE_API_KEY--Your Google AI Studio API Key for Gemma: https://aistudio.google.com/apikey --各变量的含义与取值说明变量作用说明GOOGLE_CLOUD_PROJECTGoogle Cloud 项目 ID服务端 Gemini 客户端与翻译 API 都依赖它替换为真实项目 IDGOOGLE_CLOUD_LOCATIONVertex AI 区域默认us-central1也可用europe-west1等客户端代码中的默认值同样是us-central1LLM_MODEL_NAME客户端编排模型默认gemma-3-27b-it作为对话调度器按 README 建议使用便宜模型服务端各工具使用的模型在gemini_server.py中硬编码GOOGLE_API_KEYGemma 的 Google AI Studio API Key仅客户端使用走 AI Studio / Gemini Developer API服务端走 Vertex AI 应用默认凭据ADCexample.env中还提示了两种认证方式推荐 ADC运行gcloud auth application-default login完成本地认证云环境自动继承服务账号通过GOOGLE_APPLICATION_CREDENTIALS/path/to/your/service-account-key.json指向密钥文件。务必把.env加入.gitignore避免凭据泄露。4. 重新认证 gcloud如需gcloud auth application-default login gcloud auth application-default set-quota-project your-google-cloud-project-id5. 启用 Google Cloud APICloud Translation API在 Google Cloud Console 中启用translate.googleapis.comVertex AI API在项目里启用Gemini 模型推理所需。6.可选校准服务端配置如果使用servers_config.json管理服务端设置请确保它位于当前运行目录并正确指向gemini_server.py。仓库中已提供一份开箱即用的配置 servers_config.json{ geminiServer: { name: gemini_llm_server, config: { script_path: gemini_server.py, env: {} } } }该配置由 gemini_client.py 中的main()读取它先通过Configuration.load_config(servers_config.json)加载 JSON再取出geminiServer节点的name与config实例化Server对象。script_path指定服务端脚本相对当前工作目录env允许向服务端子进程注入额外的环境变量。MCP 服务端把专业模型变成可调用工具服务端 gemini_server.py 使用官方mcp.server.fastmcp.FastMCP构建实例名为gemini-complexity-serverL98-L103。客户端初始化与认证差异服务端通过genai.Client(vertexaiTrue, ...)走Vertex AI通道L62-L65使用应用默认凭据ADC认证与客户端使用 API Key 的 AI Studio 通道形成互补。服务端在启动时即校验GOOGLE_CLOUD_PROJECT与GOOGLE_CLOUD_LOCATIONL49-L58并对DefaultCredentialsError、PermissionDenied、GoogleAPIError、RuntimeError做了分类降级处理保证初始化失败时服务端仍能优雅退出而非崩溃。统一推理入口 call_gemini_model所有 Gemini 工具都复用统一的异步函数 call_gemini_model其生成配置为temperature0.2、top_p0.8、max_output_tokens1024、response_modalities[TEXT]并把四类安全阈值仇恨言论、危险内容、色情内容、骚扰全部设为OFF让专业模型在受限场景下保持输出流畅。四个工具的定义服务端通过 FastMCP 装饰器暴露了 4 个工具L240-L327工具名对应模型/服务适用场景translate_llmGoogle Cloud Translation v3显式要求翻译或澄清非英文文本含义时调用参数为text、source_language、target_languagegemini_flash_lite_2_0gemini-2.0-flash-lite-001诗歌类 prompt低成本模型gemini_flash_2_0gemini-2.0-flash与科学相关的 promptgemini_pro_2_5gemini-2.5-pro-exp-03-25复杂 prompt、代码、数学等需要深度推理的场景注意gemini_pro_2_5工具的描述明确写着thinking is needed正是为了把推理密集型任务路由到能力更强的模型。翻译工具的容错设计translate_text 使用google.cloud.translate_v3客户端调用translate_textRPC 并携带mime_type: text/plain与语言码参数。异常处理按优先级分层认证失败DefaultCredentialsError、Unauthenticated→ 瞬时故障ServiceUnavailable、DeadlineExceeded、ResourceExhausted提示可重试→ 其余GoogleAPIError兜底任何失败都返回None并由工具层转成\nTranslation failed.。MCP 客户端编排循环的源码级剖析客户端 gemini_client.py 是整个编排逻辑的核心由四个类协同工作。Configuration配置加载Configuration 提供两个静态方法load_env()用python-dotenv加载.envload_config(file_path)读取 JSON 配置文件并对FileNotFoundError与json.JSONDecodeError做了显式日志与向上抛出。Server管理服务端子进程Server 负责与服务端进程建立 stdio 连接initialize()通过shutil.which(python)探测解释器路径读取配置中的script_path构造StdioServerParameters并合并os.environ与配置中的env然后借助AsyncExitStack启动stdio_client与ClientSession并握手初始化L96-L168list_tools()调用 MCP 的session.list_tools()兼容input_schema/inputSchema两种命名把原始工具描述转成Tool对象L170-L219execute_tool()带重试机制的工具执行——默认retries1、delay1.0s对asyncio.TimeoutError、BrokenPipeError、ConnectionResetError、EOFError等 stdio 传输层异常进行重试全部失败后抛出RuntimeErrorL221-L302cleanup()用asyncio.Lock保证并发安全地关闭退出栈、释放连接L304-L312。Tool把工具描述喂给 LLMTool 是本地轻量表示其format_for_llm()会把工具名、描述、参数含必填标记格式化为 LLM 可读的文本块例如Tool: gemini_pro_2_5 Description: Calls the Gemini 2.5 Pro Thinking model for complex prompts, ... Arguments: - prompt: The prompt to send to the model. (required)这些文本块最终会被拼进系统指令让调度模型知道有哪些工具可用。LLMClient与编排模型对话LLMClient 封装了与客户端模型的通信_initialize_client()使用GOOGLE_API_KEY创建genai.Client(vertexaiFalse, ...)即走 AI Studio / Gemini Developer API 通道与使用 ADC 的服务端区别开L387-L404set_system_instruction()创建聊天会话并把系统指令作为首条消息发出L415-L433extract_tool_call_json()用正则rjson\s*(\{.*?\})\s*从模型响应中提取 JSON 代码块校验其是否含tool与arguments两个键兼容整段文本就是 JSON的兜底解析L435-L505get_response()把当前对话上下文发送给模型并返回原始文本L507-L543。ChatSession编排主循环ChatSession 是编排的心脏start()的完整流程如下准备阶段_prepare_llm()L575-L713初始化服务端 → 拉取工具列表 → 用format_for_llm()生成工具描述 → 拼装系统指令包含仅输出指定 JSON 格式调用工具后要转述成自然语言翻译工具的参数说明等约束→ 设置生成配置temperature0.9, top_p0.8, max_output_tokens4048→ 建立聊天会话并初始化消息历史循环阶段读取用户输入quit/exit退出→ 追加用户消息 → 获取 LLM 原始响应 → 尝试解析为工具调用工具调用分支若解析成功把模型的 JSON 决策追加进历史执行_run_tool_and_get_result()找到对应工具校验工具确实在available_tools列表中并调用execute_tool()把结果格式化为文本追加回历史再让模型基于工具结果生成最终回答L786-L836直接回答分支若解析不到合法 JSON则把模型原始响应当作最终回答输出L838-L847退出清理KeyboardInterrupt、ConnectionError或用户输入退出词时统一调用cleanup_servers()释放服务端连接L852-L868。整个会话中工具调用决策通过文本即协议完成模型输出一个 json 代码块客户端用正则解析、校验、执行再把结果回灌给模型生成人类可读的回答——这正是 MCP把模型能力工具化的轻量落地方式。启动应用在项目目录下执行cd src python gemini_client.py启动后终端进入交互式聊天会话输入quit或exit退出。你可以这样验证模型路由输入写一首关于秋天的诗——大概率命中gemini_flash_lite_2_0低成本诗歌模型输入解释一下黑洞的视界——可能命中gemini_flash_2_0或gemini_pro_2_5输入把 Hello world 翻译成法语——触发translate_llm走 Cloud Translation API输入普通闲聊——调度模型直接回答不调用任何工具。每条回答尾部会标注所用的模型MCP Client Model: ...或Response by Default Model: ...方便你观察编排路由是否符合预期。常见问题与排查要点GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION未设置客户端main()与服务端启动逻辑都会在缺失时记录错误并退出客户端默认区域us-central1先在.env中确认服务端连接失败Server.initialize()对FileNotFoundError、PermissionError、BrokenPipeError等分别记录了含脚本路径的详细错误信息检查script_path是否相对当前运行目录cd src后应为gemini_server.py以及 Python 是否在 PATH 中工具调用超时/中断execute_tool()内置重试默认 1 次重试、间隔 1 秒若持续失败请检查服务端进程是否崩溃、stdio 管道是否被意外关闭安全阈值客户端与服务端的生成配置均把四类安全阈值设为OFF这是示例代码为演示流畅输出而做的取舍生产环境应改为合适的BLOCK级别并在服务端开启内容审核translate_llm的工具描述也明确要求过滤不当文本凭据安全.env必须加入.gitignore生产环境建议改用 Secret Manager 管理 API Key 与服务账号。总结mcp_orchestration_app完整展示了轻量调度模型 专业执行模型的 MCP 编排范式服务端用 FastMCP 以最少的样板代码把 Gemma 之外的 Gemini 2.0 Flash Lite、2.0 Flash、2.5 Pro 以及 Cloud Translation 变成标准 MCP 工具客户端用Server/Tool/LLMClient/ChatSession四个类完成工具发现 → 系统指令注入 → JSON 工具调用解析 → 执行 → 结果转述的闭环。无论你是要借鉴其模型路由设计、复用其重试与容错骨架还是想在自己的项目里接入 MCP 工具生态这份源码都是一份结构清晰、可直接上手的参考实现。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考