Bitzsoft.Integrations.SemanticKernel 1.0.0-alpha.6

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 协议的服务端点
• HttpClient 已接入 Bitzsoft.Integrations.RequestLogging 第三方请求日志

安装

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。

第三方请求日志

⚠️ 机制说明：本连接器基于 Microsoft Semantic Kernel，HTTP 管道封装在 Kernel 的连接器内部，无法用 DelegatingHandler 拦截（与 HttpClient 直连实现不同）。因此请求日志改由 IRequestLogRecorder 回调钩子实现——在 Semantic Kernel 调用包装层记录每次交互，汇入与 HttpClient 拦截同一个日志管道（IRequestLogStore），由宿主统一持久化。

记录内容（每次 Kernel 交互产生一条）：

局限（诚实声明）：

• Semantic Kernel 不暴露原始 HTTP 状态码与响应头，故无法像 HttpClient 拦截那样记录真实 HTTP StatusCode/RequestHeaders，StatusCode 仅为尽力而为（成功记 200、异常时留空）。
• 仅本连接器实现的交互操作会被记录；Kernel 的其他能力（如嵌入、记忆等，本连接器未使用）不在记录范围。

// ① 默认：启用回调但不持久化（日志丢弃）
services.AddSemanticKernel(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，Semantic Kernel 调用自动落库
//    AddSemanticKernel 内部已注入 IRequestLogRecorder，宿主无需再额外挂载 handler
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 0;               // 模型响应可能很长，0=不截断完整保留
    opts.SensitiveFields.Add("mySecret"); // 额外脱敏字段
});
services.AddSemanticKernel(options => { /* ... */ });

自定义 IRequestLogStore 实现（SqlSugar / Dapper / MongoDB）详见 Bitzsoft.Integrations.RequestLogging。

使用示例

基础对话

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();
    }
}

相关包