Loading...

文章背景图

Semantic Kernel:微软出品的模型无关企业级 Agent 编排 SDK|部署与使用全指南

2026-11-02
0
- 字
- 分钟
|

Semantic Kernel:微软出品的模型无关企业级 Agent 编排 SDK|部署与使用全指南

项目仓库: https://github.com/microsoft/semantic-kernel

开源协议:MIT(© Microsoft Corporation)· 支持语言:Python 3.10+ / .NET 10.0+ / Java JDK 17+ · 交付形态:SDK(NuGet / PyPI / Maven)· 官方文档:learn.microsoft.com/semantic-kernel

官方重要提示(README 顶部):Semantic Kernel 现已由 Microsoft Agent Framework(MAF) 接棒。MAF 1.0 已作为生产就绪版本发布,提供企业级多 Agent 编排、多提供者模型支持与 A2A / MCP 跨运行时互操作。迁移路径见官方 migration guide。


1 项目简介

Semantic Kernel 是微软开源的模型无关 SDK,用于构建、编排、部署 AI Agent 与多 Agent 系统。无论简单聊天机器人还是复杂多 Agent 工作流,它都提供企业级可靠性与灵活性。

1.1 核心信息一览

项目项 内容
项目名称 Semantic Kernel(SK)
仓库地址 github.com/microsoft/semantic-kernel
项目定位 模型无关的企业级 Agent 编排 SDK
开源协议 MIT
支持语言 Python 3.10+、.NET 10.0+、Java JDK 17+
操作系统 Windows / macOS / Linux
包 semantic-kernel(PyPI)、Microsoft.SemanticKernel(NuGet)
模型接入 OpenAI、Azure OpenAI、Hugging Face、NVidia、Ollama、LMStudio、ONNX 等
向量库 Azure AI Search、Elasticsearch、Chroma 等
官方文档 learn.microsoft.com/semantic-kernel
继任者 Microsoft Agent Framework 1.0(生产就绪)

1.2 适用场景

  • 已经在用 .NET / Python 企业栈,希望把 LLM 能力以 SDK 方式嵌入现有应用。
  • 需要多 Agent 协作(如 Triage → Billing / Refund),用代码而不是可视化编排器描述。
  • 同时对接 OpenAI、Azure OpenAI、本地 Ollama、Hugging Face 等多个模型后端。
  • 需要企业级可观测性、安全与稳定 API 承诺。

1.3 能力边界(官方口径)

  • README 顶部明确:SK 已被 MAF 1.0 接棒;新项目建议直接评估 MAF,存量项目按官方迁移路径升级。
  • SDK 本身不附带模型;需要自行准备 OpenAI / Azure OpenAI 等凭据。
  • 插件、记忆、规划等能力以 SDK 抽象提供,不替代业务系统。

2 功能特性

2.1 模型灵活性

内置支持 OpenAI、Azure OpenAI、Hugging Face、NVidia 等;可本地跑 Ollama、LMStudio、ONNX。

2.2 Agent 框架

用工具 / 插件、记忆、规划能力构建模块化 Agent。

2.3 多 Agent 系统

编排协作型专家 Agent,例如 Triage Agent 把请求转给 Billing / Refund Agent。

2.4 插件生态

  • 原生代码函数;
  • 提示词模板;
  • OpenAPI 规格;
  • Model Context Protocol(MCP)。

2.5 向量库与多模态

  • 无缝集成 Azure AI Search、Elasticsearch、Chroma 等;
  • 处理文本、视觉、音频输入。

2.6 Process Framework

用结构化工作流方式建模复杂业务流程。

2.7 企业级就绪

内置可观测性、安全、稳定 API。

3 官方界面预览

SK 是 SDK,不自带 Web UI;官方示例见 detailed-samples。

4 官方跳转链接汇总

类别 链接 说明
仓库主页 github.com/microsoft/semantic-kernel 源码、README、示例
官方文档 learn.microsoft.com/semantic-kernel 概念、快速入门、API 参考
快速入门 get-started/quick-start-guide 官方入门
详细示例 detailed-samples 100+ 示例
构建 Agent frameworks/agent Agent 文档
Python API C# / Python API 参考 API 参考
MAF 继任者 Microsoft Agent Framework 1.0 生产就绪
迁移指南 from-semantic-kernel SK → MAF
Discord aka.ms/SKDiscord 社区
Issues github.com/microsoft/semantic-kernel/issues 问题上报

5 前置要求与服务器配置

5.1 软件前提

运行时 版本
Python 3.10+
.NET .NET 10.0+
Java JDK 17+
操作系统 Windows / macOS / Linux

5.2 模型凭据

# Azure OpenAI
export AZURE_OPENAI_API_KEY=AAA....

# 或直接用 OpenAI
export OPENAI_API_KEY=sk-...

5.3 服务器建议

项目 最低 / 建议
操作系统 Linux(Ubuntu 22.04+)
CPU 2 核起步,4 核建议
内存 4 GB 起步,8 GB 建议
磁盘 10 GB 可用
网络 能访问 Azure OpenAI / OpenAI API

6 方式一:pip / dotnet 安装(推荐)

6.1 Python

pip install semantic-kernel

6.2 .NET

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core

6.3 Java

参见 semantic-kernel-java build。

6.4 最小 Agent(Python)

import asyncio
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

async def main():
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="You are a helpful assistant.",
    )
    response = await agent.get_response(messages="Write a haiku about Semantic Kernel.")
    print(response.content)

asyncio.run(main())

6.5 最小 Agent(.NET)

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
                Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"),
                Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY"));
var kernel = builder.Build();

ChatCompletionAgent agent = new()
{
    Name = "SK-Agent",
    Instructions = "You are a helpful assistant.",
    Kernel = kernel,
};

await foreach (AgentResponseItem<ChatMessageContent> response
    in agent.InvokeAsync("Write a haiku about Semantic Kernel."))
{
    Console.WriteLine(response.Message);
}

7 方式二:源码 / 多 Agent 示例

7.1 克隆仓库

git clone https://github.com/microsoft/semantic-kernel.git
cd semantic-kernel

7.2 带插件的 Agent(Python)

import asyncio
from typing import Annotated
from pydantic import BaseModel
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, OpenAIChatPromptExecutionSettings
from semantic_kernel.functions import kernel_function, KernelArguments

class MenuPlugin:
    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return "Special Soup: Clam Chowder\nSpecial Salad: Cobb Salad\nSpecial Drink: Chai Tea"

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"

class MenuItem(BaseModel):
    price: float
    name: str

async def main():
    settings = OpenAIChatPromptExecutionSettings()
    settings.response_format = MenuItem

    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="You are a helpful assistant.",
        plugins=[MenuPlugin()],
        arguments=KernelArguments(settings)
    )
    response = await agent.get_response(messages="What is the price of the soup special?")
    print(response.content)

asyncio.run(main())

7.3 多 Agent 系统(Python)

billing_agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="BillingAgent",
    instructions="You handle billing issues like charges, payment methods, cycles, fees, discrepancies, and payment failures."
)

refund_agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="RefundAgent",
    instructions="Assist users with refund inquiries, including eligibility, policies, processing, and status updates."
)

triage_agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(),
    name="TriageAgent",
    instructions="Evaluate user requests and forward them to BillingAgent or RefundAgent for targeted assistance.",
    plugins=[billing_agent, refund_agent],
)

8 配置项说明

8.1 环境变量

变量 作用
AZURE_OPENAI_API_KEY Azure OpenAI 密钥
AZURE_OPENAI_ENDPOINT Azure OpenAI 实例地址
AZURE_OPENAI_DEPLOYMENT Azure 部署名
OPENAI_API_KEY 直接用 OpenAI 时的密钥

8.2 插件

  • Python:@kernel_function 装饰函数;
  • .NET:[KernelFunction, Description] 标注方法;
  • 也可从 OpenAPI 规格、MCP server 导入。

8.3 结构化输出

settings = OpenAIChatPromptExecutionSettings()
settings.response_format = MenuItem  # pydantic BaseModel

9 常用运维命令

# ---- Python ----
pip install semantic-kernel
pip show semantic-kernel

# ---- .NET ----
dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core
dotnet build

# ---- 凭据 ----
export OPENAI_API_KEY=sk-...
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_ENDPOINT=...
export AZURE_OPENAI_DEPLOYMENT=...

# ---- 本地模型 ----
# 配合 Ollama / LMStudio / ONNX 使用,按官方文档配置

10 常见故障排查

10.1 认证错误

  • 检查 API Key 环境变量是否正确设置;
  • Azure OpenAI 还要核对 endpoint 与 deployment 名。

10.2 模型不可用

  • 确认 Azure OpenAI 部署已就绪;
  • 确认 OpenAI 账户有对应模型访问权限与额度。

10.3 求助方式

10.4 是否该用 MAF

README 顶部已明确:新项目建议直接评估 Microsoft Agent Framework 1.0;存量 SK 项目按官方迁移路径升级。

11 风险与合规说明

以下条款整理自官方 README 与 MIT 许可证;如与官方原文不一致,以仓库 LICENSE、README 与 learn.microsoft.com 为准。

11.1 开源协议与维护状态

SK 采用 MIT 许可证;但官方已将未来投入转向 MAF 1.0,新项目建议优先评估 MAF。

11.2 模型与 API 责任

  • SDK 不附带模型;OpenAI、Azure OpenAI、Hugging Face、NVidia 等归各自厂商。
  • 业务数据会按所选模型外发;敏感场景优先本地模型与离线配置。

11.3 自动化与工具权限

  • 插件 / 工具可以读写外部系统;生产环境应限制工具范围、保留人工审批。
  • 多 Agent 系统的行为由提示词与插件共同决定,上线前应充分测试。

11.4 免责

使用者在法律允许的最大范围内,自行承担因部署、修改、运行本项目产生的代码质量、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益,请通过 GitHub Issues 提交说明。

评论交流

文章目录