展开本页目录
开始前准备什么
- 独立 Python 虚拟环境；本次 Semantic Kernel 1.45.0 与 OpenAI 3.26.0。
- 准备支持 Chat Completions 的准确模型 ID。
- 首次只安装本页版本文件；不要与其他 Agent 环境混装。
- 创建自定义客户端
- 映射服务标签
- 加入 ChatHistory
- 验证一次文字
- 扩展受限插件
2026-10-25 资料复核与操作补充
继续操作前，核对当前配置与执行范围
这里的已验证范围为锁定SDK构造与离线路由示例；在线模型权限、插件执行和向量服务仍按各自实际记录确认。直接AsyncOpenAI成功不能替代Semantic Kernel服务的调用记录。
原记录范围：本页保留原有配置、离线检查和历史记录；本轮没有新增该客户端或协议的在线运行记录。 下列相邻实验各有自己的日期、模型和产物，不替代本篇客户端或协议的原生验收。
把客户端传入服务，避免读错默认地址
完整下载包含 imports、asyncio、客户端关闭与 --run 门禁。这个入口调用 Chat Completions；它没有将 Chat 参数转成 Responses，也不默认启用自动插件执行。
semantic-kernel-chat.py 核心片段
client = AsyncOpenAI(
api_key=os.environ["tokenba_API_KEY"],
base_url="https://api.apizt.com/v1",
max_retries=0, timeout=30,
)
service = OpenAIChatCompletion(
ai_model_id=os.environ["tokenba_MODEL"],
service_id="apizt", async_client=client,
)
history = ChatHistory()
history.add_user_message("仅回答 tokenba_OK")
settings = OpenAIChatPromptExecutionSettings(
service_id="apizt", max_tokens=64)
result = await service.get_chat_message_contents(
chat_history=history, settings=settings)
本站绘制的内容说明图：此页 Chat 入口显式注入客户端，避免使用默认地址；没有自动把 Chat 参数转换成 Responses。
三类 ID 分别承担什么
| 字段 | 例子 | 含义 |
|---|---|---|
| ai_model_id | 从 apizt 目录复制准确 ID | 决定调用的模型 |
| service_id | apizt | 应用服务标签；与 execution settings 对齐 |
| Kernel function / plugin | 自己的本地函数名称 | 应用能力；不是模型供应商或渠道名 |
| Base URL | https://api.apizt.com/v1 | HTTP 协议入口，不填写主站网址 |
- 字段
- ai_model_id
- 例子
- 从 apizt 目录复制准确 ID
- 含义
- 决定调用的模型
- 字段
- service_id
- 例子
- apizt
- 含义
- 应用服务标签；与 execution settings 对齐
- 字段
- Kernel function / plugin
- 例子
- 自己的本地函数名称
- 含义
- 应用能力；不是模型供应商或渠道名
- 字段
- Base URL
- 例子
- https://api.apizt.com/v1
- 含义
- HTTP 协议入口，不填写主站网址
独立环境跑一次固定文字
--offline 使用真实 Semantic Kernel 服务与 OpenAI 客户端，由 mock 返回固定 Chat JSON，检查请求路径和型号；不访问真实模型。首次真实运行只做文字，不同时接入插件、向量库或批处理。
在下载目录运行
python3 -m venv .venv-semantic-kernel
.venv-semantic-kernel/bin/python -m pip install -r semantic-kernel-requirements.txt
.venv-semantic-kernel/bin/python semantic-kernel-chat.py
.venv-semantic-kernel/bin/python semantic-kernel-chat.py --offline
# 在自己的安全环境提供 Key 和准确 Model ID 后
.venv-semantic-kernel/bin/python semantic-kernel-chat.py --run聊天、插件和向量服务分别接入
| 能力 | 下一步验证 | 不能省略 |
|---|---|---|
| 聊天 | 准确型号、正文、usage | 目标通道的真实权限 |
| Kernel plugin | 函数 schema、参数、执行权限与真实结果 | 普通文字成功不代表自动 function calling |
| Embedding | 独立服务、模型和维度 | Chat 型号不等于向量型号 |
| Rerank | 独立端点与请求格式 | 不能把 Chat endpoint 当重排 |
- 能力
- 聊天
- 下一步验证
- 准确型号、正文、usage
- 不能省略
- 目标通道的真实权限
- 能力
- Kernel plugin
- 下一步验证
- 函数 schema、参数、执行权限与真实结果
- 不能省略
- 普通文字成功不代表自动 function calling
- 能力
- Embedding
- 下一步验证
- 独立服务、模型和维度
- 不能省略
- Chat 型号不等于向量型号
- 能力
- Rerank
- 下一步验证
- 独立端点与请求格式
- 不能省略
- 不能把 Chat endpoint 当重排
本站绘制的内容说明图：本页将聊天、插件、向量与重排分开；不能用同一个 Chat endpoint 代替全部服务。
版本和 Provider 边界
本页验证 Python OpenAIChatCompletion 的 async_client 路径；它不是 .NET 自定义 endpoint 示例，也没有验证 Azure 身份认证。按所用语言和版本选择 Provider，避免把 Azure deployment_id 当普通 Model ID。
本次 Agents SDK 与 Semantic Kernel 对 MCP 依赖范围不同。各页面版本文件分别用于自己的虚拟环境，不能直接拼到一个 requirements.txt。
| 现象 | 检查位置 | 处理 |
|---|---|---|
| service not found | service_id 与 execution settings | 使用相同服务标签 |
| 401 / 404 | 自定义客户端是否真的传入 | 检查地址与 Key，而非只设置全局变量 |
| 400 参数不支持 | execution settings 实际字段 | 删除可选参数，按型号逐项验证 |
| 插件结果缺失 | 工具事件和返回历史 | 保存原 call ID 与实际执行结果 |
- 现象
- service not found
- 检查位置
- service_id 与 execution settings
- 处理
- 使用相同服务标签
- 现象
- 401 / 404
- 检查位置
- 自定义客户端是否真的传入
- 处理
- 检查地址与 Key，而非只设置全局变量
- 现象
- 400 参数不支持
- 检查位置
- execution settings 实际字段
- 处理
- 删除可选参数，按型号逐项验证
- 现象
- 插件结果缺失
- 检查位置
- 工具事件和返回历史
- 处理
- 保存原 call ID 与实际执行结果
上线前保留同任务记录
- 记录版本、服务标签、Model ID、最终端点和任务输入摘要。
- 工具不自动获得业务权限；写操作需要应用批准和稳定业务 ID。
- 服务端保存 Key，禁止把私有插件结果和 Authorization 带入公开日志。
- 下载脚本没有持久化防重复，--run 再次执行会产生新请求；超时先回查。
怎样确认已经完成
- 独立环境依赖无冲突。
- 自定义客户端实际发到 /v1/chat/completions。
- service_id 与设置一致，ai_model_id 为准确型号。
- 插件、向量与费用各自有验收证据。
常见问题
service_id 可以写模型名字吗？
可以作为应用标签，但它不是上游模型选择字段。模型由 ai_model_id 决定；标签必须与执行设置一致。
这个例子支持所有 Semantic Kernel 语言吗？
本页是 Python 1.45.0 的客户端路径。.NET、Java 与其他 Provider 需按各自 API 单独配置验证。
为什么要为它单独建虚拟环境？
不同 Agent 框架可能依赖不同主版本的 MCP 等组件。本批固定版本分别安装验证，混装会扩大依赖冲突范围。