Semantic Kernel Python AI Connectors 深度解析六大模态基类与全部内置连接器【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本文以 python/semantic_kernel/connectors/ai/README.md 为核心骨架结合仓库源码逐一拆解 Semantic KernelPython中 AI ConnectorAI 服务连接器的整体设计六类按模态划分的客户端基类、统一的AIServiceClientBase契约、PromptExecutionSettings执行参数体系以及覆盖 OpenAI、Azure OpenAI、Anthropic、Bedrock、Google AI、HuggingFace、Ollama、ONNX 等厂商的完整连接器清单。读完本文你将掌握连接器的继承体系与扩展方式能够在自己的应用中正确选择、配置和编写 AI 连接器。一、AI Connector 是什么Kernel 与大模型之间的统一抽象在 Semantic Kernel 中AI Connector也称为 AI Service是与具体 AI 模型交互的实现层。它的职责非常单一把 Kernel 发来的请求聊天历史、提示词、文本、图片、音频翻译成某个模型服务商的 API 调用再把响应包装成语义内核统一的内容类型返回。python/semantic_kernel/connectors/ai/目录正是 Python 版所有 AI 连接器实现与公共基类的聚集地。它的核心设计思想是按模态modality分类不同模型擅长处理不同形态的输入输出因此连接器根据任务类型继承自不同的基类模态Modality基类Base Client源码位置聊天补全ChatCompletionClientBasechat_completion_client_base.py文本补全TextCompletionClientBasetext_completion_client_base.py语音转文本AudioToTextClientBaseaudio_to_text_client_base.py文本转语音TextToAudioClientBasetext_to_audio_client_base.py文本转图片TextToImageClientBasetext_to_image_client_base.py文本嵌入EmbeddingGeneratorBaseembedding_generator_base.py而所有这些基类最终都继承自同一个根类——AIServiceClientBase位于 python/semantic_kernel/services/ai_service_client_base.py。这就保证了无论使用哪种模态、哪个厂商的连接器在 Kernel 层面都遵循同一套服务注册、参数解析与调用协议。从源码结构看python/semantic_kernel/connectors/ai/ 目录中还包含一个 realtime_client_base.py实时对话客户端基类README 未列入上述六类说明该目录正随实时 API 等新模态持续演进。二、统一基类 AIServiceClientBaseai_model_id 与 service_id 的契约所有连接器都继承自AIServiceClientBase它定义了连接器的最低公共接口。从源码ai_service_client_base.py可以看到两个核心字段ai_model_id: Annotated[str, StringConstraints(strip_whitespaceTrue, min_length1)] service_id: str ai_model_id必填字段用于标识具体模型例如 OpenAI 的gpt-4o-mini也可以只是服务端用于区分模型的任意字符串。service_id在 Semantic Kernel 中用于标识服务实例的 ID如果为空则在model_post_init中自动回退为ai_model_id源码#L28-L31。除字段外基类还定义了几个与执行设置相关的核心方法get_prompt_execution_settings_class()返回该服务期望的PromptExecutionSettings子类默认是通用PromptExecutionSettings各厂商连接器会覆写为带专属参数的类型如 OpenAI 的OpenAIChatPromptExecutionSettings。instantiate_prompt_execution_settings(**kwargs)按上述类型直接构造一个设置对象。get_prompt_execution_settings_from_settings(settings)把任意传入的设置对象转换为当前服务期望的类型——如果本身就是目标类型则原样返回否则调用from_prompt_execution_settings迁移字段。service_url()默认返回None需要暴露服务地址的厂商如 Ollama、Azure会在子类中覆写。这一设计使得 Kernel 侧只需持有设置对象而无需关心具体是哪个厂商的参数格式转换职责被下沉到每个连接器自己身上。三、六类客户端基类逐一拆解3.1 ChatCompletionClientBase聊天补全聊天补全是当前大模型应用最常用的模态。ChatCompletionClientBasechat_completion_client_base.py是整个目录中逻辑最丰富的基类关键成员包括SUPPORTS_FUNCTION_CALLING: ClassVar[bool] False#L39声明该连接器是否支持函数调用Function Calling / Tool Calling。支持者如 OpenAI、Azure OpenAI、Anthropic、Ollama 等必须覆写为True。instruction_role: str system#L40指令消息使用的角色名默认system个别厂商用别的角色名时可覆写。抽象方法_inner_get_chat_message_contents与_inner_get_streaming_chat_message_contents真正发请求给模型服务商的逻辑由具体连接器实现以_前缀表示内部接口。对外暴露的公开方法是get_chat_message_contents#L85-L174。它的执行流程在源码中非常清晰copy.deepcopy(settings)深拷贝设置对象避免污染调用方传入的原始设置通过get_prompt_execution_settings_from_settings把设置统一转换成本连接器期望的类型若不支持函数调用直接调用_inner_get_chat_message_contents返回结果若设置了function_choice_behavior且需要auto_invoke_kernel_functions自动调用内核函数则进入自动调用循环#L137-L174在maximum_auto_invoke_attempts限制内循环请求模型从响应中抽取FunctionCallContent若没有函数调用则立即返回把助手消息加入ChatHistory然后用asyncio.gather并行调用kernel.invoke_function_call执行多个工具将工具结果合并回历史继续下一轮达到最大尝试次数后_reset_function_choice_settings关闭函数调用再做一次收尾请求。get_streaming_chat_message_contents#L196-L318是同样的流程的流式版本它先把流式分片累积为完整的StreamingChatMessageContent用reduce合并识别其中的FunctionCallContent调用函数后再通过merge_streaming_function_results把结果作为新的流式消息产出。另外_prepare_chat_history_for_request#L350-L378负责把ChatHistory序列化为请求消息数组会剔除AnnotationContent与FileReferenceContent这类非对话内容并允许通过role_key/content_key自定义角色与内容字段名源码注释特别指出ChatRole.TOOL消息需要tool_call_id与函数名name字段且应移除metadata与encoding键——这是多厂商适配的关键细节。3.2 TextCompletionClientBase文本补全面向纯文本补全如早期 GPT-3 风格接口。基类text_completion_client_base.py只要求子类实现_inner_get_text_contents与_inner_get_streaming_text_contents两个抽象方法公开方法get_text_contents#L59-L76同样先深拷贝设置再透传get_text_content则返回列表首元素。文本补全没有函数调用自动循环逻辑相对轻量。3.3 AudioToTextClientBase语音转文本对应 ASR / Whisper 一类服务。抽象方法签名audio_to_text_client_base.py为async def get_text_contents( self, audio_content: AudioContent, # 音频内容对象 settings: PromptExecutionSettings | None None, **kwargs: Any, ) - list[TextContent]子类必须实现它基类提供的get_text_content便捷方法直接返回第一个TextContent。3.4 TextToAudioClientBase文本转语音与上一类互补抽象方法为get_audio_contents(text, settingsNone, **kwargs) - list[AudioContent]text_to_audio_client_base.py。源码注释明确说明部分服务一次调用可能返回多个音频内容因此统一返回列表单个结果也以单元素列表返回get_audio_content取首元素。3.5 TextToImageClientBase文生图抽象方法generate_imagetext_to_image_client_base.py返回bytes | str——即图片字节数据或图片 URL具体取决于服务商。值得注意的细节width与height参数在源码 docstring 中被标注为Deprecated建议改为在settings中指定。基类提供的get_image_content会把返回值包装为统一的ImageContentURL 走ImageContent(uri...)字节走ImageContent(data...)。3.6 EmbeddingGeneratorBase文本嵌入嵌入生成器在源码中标记为experimentalembedding_generator_base.py抽象方法为async def generate_embeddings( self, texts: list[str], settings: PromptExecutionSettings | None None, **kwargs: Any, ) - ndarray # numpy 数组generate_raw_embeddings用于获取未经加工的原始嵌入格式未实现的服务会回退到generate_embeddings。此外目录下还保留了旧的兼容入口 embeddings/embedding_generator_base.py其中用deprecated明确提示该类已迁移到semantic_kernel.connectors.ai.embedding_generator_base请更新 import——新代码应直接使用上层的EmbeddingGeneratorBase。四、现有 AI 连接器全景以下是 README 中登记的全部内置连接器路径已换算为仓库根目录相对路径覆盖云端商业模型、本地推理与多模态服务服务商连接器源码路径OpenAIOpenAIChatCompletionopen_ai/services/open_ai_chat_completion.pyOpenAITextCompletionopen_ai/services/open_ai_text_completion.pyOpenAITextEmbeddingopen_ai/services/open_ai_text_embedding.pyOpenAITextToImageopen_ai/services/open_ai_text_to_image.pyOpenAITextToAudioopen_ai/services/open_ai_text_to_audio.pyOpenAIAudioToTextopen_ai/services/open_ai_audio_to_text.pyAzure OpenAIAzureChatCompletionopen_ai/services/azure_chat_completion.pyAzureTextEmbeddingopen_ai/services/azure_text_embedding.pyAzureTextToImageopen_ai/services/azure_text_to_image.pyAzureTextToAudioopen_ai/services/azure_text_to_audio.pyAzureAudioToTextopen_ai/services/azure_audio_to_text.pyAzure AI InferenceAzureAIInferenceChatCompletionazure_ai_inference/services/azure_ai_inference_chat_completion.pyAzureAIInferenceTextEmbeddingazure_ai_inference/services/azure_ai_inference_text_embedding.pyAnthropicAnthropicChatCompletionanthropic/services/anthropic_chat_completion.pyAmazon BedrockBedrockChatCompletionbedrock/services/bedrock_chat_completion.pyBedrockTextCompletionbedrock/services/bedrock_text_completion.pyBedrockTextEmbeddingbedrock/services/bedrock_text_embedding.pyGoogle AIGeminiGoogleAIChatCompletiongoogle/google_ai/services/google_ai_chat_completion.pyGoogleAITextCompletiongoogle/google_ai/services/google_ai_text_completion.pyGoogleAITextEmbeddinggoogle/google_ai/services/google_ai_text_embedding.pyVertex AIGoogleAIChatCompletion等同 Google AI 类google/README.mdHuggingFaceHuggingFaceTextCompletionhugging_face/services/hf_text_completion.pyHuggingFaceTextEmbeddinghugging_face/services/hf_text_embedding.pyMistral AIMistralAIChatCompletionmistral_ai/services/mistral_ai_chat_completion.pyMistralAITextEmbeddingmistral_ai/services/mistral_ai_text_embedding.pyNvidiaNvidiaTextEmbeddingnvidia/services/nvidia_text_embedding.pyOllamaOllamaChatCompletionollama/services/ollama_chat_completion.pyOllamaTextCompletionollama/services/ollama_text_completion.pyOllamaTextEmbeddingollama/services/ollama_text_embedding.pyONNXOnnxGenAIChatCompletiononnx/services/onnx_gen_ai_chat_completion.pyOnnxGenAITextCompletiononnx/services/onnx_gen_ai_text_completion.py几点值得注意的观察Azure OpenAI 与 OpenAI 共用一个open_ai/代码库AzureChatCompletion等通过覆写请求构造/鉴权逻辑复用同一套服务实现Google AI 与 Vertex AI 共用google_ai/下的同一批类README 中两者指向相同路径差异主要体现在服务端点与鉴权配置本地/自托管生态完整HuggingFace、Ollama、ONNX、Nvidia 均覆盖了文本补全或嵌入等模态便于离线与私有化部署场景更细的接入说明可分别查阅 bedrock/README.md、google/README.md 与 nvidia/README.md。五、PromptExecutionSettings连接器与 Kernel 之间的参数契约连接器与 Kernel 通信时携带的执行参数统一由PromptExecutionSettings承载prompt_execution_settings.py。它定义在连接器目录的顶层并被init.py 导出连同FunctionChoiceBehavior与CompletionUsage是每个厂商设置子类如 OpenAI 的temperature、max_tokens的共同基类。基类核心字段service_id本次请求关联的服务 IDextension_data额外数据字典用于容纳尚未映射为显式字段的任意参数function_choice_behavior函数调用行为配置Field(excludeTrue)序列化时排除。它的机制相当精巧__init__#L52-L66会把所有未命名的**kwargs收进extension_data再调用unpack_extension_data()将其中能对应到显式字段的键解包为属性model_validator#L39-L50支持function_choice_behavior从字符串或字典自动解析为FunctionChoiceBehavior对象prepare_settings_dict#L73-L87在真正发送请求前剔除service_id、extension_data、structured_json_response及所有None值得到干净的请求参数from_prompt_execution_settings/update_from_prompt_execution_settings#L89-L105用于在不同类型设置对象之间迁移字段——这正是AIServiceClientBase.get_prompt_execution_settings_from_settings得以实现类型转换的底层能力。对于使用者而言日常最常接触的是各厂商的专属设置子类但理解基类的extension_data机制有助于排查为什么我传的参数没生效这类问题未识别的参数会先落入extension_data只有当键名与目标类的字段名一致时才会被解包到显式属性。六、从源码看连接器的实际调用链与 Kernel 的协作方式连接器并不被用户直接手动调用而是注册到Kernel后由内核统一调度。从 ChatCompletionClientBase.get_chat_message_contents 的源码可以还原一条完整的调用链用户代码 → Kernel(聊天补全) → ChatCompletionClientBase.get_chat_message_contents → 设置类型转换/深拷贝 → 函数调用行为配置 → _inner_get_chat_message_contents厂商 SDK 请求 → 可选自动调用循环kernel.invoke_function_call → 结果合并 → 下一轮 → list[ChatMessageContent] 返回给 Kernel其中函数调用环节的关键证据链包括SUPPORTS_FUNCTION_CALLING决定是否进入函数调用流程自动调用依赖kernel参数kwargs.get(kernel)若设置了函数行为却未传 kernel会抛出ServiceInvalidExecutionSettingsError#L117-L118并行工具执行使用asyncio.gather工具结果通过merge_function_results合并进ChatHistory循环受function_choice_behavior.maximum_auto_invoke_attempts约束达到上限后_reset_function_choice_settings关闭工具再进行一次收尾请求避免模型永远调函数不给答案。对应用开发者的实践启示要使用函数调用必须选择SUPPORTS_FUNCTION_CALLINGTrue的连接器OpenAI、Azure OpenAI、Anthropic、Mistral、Ollama 的聊天补全类均满足通过kernel.set_service/add_service注册连接器时ai_model_id与service_id会被用作路由标识详见 services/ai_service_client_base.py 的默认回退逻辑设置对象不要跨请求复用后担心被污染——基类在入口处会deepcopy但function_choice_behavior的configure动作仍会写回副本因此建议按请求构造设置。七、如何从零扩展一个自定义 AI Connector结合以上源码分析编写一个全新的连接器通常遵循四个步骤选择模态基类根据任务类型继承六类基类之一如果任务是聊天则继承ChatCompletionClientBase。实现内部抽象方法补全_inner_get_chat_message_contents及流式版本在其中调用目标服务 SDK并把响应包装为ChatMessageContent列表若支持函数调用将SUPPORTS_FUNCTION_CALLING覆写为True。提供专属设置类继承PromptExecutionSettings声明厂商特有的参数如temperature、top_p并让连接器覆写get_prompt_execution_settings_class()返回该类型——这样 Kernel 传入的通用设置会自动迁移为你服务的类型。处理多模态返回值语音转文本返回list[TextContent]文本转语音返回list[AudioContent]文生图返回bytes | str或直接用get_image_content得到ImageContent嵌入返回 numpyndarray。从仓库现有实现看open_ai/services/open_ai_chat_completion.py 是结构最完整的参考范本若只需接入本地模型ollama/ 与 onnx/ 的实现规模更小、更易通读。八、示例与验证路径仓库为每个模态都准备了可直接运行的示例可作为连接器用法的第一手参考聊天补全python/samples/getting_started/00-getting-started.ipynb、python/samples/getting_started/03-prompt-function-inline.ipynb 与 python/samples/concepts/chat_completion/ 目录下的全部示例函数调用自动调用循环python/samples/concepts/auto_function_calling/语音转写 / 合成python/samples/concepts/audio/文生图python/samples/concepts/images/文本嵌入python/samples/concepts/embedding/ 与 python/samples/concepts/memory/测试验证仓库在 python/tests/unit/ 与 python/tests/integration/ 下维护着连接器相关的单元与集成测试集成测试依赖python/samples/service_settings.py与sk_service_configurator.py从环境变量加载密钥说明各连接器均通过环境变量如 API Key、Endpoint、模型名完成配置。九、总结Semantic Kernel Python 的 AI Connector 体系用一个清晰的继承树解决了多厂商、多模态的接入问题AIServiceClientBase提供统一的服务身份与设置转换契约六个模态基类按任务类型定义请求/响应协议具体厂商连接器只需补齐内部实现方法 专属设置类即可接入 Kernel。开发者既可以直接选用 README 中登记的全部内置连接器OpenAI / Azure OpenAI / Azure AI Inference / Anthropic / Bedrock / Google AI / Vertex AI / HuggingFace / Mistral AI / Nvidia / Ollama / ONNX也可以依照同样的模式快速扩展自定义服务这正是 Semantic Kernel 保持模型无关model-agnostic架构的关键一环。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考