Bitzsoft.Integrations.SemanticKernel 1.0.0-alpha.5

Bitzsoft.Integrations.SemanticKernel

Semantic Kernel 编排层 -- 基于 Microsoft Semantic Kernel 的 AI 编排服务，提供对话、流式输出、插件注册与函数调用（Function Calling）能力。

功能特性

• 封装 Microsoft Semantic Kernel，Kernel 通过 DI 容器注册（微软最佳实践）
• 支持一次性响应与流式（Streaming）响应两种对话模式
• 内置系统提示词（SystemPrompt）配置，支持全局默认值与单次覆盖
• 支持 Plugin 机制：通过 ImportPluginFromType<T>() 注册原生插件
• Function Calling：SendMessageWithFunctionCallingAsync 自动识别并调用注册的 [KernelFunction] 方法
• 内置 DateTimePlugin 日期时间插件示例
• 兼容所有 OpenAI Chat Completions API 协议的服务端点

安装

dotnet add package Bitzsoft.Integrations.SemanticKernel

或通过 csproj 引用：

<PackageReference Include="Bitzsoft.Integrations.SemanticKernel" Version="*" />

配置

在 appsettings.json 中添加以下配置节：

{
  "SemanticKernel": {
    "Enabled": true,
    "ModelId": "gpt-4o",
    "Endpoint": "https://api.openai.com/v1",
    "ApiKey": "sk-your-api-key",
    "SystemPrompt": "你是一个有帮助的 AI 助手。"
  }
}

注册服务

using Bitzsoft.Integrations.SemanticKernel;
using Bitzsoft.Integrations.SemanticKernel.Dto;

// Program.cs / Startup.cs
services.AddSemanticKernel(options =>
{
    options.Enabled = true;
    options.ModelId = "gpt-4o";
    options.Endpoint = "https://api.openai.com/v1";
    options.ApiKey = "sk-your-api-key";
    options.SystemPrompt = "你是一个专业的企业知识库助手。";
});

架构说明：AddSemanticKernel 通过 DI 工厂注册 Kernel（Singleton），遵循微软最佳实践——消费方可直接注入 Kernel、ISemanticKernelClient 或 SK 的 IChatCompletionService。

使用示例

基础对话

using Bitzsoft.Integrations.SemanticKernel;

public class ChatService
{
    private readonly ISemanticKernelClient _kernelClient;

    public ChatService(ISemanticKernelClient kernelClient)
    {
        _kernelClient = kernelClient;
    }

    /// <summary>
    /// 回答用户问题
    /// </summary>
    public async Task<string> AnswerQuestionAsync(string question, CancellationToken ct = default)
    {
        // 使用全局默认 SystemPrompt
        return await _kernelClient.SendMessageAsync(question, cancellationToken: ct);
    }

    /// <summary>
    /// 带自定义角色的对话
    /// </summary>
    public async Task<string> ChatAsExpertAsync(string userMessage, CancellationToken ct = default)
    {
        return await _kernelClient.SendMessageAsync(
            message: userMessage,
            systemPrompt: "你是一位资深 .NET 架构师，擅长系统设计与性能优化。",
            cancellationToken: ct);
    }
}

流式响应（Streaming）

using System.Runtime.CompilerServices;
using Bitzsoft.Integrations.SemanticKernel;

public class StreamingChatService
{
    private readonly ISemanticKernelClient _kernelClient;

    public StreamingChatService(ISemanticKernelClient kernelClient)
    {
        _kernelClient = kernelClient;
    }

    /// <summary>
    /// 流式输出 AI 响应，适合实时展示场景
    /// </summary>
    public async IAsyncEnumerable<string> StreamReplyAsync(
        string userMessage,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var chunk in _kernelClient.SendMessageStreamAsync(
            message: userMessage,
            systemPrompt: "请用简洁的方式回答问题。",
            cancellationToken: ct))
        {
            yield return chunk;
        }
    }
}

注册并使用 Plugin

using System.ComponentModel;
using Bitzsoft.Integrations.SemanticKernel;
using Microsoft.SemanticKernel;

// 定义一个业务插件
public class OrderQueryPlugin
{
    [KernelFunction("query_order")]
    [Description("根据订单号查询订单状态")]
    public string QueryOrder(string orderId)
    {
        // 实际业务中此处调用订单服务
        return $"订单 {orderId} 状态：已发货";
    }
}

// 在应用启动时注册插件
public class PluginSetupService(IServiceProvider provider) : IHostedService
{
    public Task StartAsync(CancellationToken ct)
    {
        var client = provider.GetRequiredService<ISemanticKernelClient>();

        // 注册类型插件
        client.ImportPluginFromType<OrderQueryPlugin>("OrderQuery");

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

Function Calling（自动函数调用）

注册插件后，通过 SendMessageWithFunctionCallingAsync 让 AI 自动识别并调用已注册的工具方法：

using Bitzsoft.Integrations.SemanticKernel;
using Bitzsoft.Integrations.SemanticKernel.Plugins;

// 1. 注册内置日期时间插件（GetCurrentDateTime / GetDaysBetween 等）
client.ImportPluginFromType<DateTimePlugin>("DateTime");

// 2. AI 将自动调用 DateTimePlugin 获取当前时间来回答
var answer = await client.SendMessageWithFunctionCallingAsync(
    message: "今天是几号？距离 2026-12-31 还有多少天？",
    systemPrompt: "你是一个智能助手");

内置 DateTimePlugin 提供：GetCurrentDateTime、GetCurrentDate、GetDaysBetween 三个工具方法。

直接访问 Kernel 实例

using Bitzsoft.Integrations.SemanticKernel;
using Microsoft.SemanticKernel;

public class AdvancedKernelService
{
    private readonly ISemanticKernelClient _kernelClient;

    public AdvancedKernelService(ISemanticKernelClient kernelClient)
    {
        _kernelClient = kernelClient;
    }

    public async Task<string> ExecutePromptAsync(string promptTemplate, CancellationToken ct = default)
    {
        // 通过 Kernel 属性直接使用 Semantic Kernel 原生 API
        var result = await _kernelClient.Kernel.InvokePromptAsync(promptTemplate, cancellationToken: ct);
        return result.ToString();
    }
}

相关包