Bitzsoft.Integrations.AI 1.0.0-alpha.7

Bitzsoft.Integrations.AI

AI 服务集成 — 基于 Microsoft.Extensions.AI 的 IChatClient 抽象，提供轻量 OpenAI 兼容客户端。

功能特性

• 基于 Microsoft.Extensions.AI.IChatClient 标准抽象，Provider 无关
• 兼容所有 OpenAI Chat Completions API 协议的服务商（OpenAI、DeepSeek、通义千问等）
• 支持命名客户端（Keyed DI），满足多租户或多模型场景
• 支持结构化输出（GetObjectAsync<T>），直接获取强类型对象
• 内置 MEAI 中间件管道：OpenTelemetry 遥测、分布式缓存、日志记录
• HttpClient 已接入 Bitzsoft.Integrations.RequestLogging 第三方请求日志

安装

dotnet add package Bitzsoft.Integrations.AI

配置

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

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

兼容历史配置：ApiUrl 映射到 Endpoint，DefaultModel 映射到 ModelId。

注册服务

基础注册

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.AI;

// Program.cs
services.AddBitzChatClient(options =>
{
    options.Endpoint = "https://api.openai.com/v1";
    options.ApiKey = "sk-your-api-key";
    options.ModelId = "gpt-4o";
});

多租户 / 多模型注册

// 注册 GPT-4o 客户端
services.AddBitzChatClient("GPT4", options =>
{
    options.Endpoint = "https://api.openai.com/v1";
    options.ApiKey = "sk-openai-key";
    options.ModelId = "gpt-4o";
});

// 注册 DeepSeek 客户端
services.AddBitzChatClient("DeepSeek", options =>
{
    options.Endpoint = "https://api.deepseek.com/v1";
    options.ApiKey = "sk-deepseek-key";
    options.ModelId = "deepseek-chat";
});

第三方请求日志

机制说明：本连接器基于 Microsoft.Extensions.AI 的 IChatClient 抽象，HTTP 管道由 IChatClient 实现内部管理，无法用 DelegatingHandler 拦截（与 HttpClient 直连实现不同）。请求日志改由 RequestLoggingChatClient 包装层实现：它实现 IChatClient，在每次对话补全调用前后经 IRequestLogRecorder 钩子记录，汇入与 HttpClient 拦截同一个日志管道（IRequestLogStore），由宿主统一持久化。

记录内容（每次对话补全调用产生一条）：

局限：

• IChatClient 不暴露原始 HTTP 状态码与响应头，无法像 HttpClient 拦截那样记录真实 HTTP StatusCode/RequestHeaders，StatusCode 在成功时记 200，异常时留空。
• 仅本连接器实现的对话补全调用会被记录；IChatClient 管道的其他能力（如嵌入、音频等，本连接器未使用）不在记录范围。

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

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

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

使用示例

注入并使用 IChatClient

using Microsoft.Extensions.AI;

public class DocumentService(IChatClient chatClient)
{
    /// <summary>
    /// 对文档内容进行摘要提取
    /// </summary>
    public async Task<string> SummarizeAsync(string documentContent, CancellationToken ct = default)
    {
        var messages = new List<ChatMessage>
        {
            new(ChatRole.System, "你是一个专业的文档摘要助手。"),
            new(ChatRole.User, $"请对以下文档内容进行摘要：\n\n{documentContent}")
        };

        var response = await chatClient.GetResponseAsync(messages, cancellationToken: ct);
        return response.Text;
    }

    /// <summary>
    /// 流式输出
    /// </summary>
    public async IAsyncEnumerable<string> SummarizeStreamAsync(
        string documentContent,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        var messages = new List<ChatMessage>
        {
            new(ChatRole.System, "你是一个专业的文档摘要助手。"),
            new(ChatRole.User, documentContent)
        };

        await foreach (var update in chatClient.GetStreamingResponseAsync(messages, cancellationToken: ct))
        {
            if (update.Text is not null)
            {
                yield return update.Text;
            }
        }
    }
}

结构化输出（Structured Output）

通过 GetObjectAsync<T> 直接获取强类型对象，无需手动 JSON 反序列化：

using Bitzsoft.Integrations.AI;

// 定义返回类型
public record SentimentResult(string Sentiment, double Confidence, string Summary);

public class AnalysisService(IChatClient chatClient)
{
    public async Task<SentimentResult?> AnalyzeAsync(string text, CancellationToken ct = default)
    {
        return await chatClient.GetObjectAsync<SentimentResult>(
            message: $"请分析以下文本的情感倾向：\n{text}",
            systemPrompt: "你是情感分析助手，返回 JSON 格式：sentiment（正面/负面/中性）、confidence（0-1）、summary");
    }
}

使用命名客户端（多模型场景）

public class MultiModelService(
    [FromKeyedServices("BitzChatClient_GPT4")] IChatClient gpt4Client,
    [FromKeyedServices("BitzChatClient_DeepSeek")] IChatClient deepseekClient)
{
    public Task<string> AskGptAsync(string question) =>
        gpt4Client.GetResponseAsync(question);

    public Task<string> AskDeepSeekAsync(string question) =>
        deepseekClient.GetResponseAsync(question);
}

相关包