Semantic Kernel Python OpenAPI 插件实战从 OpenAPI 规范到可调用 Kernel Function 的完整示例解析【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本指南围绕python/samples/concepts/plugins/openapi目录下的 OpenAPI 语法示例展开讲解如何基于一份 OpenAPI 3.1 规范文档openapi.yaml借助 Semantic Kernel Python 的add_plugin_from_openapi能力将 REST API 操作自动转换为可被 Kernel 调用的插件函数Kernel Function并通过本地 aiohttp 服务器完成端到端请求验证。读完本文你将掌握 OpenAPI 插件的完整运行流程、参数映射规则、底层调用链以及动态 payload、SSRF 防护、认证回调等执行参数的配置方法。示例全景三个文件构成的最小可运行闭环该示例由三个文件组成构成一个规范定义 → 服务端实现 → 客户端调用的完整闭环文件角色说明openapi.yamlAPI 规范OpenAPI 3.1.0 文档定义一个POST /{name}接口operationId为helloWorldopenapi_server.py服务端基于 aiohttp 的本地 HTTP 服务器监听POST /{name}并回显路径、查询、请求体与请求头openapi_client.py客户端使用kernel.add_plugin_from_openapi将openapi.yaml注册为插件并调用helloWorld函数从源码结构看示例刻意选用本地服务器而非真实第三方 API目的是在无外部依赖的环境下完整演示OpenAPI 规范 → Kernel 插件 → HTTP 请求的语法链路因此非常适合作为学习和二次开发的起点。环境准备使用 uv 建立可复现的开发环境示例的运行依赖 Semantic Kernel Python 源码环境其通用安装说明位于 python/DEV_SETUP.md。核心工具是uv它允许直接从本地源码使用 SK无需关心包路径解析效果等同于安装了 pip 包。对于 Windows非 WSL环境可按官方 uv 安装文档安装后执行# 安装 Python 3.10、3.11、3.12 uv python install 3.10 3.11 3.12 # 创建虚拟环境可切换 3.10/3.11/3.12 uv venv --python 3.10 # 安装 SK 及全部依赖 uv sync --all-extras --dev对于 Mac 和 Linux含 WSL可直接使用仓库自带的 Makefile 目标make install如需指定 Python 版本可通过PYTHON_VERSION环境变量控制make install PYTHON_VERSION3.12分步运行两终端、四步骤完成端到端调用原文档给出了清晰的运行步骤这里补充每一步的目的与细节第 1 步进入示例目录cd semantic_kernel/python/samples/concepts/plugins/openapi第 2 步同步依赖并激活虚拟环境uv sync source .venv/bin/activateuv sync会根据仓库的uv.lock位于 python/uv.lock锁定并安装全部依赖source .venv/bin/activate用于激活虚拟环境。文档特别提醒取决于操作系统activate 脚本可能位于不同位置——例如 Windows 下通常是.venv\Scripts\activate。第 3 步启动本地 API 服务器python openapi_server.py该命令启动 aiohttp 应用默认监听localhost:8080端口来源于openapi.yaml中servers节点的声明见下文。启动后终端会持续输出访问日志保持运行。第 4 步另开终端重复第 1、2 步后运行客户端python openapi_client.py客户端将注册一个代表openapi.yaml所定义 API 的插件执行helloWorld函数并向第 3 步启动的服务器发起真实的 HTTP 请求。在客户端终端应能看到类似Hello, John: q0.7, body{input: hello world}, headers...的输出具体内容由服务器端回显逻辑决定。规范即契约逐字段解析 openapi.yamlopenapi.yaml 是一份精简但完整的 OpenAPI 3.1.0 文档其结构如下openapi: 3.1.0 info: title: Test API version: 1.0.0 servers: - url: http://localhost:8080 paths: /{name}: post: summary: Hello World operationId: helloWorld requestBody: required: true content: application/json: schema: type: object properties: input: type: string description: The input of the request example: Howdy responses: 200: description: OK parameters: - name: name in: path required: true schema: type: string description: Your name - name: Header in: header required: true schema: type: string description: The header - name: q in: query required: false schema: type: string description: The query parameter各关键节点的作用如下servers[0].url声明服务器基地址为http://localhost:8080。OpenAPI 插件解析后会用该地址拼接操作路径构造最终请求 URL。operationId: helloWorld这是语义内核映射函数名的关键。插件中每个 OpenAPI 操作会被包装为一个以operationId命名的 Kernel Function因此客户端可以用openapi_plugin[helloWorld]获取对应函数。parameters声明三个参数覆盖了 REST 参数的三类常见位置namein: path必填路径参数会被替换进/{name}中的占位符Headerin: header必填请求头参数大小写敏感与客户端传入的Headerexample-header一一对应qin: query可选查询字符串参数。requestBody声明application/json请求体含一个input字符串属性。这是动态 payload机制的数据来源——客户端无需手动构造完整 JSON只需按属性名传入参数由运行时自动组装请求体详见下文。服务端实现aiohttp 如何回显各类参数openapi_server.py 使用 aiohttp 实现核心代码如下from aiohttp import web routes web.RouteTableDef() routes.post(/{name}) async def hello(request): # 路径参数 name request.match_info.get(name, ) # 查询参数 q request.rel_url.query.get(q, ) # 请求体 body await request.json() # 请求头 headers request.headers return web.Response(textfHello, {name}: q{q}, body{body}, headers{headers}) app web.Application() app.add_routes(routes) if __name__ __main__: web.run_app(app)该服务器的作用是照单全收分别从match_info路径、rel_url.query查询串、request.json()请求体和request.headers请求头提取客户端发送的全部数据并原样回显。这使开发者可以直观地核对客户端插件是否按照openapi.yaml的声明将name、q、input、Header正确放到了对应的 HTTP 位置——这正是该示例作为语法验证器的价值所在。客户端调用三行核心代码背后的调用链openapi_client.py 的核心逻辑非常紧凑from semantic_kernel import Kernel from semantic_kernel.functions.kernel_arguments import KernelArguments async def main(): kernel Kernel() spec_path os.path.join( os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))), plugins, openapi, openapi.yaml, ) openapi_plugin kernel.add_plugin_from_openapi( plugin_nameopenApiPlugin, openapi_document_pathspec_path, ) arguments KernelArguments( inputhello world, nameJohn, q0.7, Headerexample-header, ) result await kernel.invoke(openapi_plugin[helloWorld], argumentsarguments) print(result)这里有几个值得注意的细节spec_path的动态定位客户端通过os.path.realpath(__file__)向上回溯三层目录拼出plugins/openapi/openapi.yaml的绝对路径而不是写死路径。这样无论从哪个工作目录启动脚本都能正确定位规范文件。插件注册kernel.add_plugin_from_openapi是入口方法plugin_nameopenApiPlugin定义了插件的命名空间openapi_document_path指向规范文件。KernelArguments中input、name、q、Header分别对应规范中的请求体属性、路径参数、查询参数与请求头参数。函数调用openapi_plugin[helloWorld]按operationId索引到包装后的 Kernel Functionkernel.invoke执行后返回KernelResult并打印。从源码实现看add_plugin_from_openapi最终落在 kernel_plugin.py 的KernelPlugin.from_openapi类方法上。该方法要求openapi_document_path与openapi_parsed_spec至少提供一个否则抛出PluginInitializationError随后调用 openapi_manager.py 中的create_functions_from_openapi该函数被experimental装饰器标记属于实验性 API完成规范 → 函数的转换。底层调用链规范如何变成可执行函数create_functions_from_openapi的执行流程可以概括为四个阶段解析Parse使用OpenApiParser位于 openapi_parser.py读取 YAML 文档生成解析后的规范字典。建模Model将规范转换为RestApiOperation等 REST 操作模型位于 models 目录含RestApiParameter、RestApiPayload、RestApiSecurityRequirement、RestApiUri等类型。包装Wrap对每个操作创建一个kernel_function装饰的异步闭包run_openapi_operation函数名取operation.id即operationId描述取自operation.summary或operation.description。注册Register将闭包包装为KernelFunctionFromMethod并把 HTTP 方法、服务器 URL、安全要求等写入additional_metadata最终返回函数列表。参数映射与必填校验包装函数执行时会遍历该操作的全部RestApiParameter按以下规则从kwargs中取值见 openapi_manager.py优先使用参数的alternative_name即规范参数名其次使用name找到且值非None时写入KernelArguments若参数标记为is_required但调用时缺失则抛出FunctionExecutionException提示没有找到可用于 REST 函数{plugin_name}.{operation.id}参数{parameter.name}的变量。同时每个参数都会转换为KernelParameterMetadata名称、描述、默认值、是否必填、类型及 schema这使得 OpenAPI 插件函数可以被 Kernel 的自动函数调用function calling机制识别向 LLM 暴露正确的参数 schema。请求构建URL、查询串与动态 payload请求的最终构造在 openapi_runner.py 的OpenApiRunner中完成URL 构建build_operation_url将路径参数替换进模板路径build_query_string从参数中收集in: query的参数生成查询串再通过build_full_url拼接出完整 URL。动态 payload默认开启当enable_dynamic_payloadTrue时build_json_payload依据规范中requestBody的 schema 逐属性从参数中取值自动组装 JSON 请求体必需属性缺失时抛出FunctionExecutionException。这正是客户端只需传inputhello world而不必手工构造 JSON 的原因。静态 payload关闭动态模式时若enable_dynamic_payloadFalse则要求通过名为payload的字符串参数直接提供完整请求体。enable_payload_namespacing开启后嵌套对象属性会以属性路径的命名空间形式映射为扁平参数便于大模型直接传参。执行参数详解OpenAPIFunctionExecutionParameters 全字段若需要定制插件行为可通过 openapi_function_execution_parameters.py 中的OpenAPIFunctionExecutionParameters基于 pydantic 的KernelBaseModel向from_openapi传入execution_settings。全部字段如下字段类型默认值说明http_clienthttpx.AsyncClient \| NoneNone自定义 HTTP 客户端可注入代理、TLS 配置等auth_callback异步回调None认证回调执行请求前调用返回请求头字典用于注入令牌等凭据server_url_overridestr \| NoneNone覆盖规范中声明的服务器 URL若格式非法会在初始化时抛出ValueErrorignore_non_compliant_errorsboolFalse是否忽略不符合规范的错误user_agentstr \| None默认 SK UA请求 User-Agent未设置时自动使用 Semantic Kernel 的HTTP_USER_AGENTenable_dynamic_payloadboolTrue是否根据 schema 动态组装请求体enable_payload_namespacingboolFalse是否将嵌套 payload 属性扁平化为命名空间参数operations_to_excludelist[str][]需要排除的operationId列表用于过滤不希望暴露给 Kernel 的操作operation_selection_predicate回调None操作选择谓词接收OperationSelectionPredicateContext返回bool决定是否注册该操作timeoutfloat \| NoneNoneHTTP 请求超时秒为None时使用 httpx 默认值 5 秒enable_file_ref_resolutionboolFalse是否解析 OpenAPI 文档中的本地文件$ref引用适用于规范拆分为多个本地文件的场景仅信任来源时开启enable_http_ref_resolutionboolFalse是否解析外部 HTTP$ref引用默认关闭仅在信任文档来源时开启server_url_validation_allowed_base_urlslist[str][]显式信任的基地址白名单匹配的 URL 可绕过默认的 HTTPS-only 与私有网络校验allow_private_network_accessboolFalse是否允许请求目标为私网、回环loopback、链路本地等非公网地址注意示例中的http://localhost:8080属于回环地址。根据默认的 URL 校验策略这类请求默认会被拦截因此在客户端脚本中不会显式配置allow_private_network_access其实际处理依赖运行时的默认行为——在自行搭建类似本地示例时若请求被安全校验拦截需要通过server_url_validation_allowed_base_urls显式放行http://localhost:8080或设置allow_private_network_accessTrue。安全机制默认开启的 SSRF 防护OpenAPIFunctionExecutionParameters的类文档明确说明OpenAPI 操作请求 URL默认经过校验以降低 SSRF 风险——请求必须使用 HTTPS且不得解析到私网、回环、链路本地等非公网 IP 地址除非目标通过server_url_validation_allowed_base_urls显式信任或通过allow_private_network_access放开私有网络访问。相关校验逻辑位于 server_url_validator.pyServerUrlValidationOptions/validate_server_url。这一设计意味着当你的openapi.yaml来自不可信的第三方来源时即便其中声明了内网地址插件默认也不会向内网发起请求从而避免恶意规范被用作 SSRF 攻击跳板。在配置自己的 OpenAPI 插件时应遵循最小信任原则只在明确需要时修改这两个字段。进阶指引如何把示例改造成真实 API 插件在理解示例后替换为真实 API 只需三步替换规范文件将openapi.yaml换成目标 API 的 OpenAPI 3.x 文档语义内核使用openapi_core进行规范解析与请求校验支持 JSON Pointer 内部引用跨文件/HTTP 引用需按上文说明显式开启。调整服务器 URL确认规范中servers声明的是可访问的 HTTPS 公网地址若使用内网或本地服务需同步配置 URL 白名单。按需注入认证若 API 需要鉴权通过execution_settings传入auth_callback在回调中返回携带访问令牌如 Bearer Token的请求头字典需要精细化控制时还可使用operation_selection_predicate与operations_to_exclude只暴露必要的操作。完成上述替换后即可让 LLM 通过函数调用机制自动发现并调用这些由 OpenAPI 规范生成的 Kernel Functions实现自然语言 → 结构化 API 调用的完整链路。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考