尧图网站建设 
Semantic Kernel Python 连接 Google GeminiGoogle AI 与 Vertex AI 双连接器实战指南【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本指南聚焦 Semantic Kernel Python 版本中的 Google Gemini 连接器python/semantic_kernel/connectors/ai/google系统讲解通过Google AI StudioAPI Key 模式与Vertex AI企业级 Google Cloud 模式两条路径接入 Gemini 模型的完整方法。读完本文你将掌握两种连接器的初始化方式、.env环境变量配置、核心执行参数temperature、top_p、max_output_tokens 等、函数调用与流式输出的底层实现原理以及两者代码高度相似却必须区分使用的根本原因。一、两种接入方式概览Gemini 是 Google 的大语言模型系列。Semantic Kernel 的 Python 包提供了两个连接器分别对接 Google 的两条模型访问通道连接器适用场景认证方式关键前置条件GoogleAIChatCompletiongoogle_ai快速原型验证API Key在 Google AI Studio 中创建 API KeyVertexAIChatCompletionvertex_ai企业级端到端 AI 应用Google Cloud 服务账号创建 Google Cloud 项目并安装、初始化 gcloud CLI两者的业务入口完全相同均通过GoogleAIChatCompletion类实例化区别仅在use_vertexai参数与认证参数上。需要特别留意的是从源码看VertexAIChatCompletion类已被标记为弃用deprecated提示将于 2026/01/01 之后移除建议改用google_ai连接器详见 vertex_ai_chat_completion.py。因此本文以google_ai连接器为主线vertex_ai作为对照讲解。二、Google AI Studio 快速开始API Key 模式2.1 前置准备在 Google AI Studio 中为 Gemini API 创建一个 API Key该模式依赖 API Key 认证适合快速原型开发。确认已安装 Semantic Kernel Python 包及其 Google 依赖。2.2 在 Kernel 中注册服务创建Kernel实例并通过GoogleAIChatCompletion注册 Gemini 服务from semantic_kernel import Kernel from semantic_kernel.connectors.ai.google import GoogleAIChatCompletion kernel Kernel() kernel.add_service( GoogleAIChatCompletion( gemini_model_idgemini-2.5-flash, api_key..., ) )注册完成后即可像使用其他聊天完成服务一样将对话交给ChatCompletionService调用。2.3 使用 .env 文件管理密钥提示可以将模型 ID 与 API Key 放入.env文件避免在代码中硬编码敏感信息。源码层面的配置解析逻辑位于 google_ai_settings.pyGoogleAISettings继承自KernelBaseSettings其配置读取顺序为环境变量前缀GOOGLE_AI_→.env文件UTF-8 编码→ 构造参数。若.env中也找不到对应项则忽略该项但在校验时若缺少必填项会直接报错。对应的.env文件内容如下GOOGLE_AI_GEMINI_MODEL_IDgemini-2.5-flash GOOGLE_AI_API_KEY你的_API_KEY此时代码可以简化为不传任何参数直接从环境加载kernel.add_service(GoogleAIChatCompletion())2.4 GoogleAISettings 完整字段GoogleAISettings支持以下字段google_ai_settings.py字段环境变量说明gemini_model_idGOOGLE_AI_GEMINI_MODEL_IDGemini 模型 ID如gemini-2.5-flash、gemini-1.5-proembedding_model_idGOOGLE_AI_EMBEDDING_MODEL_ID嵌入模型 ID如text-embedding-004api_keyGOOGLE_AI_API_KEYGoogle AI 部署的 API Keycloud_project_idGOOGLE_AI_CLOUD_PROJECT_IDGoogle Cloud 项目 ID开启 Vertex AI 时必填cloud_regionGOOGLE_AI_CLOUD_REGIONGoogle Cloud 区域开启 Vertex AI 时必填use_vertexaiGOOGLE_AI_USE_VERTEXAI是否走 Vertex AI默认False注意use_vertexaiTrue时api_key不再被检查但cloud_project_id与cloud_region二者缺一不可。这一校验逻辑可以在 google_ai_chat_completion.py 的__init__中看到缺少对应参数时会抛出ServiceInitializationError。三、Vertex AI 接入企业级模式Vertex AI 是 Google 面向企业端到端 AI 应用提供的平台。该模式不使用 API Key而是依赖Google Cloud 服务账号。3.1 环境准备步骤创建 Google Cloud 项目若尚无务必记住project id访问模型时必需。安装 gcloud CLI。初始化 gcloud CLI登录并配置项目。3.2 注册服务使用google_ai连接器并以use_vertexaiTrue切换通道from semantic_kernel import Kernel from semantic_kernel.connectors.ai.google import GoogleAIChatCompletion kernel Kernel() kernel.add_service( GoogleAIChatCompletion( project_id你的_项目ID, region你的_区域, gemini_model_idgemini-2.5-flash, use_vertexaiTrue, ) )提示同样可以使用.env文件存储模型 ID 与项目 ID。GOOGLE_AI_GEMINI_MODEL_IDgemini-2.5-flash GOOGLE_AI_CLOUD_PROJECT_ID你的_项目ID GOOGLE_AI_CLOUD_REGION你的_区域 GOOGLE_AI_USE_VERTEXAItrue3.3 底层通道切换原理GoogleAIChatCompletion在发起请求时会根据配置动态选择底层客户端google_ai_chat_completion.py显式传入client直接复用该google.genai.Client实例源码注释称之为 “break glass” 逃生舱场景use_vertexaiTrue以Client(vertexaiTrue, project..., location...)建立 Vertex AI 客户端默认以Client(api_key...)建立 Google AI Studio 客户端。也就是说两条通道共用同一套GoogleAIChatCompletion代码与同一套请求编排逻辑仅认证与端点不同。3.4 独立 VertexAI 连接器已弃用仅供对照仓库中还存在一个独立的vertex_ai连接器目录使用VERTEX_AI_前缀配置字段环境变量说明gemini_model_idVERTEX_AI_GEMINI_MODEL_IDGemini 模型 IDembedding_model_idVERTEX_AI_EMBEDDING_MODEL_ID嵌入模型 IDproject_idVERTEX_AI_PROJECT_IDGoogle Cloud 项目 ID必填regionVERTEX_AI_REGIONGoogle Cloud 区域其VertexAISettingsvertex_ai_settings.py与VertexAIChatCompletion均已标注弃用官方建议统一迁移到google_ai连接器即GoogleAIChatCompletion(use_vertexaiTrue)。新项目请勿再使用独立的 vertex_ai 连接器。四、执行参数详解Prompt Execution Settings两个连接器分别定义了各自的执行设置类。google_ai侧的基类是GoogleAIPromptExecutionSettingsgoogle_ai_prompt_execution_settings.py支持以下通用参数参数类型/约束说明stop_sequenceslist[str]最多 5 个停止序列命中即终止生成response_mime_typetext/plain或application/json响应 MIME 类型JSON 可用于结构化输出response_schemaAny响应 JSON Schema配合 JSON 输出使用candidate_countint 1生成候选数量max_output_tokensint 1最大输出 token 数temperaturefloat0.0 ~ 2.0采样温度控制随机性top_pfloat核采样概率阈值top_kintTop-K 采样参数GoogleAIChatPromptExecutionSettings额外提供tools与tool_config两个字段但源码中明确标注“不要手动设置由服务根据函数选择配置自动填充”见 google_ai_prompt_execution_settings.py。GoogleAIEmbeddingPromptExecutionSettings则提供output_dimensionalityint 768用于控制嵌入输出维度。4.1 函数调用Function Calling支持两个聊天完成类都声明了SUPPORTS_FUNCTION_CALLING True说明它们原生支持 Gemini 的函数调用能力。底层实现要点以 google_ai 为例将 Semantic Kernel 的KernelFunctionMetadata转换为 Gemini 的function_declarations格式包括函数名、描述与参数 Schema见 utils.py依据FunctionChoiceType设置 Gemini 的function_calling_config.mode如自动/强制调用见 utils.py开启函数自动调用时candidate_count必须为 1否则会抛出ServiceInvalidExecutionSettingsErrorgoogle_ai_chat_completion.py。4.2 聊天历史与多模态处理在发送请求前聊天历史会被统一格式化google_ai_chat_completion.pySYSTEM消息不进入对话体而是被提取为system_instruction配置项USER消息映射为roleuser支持文本与图片ImageContentASSISTANT消息映射为rolemodelTOOL消息映射为rolefunction函数调用结果回传。多模态图片要求以data_uri形式携带因为 Google AI API 不支持任意 URI 图片见 utils.py。4.3 流式输出两个连接器都实现了流式聊天接口_inner_get_streaming_chat_message_contents通过client.aio.models.generate_content_stream逐块产出StreamingChatMessageContent适合逐字输出体验场景google_ai_chat_completion.py。4.4 遥测与元数据请求调用被trace_chat_completion/trace_streaming_chat_completion装饰器包裹模型提供商标识为googleaigoogle_ai_base.py可接入 OpenTelemetry 观测链路。响应中还附带prompt_feedback、token 用量、safety_ratings、finish_reason等元数据google_ai_chat_completion.py便于做安全审核与用量统计。五、为什么两个连接器的实现看起来几乎一模一样这是阅读仓库时最常见的疑问google_ai与vertex_ai两个目录下的实现乃至工具函数utils高度相似很多类型命名完全相同。原因在于两者依赖的是 Google 不同的底层包与类型体系。google_ai基于google.genaiClient、GenerateContentResponse等而vertex_ai基于vertexaivertexai.generative_models中的GenerativeModel、GenerationResponse等。尽管类型名几乎一致它们分属两个 SDK彼此不兼容无法互相混用。这也是官方最终选择“统一入口 use_vertexai开关”来收敛差异的原因——从VertexAIChatCompletion的弃用说明可见未来的方向是全部收敛到GoogleAIChatCompletion。六、代码正确性验证测试与示例仓库为两个连接器都提供了单元测试作为行为契约可作为接入时的参考test_google_ai_chat_completion.pytest_google_ai_text_completion.pytest_vertex_ai_chat_completion.pytest_vertex_ai_text_completion.py集成测试基类 chat_completion_test_base.py 也覆盖了 Google 连接器在真实服务上的调用路径。进一步的多模态、流式、函数调用示例可参考 python/samples/concepts 下的相关概念样例。七、快速决策清单场景推荐方案快速原型、个人实验GoogleAIChatCompletion(gemini_model_id..., api_key...)企业生产、需要 Google Cloud 治理与合规GoogleAIChatCompletion(project_id..., region..., gemini_model_id..., use_vertexaiTrue)统一密钥管理全部改用GOOGLE_AI_前缀的.env变量代码不传参新项目使用 Vertex AI一律走google_ai连接器 use_vertexaiTrue不要使用已弃用的VertexAIChatCompletion【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Semantic Kernel Python 连接 Google Gemini：Google AI 与 Vertex AI 双连接器实战指南
Semantic Kernel Python 连接 Google GeminiGoogle AI 与 Vertex AI 双连接器实战指南【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本指南聚焦 Semantic Kernel Python 版本中的 Google Gemini 连接器python/semantic_kernel/connectors/ai/google系统讲解通过Google AI StudioAPI Key 模式与Vertex AI企业级 Google Cloud 模式两条路径接入 Gemini 模型的完整方法。读完本文你将掌握两种连接器的初始化方式、.env环境变量配置、核心执行参数temperature、top_p、max_output_tokens 等、函数调用与流式输出的底层实现原理以及两者代码高度相似却必须区分使用的根本原因。一、两种接入方式概览Gemini 是 Google 的大语言模型系列。Semantic Kernel 的 Python 包提供了两个连接器分别对接 Google 的两条模型访问通道连接器适用场景认证方式关键前置条件GoogleAIChatCompletiongoogle_ai快速原型验证API Key在 Google AI Studio 中创建 API KeyVertexAIChatCompletionvertex_ai企业级端到端 AI 应用Google Cloud 服务账号创建 Google Cloud 项目并安装、初始化 gcloud CLI两者的业务入口完全相同均通过GoogleAIChatCompletion类实例化区别仅在use_vertexai参数与认证参数上。需要特别留意的是从源码看VertexAIChatCompletion类已被标记为弃用deprecated提示将于 2026/01/01 之后移除建议改用google_ai连接器详见 vertex_ai_chat_completion.py。因此本文以google_ai连接器为主线vertex_ai作为对照讲解。二、Google AI Studio 快速开始API Key 模式2.1 前置准备在 Google AI Studio 中为 Gemini API 创建一个 API Key该模式依赖 API Key 认证适合快速原型开发。确认已安装 Semantic Kernel Python 包及其 Google 依赖。2.2 在 Kernel 中注册服务创建Kernel实例并通过GoogleAIChatCompletion注册 Gemini 服务from semantic_kernel import Kernel from semantic_kernel.connectors.ai.google import GoogleAIChatCompletion kernel Kernel() kernel.add_service( GoogleAIChatCompletion( gemini_model_idgemini-2.5-flash, api_key..., ) )注册完成后即可像使用其他聊天完成服务一样将对话交给ChatCompletionService调用。2.3 使用 .env 文件管理密钥提示可以将模型 ID 与 API Key 放入.env文件避免在代码中硬编码敏感信息。源码层面的配置解析逻辑位于 google_ai_settings.pyGoogleAISettings继承自KernelBaseSettings其配置读取顺序为环境变量前缀GOOGLE_AI_→.env文件UTF-8 编码→ 构造参数。若.env中也找不到对应项则忽略该项但在校验时若缺少必填项会直接报错。对应的.env文件内容如下GOOGLE_AI_GEMINI_MODEL_IDgemini-2.5-flash GOOGLE_AI_API_KEY你的_API_KEY此时代码可以简化为不传任何参数直接从环境加载kernel.add_service(GoogleAIChatCompletion())2.4 GoogleAISettings 完整字段GoogleAISettings支持以下字段google_ai_settings.py字段环境变量说明gemini_model_idGOOGLE_AI_GEMINI_MODEL_IDGemini 模型 ID如gemini-2.5-flash、gemini-1.5-proembedding_model_idGOOGLE_AI_EMBEDDING_MODEL_ID嵌入模型 ID如text-embedding-004api_keyGOOGLE_AI_API_KEYGoogle AI 部署的 API Keycloud_project_idGOOGLE_AI_CLOUD_PROJECT_IDGoogle Cloud 项目 ID开启 Vertex AI 时必填cloud_regionGOOGLE_AI_CLOUD_REGIONGoogle Cloud 区域开启 Vertex AI 时必填use_vertexaiGOOGLE_AI_USE_VERTEXAI是否走 Vertex AI默认False注意use_vertexaiTrue时api_key不再被检查但cloud_project_id与cloud_region二者缺一不可。这一校验逻辑可以在 google_ai_chat_completion.py 的__init__中看到缺少对应参数时会抛出ServiceInitializationError。三、Vertex AI 接入企业级模式Vertex AI 是 Google 面向企业端到端 AI 应用提供的平台。该模式不使用 API Key而是依赖Google Cloud 服务账号。3.1 环境准备步骤创建 Google Cloud 项目若尚无务必记住project id访问模型时必需。安装 gcloud CLI。初始化 gcloud CLI登录并配置项目。3.2 注册服务使用google_ai连接器并以use_vertexaiTrue切换通道from semantic_kernel import Kernel from semantic_kernel.connectors.ai.google import GoogleAIChatCompletion kernel Kernel() kernel.add_service( GoogleAIChatCompletion( project_id你的_项目ID, region你的_区域, gemini_model_idgemini-2.5-flash, use_vertexaiTrue, ) )提示同样可以使用.env文件存储模型 ID 与项目 ID。GOOGLE_AI_GEMINI_MODEL_IDgemini-2.5-flash GOOGLE_AI_CLOUD_PROJECT_ID你的_项目ID GOOGLE_AI_CLOUD_REGION你的_区域 GOOGLE_AI_USE_VERTEXAItrue3.3 底层通道切换原理GoogleAIChatCompletion在发起请求时会根据配置动态选择底层客户端google_ai_chat_completion.py显式传入client直接复用该google.genai.Client实例源码注释称之为 “break glass” 逃生舱场景use_vertexaiTrue以Client(vertexaiTrue, project..., location...)建立 Vertex AI 客户端默认以Client(api_key...)建立 Google AI Studio 客户端。也就是说两条通道共用同一套GoogleAIChatCompletion代码与同一套请求编排逻辑仅认证与端点不同。3.4 独立 VertexAI 连接器已弃用仅供对照仓库中还存在一个独立的vertex_ai连接器目录使用VERTEX_AI_前缀配置字段环境变量说明gemini_model_idVERTEX_AI_GEMINI_MODEL_IDGemini 模型 IDembedding_model_idVERTEX_AI_EMBEDDING_MODEL_ID嵌入模型 IDproject_idVERTEX_AI_PROJECT_IDGoogle Cloud 项目 ID必填regionVERTEX_AI_REGIONGoogle Cloud 区域其VertexAISettingsvertex_ai_settings.py与VertexAIChatCompletion均已标注弃用官方建议统一迁移到google_ai连接器即GoogleAIChatCompletion(use_vertexaiTrue)。新项目请勿再使用独立的 vertex_ai 连接器。四、执行参数详解Prompt Execution Settings两个连接器分别定义了各自的执行设置类。google_ai侧的基类是GoogleAIPromptExecutionSettingsgoogle_ai_prompt_execution_settings.py支持以下通用参数参数类型/约束说明stop_sequenceslist[str]最多 5 个停止序列命中即终止生成response_mime_typetext/plain或application/json响应 MIME 类型JSON 可用于结构化输出response_schemaAny响应 JSON Schema配合 JSON 输出使用candidate_countint 1生成候选数量max_output_tokensint 1最大输出 token 数temperaturefloat0.0 ~ 2.0采样温度控制随机性top_pfloat核采样概率阈值top_kintTop-K 采样参数GoogleAIChatPromptExecutionSettings额外提供tools与tool_config两个字段但源码中明确标注“不要手动设置由服务根据函数选择配置自动填充”见 google_ai_prompt_execution_settings.py。GoogleAIEmbeddingPromptExecutionSettings则提供output_dimensionalityint 768用于控制嵌入输出维度。4.1 函数调用Function Calling支持两个聊天完成类都声明了SUPPORTS_FUNCTION_CALLING True说明它们原生支持 Gemini 的函数调用能力。底层实现要点以 google_ai 为例将 Semantic Kernel 的KernelFunctionMetadata转换为 Gemini 的function_declarations格式包括函数名、描述与参数 Schema见 utils.py依据FunctionChoiceType设置 Gemini 的function_calling_config.mode如自动/强制调用见 utils.py开启函数自动调用时candidate_count必须为 1否则会抛出ServiceInvalidExecutionSettingsErrorgoogle_ai_chat_completion.py。4.2 聊天历史与多模态处理在发送请求前聊天历史会被统一格式化google_ai_chat_completion.pySYSTEM消息不进入对话体而是被提取为system_instruction配置项USER消息映射为roleuser支持文本与图片ImageContentASSISTANT消息映射为rolemodelTOOL消息映射为rolefunction函数调用结果回传。多模态图片要求以data_uri形式携带因为 Google AI API 不支持任意 URI 图片见 utils.py。4.3 流式输出两个连接器都实现了流式聊天接口_inner_get_streaming_chat_message_contents通过client.aio.models.generate_content_stream逐块产出StreamingChatMessageContent适合逐字输出体验场景google_ai_chat_completion.py。4.4 遥测与元数据请求调用被trace_chat_completion/trace_streaming_chat_completion装饰器包裹模型提供商标识为googleaigoogle_ai_base.py可接入 OpenTelemetry 观测链路。响应中还附带prompt_feedback、token 用量、safety_ratings、finish_reason等元数据google_ai_chat_completion.py便于做安全审核与用量统计。五、为什么两个连接器的实现看起来几乎一模一样这是阅读仓库时最常见的疑问google_ai与vertex_ai两个目录下的实现乃至工具函数utils高度相似很多类型命名完全相同。原因在于两者依赖的是 Google 不同的底层包与类型体系。google_ai基于google.genaiClient、GenerateContentResponse等而vertex_ai基于vertexaivertexai.generative_models中的GenerativeModel、GenerationResponse等。尽管类型名几乎一致它们分属两个 SDK彼此不兼容无法互相混用。这也是官方最终选择“统一入口 use_vertexai开关”来收敛差异的原因——从VertexAIChatCompletion的弃用说明可见未来的方向是全部收敛到GoogleAIChatCompletion。六、代码正确性验证测试与示例仓库为两个连接器都提供了单元测试作为行为契约可作为接入时的参考test_google_ai_chat_completion.pytest_google_ai_text_completion.pytest_vertex_ai_chat_completion.pytest_vertex_ai_text_completion.py集成测试基类 chat_completion_test_base.py 也覆盖了 Google 连接器在真实服务上的调用路径。进一步的多模态、流式、函数调用示例可参考 python/samples/concepts 下的相关概念样例。七、快速决策清单场景推荐方案快速原型、个人实验GoogleAIChatCompletion(gemini_model_id..., api_key...)企业生产、需要 Google Cloud 治理与合规GoogleAIChatCompletion(project_id..., region..., gemini_model_id..., use_vertexaiTrue)统一密钥管理全部改用GOOGLE_AI_前缀的.env变量代码不传参新项目使用 Vertex AI一律走google_ai连接器 use_vertexaiTrue不要使用已弃用的VertexAIChatCompletion【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考