Bitzsoft.Integrations.AI.Abstractions 1.0.0-alpha.10

Bitzsoft.Integrations.AI.Abstractions

AI 集成的共享契约包。它定义 Provider Profile、模型能力、租户感知聊天与向量 Factory 以及 Provider Adapter Seam；不绑定具体厂商 SDK。

安装与兼容性

dotnet add package Bitzsoft.Integrations.AI.Abstractions

• 目标框架：net8.0;net10.0；
• 依赖 Microsoft.Extensions.AI.Abstractions 和 Bitzsoft.Integrations.Core；
• 适合由宿主、基础设施 Adapter 和其他 AI 包共同引用；
• .NET 5 系统应通过独立的 .NET 8/10 AI 服务调用。

主要契约

| 类型 | 职责 | |---|---| | AiOptions | 一个命名客户端的非敏感 Provider、Profile、Endpoint、Model 与管道开关 | | AIEmbeddingOptions | 一个命名文本向量生成器的非敏感模型、维度与管道配置 | | AIProviderProfile | 协议、默认端点、保守能力与限制的不可变描述 | | AIModelCapabilities | Chat、Streaming、Tools、Structured Output、Vision、Reasoning 等能力标志 | | IAIProviderProfileCatalog | 查询已注册 Profile | | IAIChatClientFactory | 按命名配置和当前租户上下文创建短生命周期 IChatClient | | IAIChatClientProviderAdapter | 把一种协议转换为 IChatClient 的扩展 Seam | | IAIEmbeddingGeneratorFactory | 按命名配置和当前租户上下文创建短生命周期文本向量生成器 | | IAIEmbeddingGeneratorProviderAdapter | 把一种协议转换为 IEmbeddingGenerator 的扩展 Seam | 会话持久化使用 Bitzsoft.Integrations.AgentFramework 的专用 Store/租约契约，知识数据 使用 Bitzsoft.Integrations.RAG.IKnowledgeStore，工具则通过 Agent 或 MCP 显式注册。 本包不提供可从数据库反射加载任意类型/方法的“技能注册表”，避免把配置数据变成代码执行 入口。

配置模型

AiOptions 只允许非敏感数据：

var options = new AiOptions
{
    // ProviderId 参与凭据键，允许同一 Profile 配置多个账户或地域。
    ProviderId = "openai-prod",
    // ProfileId 只描述协议、默认端点和已确认能力。
    ProfileId = "openai-responses",
    ModelId = "approved-model",
    CredentialName = "default",
    // 三个管道开关不应承载敏感数据。
    EnableTelemetry = true,
    EnableLogging = true,
    EnableRequestAudit = true
};

Endpoint 为空时使用 Profile 默认值；覆盖值必须使用 HTTPS，只有 loopback 可以使用 HTTP；端点不能包含 userinfo、query 或 fragment。ApiKey 不存在于 Options，由 Core IIntegrationCredentialResolver 在调用时解析。

向量配置同样不保存凭据：

var embeddingOptions = new AIEmbeddingOptions
{
    // 聊天与向量可以使用不同 ProviderId 和独立凭据。
    ProviderId = "qwen-prod",
    ProfileId = "qwen",
    ModelId = "text-embedding-v4",
    // 固定维度必须与向量数据库 Schema 一致。
    Dimensions = 1024,
    CredentialName = "default"
};

固定 Dimensions 是索引 Schema 契约。模型或维度变化需要版本化 Collection 和重建索引， 不能在旧 Collection 中混写不同维度。

自定义 Adapter

实现全新协议时，具体 Adapter 包应同时引用 Bitzsoft.Integrations.AI.Abstractions 与 Bitzsoft.Integrations.AI。前者提供 Factory/Adapter 契约，后者提供运行时注册、统一凭据字段和 Profile 目录。

下面是可直接放入具体厂商包的完整骨架。ICompanyAIClientFactory 由该厂商包使用官方 SDK 实现；注册方法接收工厂实例，因此示例没有隐藏的类型或全局变量：

using Bitzsoft.Integrations.AI;
using Bitzsoft.Integrations.AI.Abstractions;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;

public interface ICompanyAIClientFactory
{
    IChatClient CreateChatClient(
        Uri endpoint,
        string modelId,
        string apiKey);

    IEmbeddingGenerator<string, Embedding<float>> CreateEmbeddingGenerator(
        Uri endpoint,
        string modelId,
        int? dimensions,
        string apiKey);
}

public sealed class PrivateProviderAdapter :
    IAIChatClientProviderAdapter
{
    private readonly ICompanyAIClientFactory _factory;

    public PrivateProviderAdapter(ICompanyAIClientFactory factory)
        => _factory = factory;

    public bool Supports(AIProviderProtocol protocol)
        => protocol == AIProviderProtocol.Custom;

    public IChatClient CreateClient(
        AIChatClientCreationContext context)
    {
        // 凭据快照只在 CreateClient 返回前有效，不能被 Adapter 缓存。
        var apiKey = context.Credential.GetRequiredSecret(
            AICredentialFieldNames.ApiKey);
        return _factory.CreateChatClient(
            context.Endpoint,
            context.ModelId,
            apiKey);
    }
}

public sealed class PrivateEmbeddingAdapter :
    IAIEmbeddingGeneratorProviderAdapter
{
    private readonly ICompanyAIClientFactory _factory;

    public PrivateEmbeddingAdapter(ICompanyAIClientFactory factory)
        => _factory = factory;

    public bool Supports(AIProviderProtocol protocol)
        => protocol == AIProviderProtocol.Custom;

    public IEmbeddingGenerator<string, Embedding<float>> CreateGenerator(
        AIEmbeddingGeneratorCreationContext context)
        => _factory.CreateEmbeddingGenerator(
            context.Endpoint,
            context.ModelId,
            context.Dimensions,
            context.Credential.GetRequiredSecret(
                AICredentialFieldNames.ApiKey));
}

public static class CompanyAIServiceCollectionExtensions
{
    public static IServiceCollection AddCompanyAI(
        this IServiceCollection services,
        ICompanyAIClientFactory sdkFactory)
    {
        ArgumentNullException.ThrowIfNull(services);
        ArgumentNullException.ThrowIfNull(sdkFactory);

        // SDK 工厂拥有 SDK 初始化细节，但不能缓存租户凭据。
        services.AddSingleton(sdkFactory);
        services.AddSingleton<
            IAIChatClientProviderAdapter,
            PrivateProviderAdapter>();
        services.AddSingleton<
            IAIEmbeddingGeneratorProviderAdapter,
            PrivateEmbeddingAdapter>();

        // Custom Profile 只声明已经通过真实账户契约测试的能力。
        services.AddBitzAIProviderProfile(new AIProviderProfile(
            profileId: "company-ai",
            displayName: "Company AI",
            protocol: AIProviderProtocol.Custom,
            defaultEndpoint: new Uri("https://ai.company.example/"),
            capabilities:
                AIModelCapabilities.Chat |
                AIModelCapabilities.Streaming |
                AIModelCapabilities.Embeddings));
        return services;
    }
}

Adapter 不拥有创建上下文中的 Credential，必须在创建方法返回前复制 SDK 所需的 密钥值。返回客户端/生成器的所有权归 Factory 调用方。不要捕获凭据对象，也不要把密钥 写入异常、日志、遥测标签或 GetService 元数据。生产实现还要为 SDK 客户端补齐取消、 超时、流式释放和真实账户契约测试。

若供应商本身兼容 OpenAI 协议，不需要自建 Adapter；注册 AIProviderProtocol.OpenAIChatCompletions 的自定义 Profile 即可复用内置实现。

数据与安全边界

• Provider 配置只保存 CredentialName，不能保存 API Key、Token 或私钥；
• Agent/RAG 的 Store 查询必须把 tenant 作为强制条件，不能依赖事后过滤；
• System Prompt、对话、工具参数和模型响应可能包含商业秘密或个人信息；
• 模型和技能配置应版本化，历史会话应能追溯对应版本；
• 技能元数据不是执行授权，工具执行边界必须重新做身份、租户、资源和参数校验；
• 模型输出不能未经验证进入 SQL、Shell、HTML、模板、文件路径或有副作用操作。

具体模型注册与内置 Profile 请参阅 Bitzsoft.Integrations.AI。