AI 管理（专业版）

你必须拥有 ABP 团队版或更高级别的许可证才能使用此模块。

⚠️ 重要通知 AI 管理模块目前处于预览阶段，尚未准备好用于生产环境。文档和实现可能会有变动。 我们建议目前仅将此模块用于评估和实验，暂时不要在生产环境中使用。

此模块基于 ABP 框架的人工智能工作区功能实现 AI（人工智能）管理能力，并允许从应用程序（包括 UI 组件和 API 端点）动态管理工作区。

如何安装

AI 管理模块在 启动模板 中未预装。你可以使用 ABP CLI 或 ABP Studio 安装它。

使用 ABP CLI:

abp add-module Volo.AIManagement

使用 ABP Studio:

打开 ABP Studio，导航到你的解决方案资源管理器，在项目上右键单击并选择导入模块。从 NuGet 选项卡中选择 Volo.AIManagement，并勾选"安装此模块"复选框。点击"确定"按钮安装模块。

软件包

此模块遵循模块开发最佳实践指南，由多个 NuGet 和 NPM 包组成。如果你想了解这些包及其之间的关系，请参阅该指南。

你可以访问AI 管理模块软件包列表页面查看与此模块相关的软件包列表。

AI 管理模块的软件包为各种使用场景设计。软件包按使用场景分组为 Volo.AIManagement.* 和 Volo.AIManagement.Client.*。这种结构有助于清晰地分离用例。

用户界面

菜单项

AI 管理模块将以下项目添加到"主"菜单：

• AI 管理: AI 管理模块的根菜单项。(AIManagement)
  • 工作区: 工作区管理页面。(AIManagement.Workspaces)

AIManagementMenus 类包含菜单项名称的常量。

页面

工作区管理

工作区页面用于管理系统中的 AI 工作区。你可以创建、编辑、复制和删除工作区。

你可以在此页面创建新的工作区或编辑现有的工作区。工作区配置包括：

• 名称: 工作区的唯一标识符（不能包含空格）
• 提供程序: AI 提供程序（OpenAI、Ollama 或自定义提供程序）
• 模型: AI 模型名称（例如，gpt-4、mistral）
• API 密钥: 身份验证密钥（如果提供程序需要）
• API 基础 URL: 自定义端点 URL（可选）
• 系统提示: 默认系统指令
• 温度: 响应随机性（0.0-1.0）
• 应用程序名称: 与特定应用程序关联
• 所需权限: 使用此工作区所需的权限

聊天界面

AI 管理模块包含一个内置的聊天界面，用于测试工作区。你可以：

• 从可用工作区中选择一个工作区
• 发送消息并接收 AI 响应
• 测试流式响应
• 在生产环境使用前验证工作区配置

访问聊天界面地址：/AIManagement/Workspaces/{WorkspaceName}

工作区配置

工作区是 AI 管理模块的核心概念。一个工作区代表一个可在整个应用程序中使用的 AI 提供程序配置。

工作区属性

创建或管理工作区时，可以配置以下属性：

*系统工作区不需要

系统工作区与动态工作区

AI 管理模块支持两种类型的工作区：

系统工作区

• 使用 PreConfigure<AbpAIWorkspaceOptions> 在代码中定义
• 无法通过 UI 删除
• 默认只读，但启用 OverrideSystemConfiguration 时可被覆盖
• 适用于必须始终可用的应用程序关键 AI 功能
• 应用程序启动时自动创建

示例：

PreConfigure<AbpAIWorkspaceOptions>(options =>
{
    options.Workspaces.Configure<MyAssistantWorkspace>(configuration =>
    {
        configuration.ConfigureChatClient(chatClientConfiguration =>
        {
            chatClientConfiguration.Builder = new ChatClientBuilder(
                sp => new OpenAIClient(apiKey).GetChatClient("gpt-4")
            );
        });
    });
});

动态工作区

• 通过 UI 或通过 IWorkspaceRepository 以编程方式创建
• 完全可管理 - 可以创建、更新、激活/停用和删除
• 与所有配置一起存储在数据库中
• 适用于用户可自定义的 AI 功能

示例（数据种子）：

var workspace = new Workspace(
    name: "CustomerSupportWorkspace",
    provider: "OpenAI",
    modelName: "gpt-4",
    apiKey: "your-api-key"
);
workspace.ApplicationName = ApplicationInfoAccessor.ApplicationName;
workspace.SystemPrompt = "You are a helpful customer support assistant.";
await _workspaceRepository.InsertAsync(workspace);

工作区命名规则

• 工作区名称必须唯一
• 工作区名称不能包含空格（使用下划线或驼峰命名法）
• 工作区名称区分大小写

权限

AI 管理模块定义了以下权限：

工作区级权限

除了模块级权限，你还可以通过设置 RequiredPermissionName 属性来限制对单个工作区的访问：

var workspace = new Workspace(
    name: "PremiumWorkspace",
    provider: "OpenAI",
    modelName: "gpt-4",
    requiredPermissionName: "MyApp.PremiumFeatures"
);

当工作区有必需的权限时：

• 只有拥有该权限的授权用户才能访问工作区端点
• 没有该权限的用户将收到授权错误

使用场景

AI 管理模块旨在支持各种使用模式，从简单的独立 AI 集成到复杂的微服务架构。该模块提供两个主要的软件包组来支持不同的场景：

• Volo.AIManagement.* 包，用于托管具有完整数据库和管理功能的 AI 管理
• Volo.AIManagement.Client.* 包，用于使用 AI 服务的客户端应用程序

场景 1：无 AI 管理依赖

使用时机： 你想在应用程序中使用 AI，但不想依赖 AI 管理模块。

在此场景中，你仅直接使用 ABP 框架的 AI 功能。你在代码中配置 AI 提供程序（如 OpenAI），不需要任何数据库或管理 UI。

所需软件包：

• Volo.Abp.AI
• 任何 Microsoft AI 扩展（例如 Microsoft.Extensions.AI.OpenAI）

配置：

public class YourModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        PreConfigure<AbpAIWorkspaceOptions>(options =>
        {
            options.Workspaces.ConfigureDefault(configuration =>
            {
                configuration.ConfigureChatClient(chatClientConfiguration =>
                {
                    chatClientConfiguration.Builder = new ChatClientBuilder(
                        sp => new OpenAIClient(apiKey).GetChatClient("gpt-4")
                    );
                });
            });
        });
    }
}

使用：

public class MyService
{
    private readonly IChatClient<TWorkspace> _chatClient;

    public MyService(IChatClient<TWorkspace> chatClient)
    {
        _chatClient = chatClient;
    }
    
    public async Task<string> GetResponseAsync(string prompt)
    {
        var response = await _chatClient.CompleteAsync(prompt);
        return response.Message.Text;
    }
}

有关工作区配置的更多详细信息，请参阅人工智能文档。

场景 2：具有领域层依赖的 AI 管理（本地执行）

使用时机： 你想在应用程序内部托管完整的 AI 管理模块，包括数据库存储和管理 UI。

在此场景中，你将安装带有数据库层的 AI 管理模块，这允许你通过 UI 或数据种子动态管理 AI 工作区。

所需软件包：

最小配置（仅后端）：

• Volo.AIManagement.EntityFrameworkCore（或 Volo.AIManagement.MongoDB）
• Volo.AIManagement.OpenAI（或其他 AI 提供程序包）

完整安装（包含 UI 和 API）：

• Volo.AIManagement.EntityFrameworkCore（或 Volo.AIManagement.MongoDB）
• Volo.AIManagement.Application
• Volo.AIManagement.HttpApi
• Volo.AIManagement.Web（用于管理 UI）
• Volo.AIManagement.OpenAI（或其他 AI 提供程序包）

注意：Volo.AIManagement.EntityFrameworkCore 传递性地包含了 Volo.AIManagement.Domain 和 Volo.Abp.AI.AIManagement 包。

工作区定义选项：

选项 1 - 系统工作区（基于代码）：

public class YourModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        PreConfigure<AbpAIWorkspaceOptions>(options =>
        {
            options.Workspaces.Configure<MyCustomWorkspace>(configuration =>
            {
                configuration.ConfigureChatClient(chatClientConfiguration =>
                {
                    // 配置将从数据库填充
                });
            });
        });
    }
}

选项 2 - 动态工作区（基于 UI）：

无需代码配置。通过以下方式定义工作区：

• AI 管理 UI（导航到 AI 管理 > 工作区）
• 在你的 DataSeeder 类中进行数据种子设定

使用聊天客户端：

public class MyService
{
    private readonly IChatClient<MyCustomWorkspace> _chatClient;

    public MyService(IChatClient<MyCustomWorkspace> chatClient)
    {
        _chatClient = chatClient;
    }
}

场景 3：具有远程执行的 AI 管理客户端

使用时机： 你想使用 AI 功能，但不想自己管理 AI 配置，而让专门的 AI 管理微服务处理所有事情。

在此场景中，你的应用程序与一个独立的 AI 管理微服务通信，该服务代表你管理配置并与 AI 提供程序通信。AI 管理服务处理所有 AI 提供程序的交互。

所需软件包：

• Volo.AIManagement.Client.HttpApi.Client

配置：

在你的 appsettings.json 中添加远程服务端点：

{
  "RemoteServices": {
    "AIManagementClient": {
      "BaseUrl": "https://your-ai-management-service.com/"
    }
  }
}

可选地在你的模块中定义工作区：

public class YourModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        PreConfigure<AbpAIWorkspaceOptions>(options =>
        {
            // 可选：预定义工作区类型以获得类型安全
            options.Workspaces.Configure<MyWorkspace>(configuration =>
            {
                // 配置将从远程服务获取
            });
        });
    }
}

使用：

public class MyService
{
    private readonly IChatCompletionClientAppService _chatService;

    public MyService(IChatCompletionClientAppService chatService)
    {
        _chatService = chatService;
    }

    public async Task<string> GetAIResponseAsync(string workspaceName, string prompt)
    {
        var request = new ChatClientCompletionRequestDto
        {
            Messages = new List<ChatMessageDto>
            {
                new ChatMessageDto { Role = "user", Content = prompt }
            }
        };

        var response = await _chatService.ChatCompletionsAsync(workspaceName, request);
        return response.Content;
    }
    
    // 对于流式响应
    public async IAsyncEnumerable<string> StreamAIResponseAsync(string workspaceName, string prompt)
    {
        var request = new ChatClientCompletionRequestDto
        {
            Messages = new List<ChatMessageDto>
            {
                new ChatMessageDto { Role = "user", Content = prompt }
            }
        };

        await foreach (var update in _chatService.StreamChatCompletionsAsync(workspaceName, request))
        {
            yield return update.Content;
        }
    }
}

场景 4：暴露客户端 HTTP 端点（代理模式）

使用时机： 你想让你的应用程序充当代理/API 网关，向其他服务或客户端应用程序暴露 AI 功能。

此场景建立在场景 3 之上，但你的应用程序暴露自己的 HTTP 端点供其他应用程序调用。然后你的应用程序将这些请求转发给 AI 管理服务。

所需软件包：

• Volo.AIManagement.Client.HttpApi.Client（用于与 AI 管理服务通信）
• Volo.AIManagement.Client.Application（应用服务）
• Volo.AIManagement.Client.HttpApi（用于暴露 HTTP 端点）
• Volo.AIManagement.Client.Web（可选，用于 UI 组件）

配置：

与场景 3 相同，在 appsettings.json 中配置远程 AI 管理服务。

使用：

配置完成后，其他应用程序可以调用你应用程序的端点：

• POST /api/ai-management-client/chat-completion 用于聊天完成
• POST /api/ai-management-client/stream-chat-completion 用于流式响应

你的应用程序充当代理，将这些请求转发给 AI 管理微服务。

对比表格

实现自定义 AI 提供程序工厂

虽然 AI 管理模块通过 Volo.AIManagement.OpenAI 包提供了对 OpenAI 的内置支持，但你可以通过实现自定义的 IChatClientFactory 轻松添加对其他 AI 提供程序的支持。

理解工厂模式

AI 管理模块使用工厂模式根据数据库中存储的提供程序配置创建 IChatClient 实例。每个提供程序（OpenAI、Ollama、Azure OpenAI 等）都需要自己的工厂实现。

创建自定义工厂

以下是如何为 Ollama 实现工厂的示例：

步骤 1：安装提供程序的 NuGet 包

首先，安装 AI 提供程序的包。对于 Ollama：

dotnet add package OllamaSharp

步骤 2：实现 IChatClientFactory 接口

创建一个实现 IChatClientFactory 的工厂类：

using Microsoft.Extensions.AI;
using OllamaSharp;
using Volo.AIManagement.Factory;
using Volo.Abp.DependencyInjection;

namespace YourNamespace;

public class OllamaChatClientFactory : IChatClientFactory, ITransientDependency
{
    public string Provider => "Ollama";

    public Task<IChatClient> CreateAsync(ChatClientCreationConfiguration configuration)
    {
        // 使用来自数据库的配置创建 Ollama 客户端
        var client = new OllamaApiClient(
            configuration.ApiBaseUrl ?? "http://localhost:11434",
            configuration.ModelName
        );

        // 作为 IChatClient 返回
        return Task.FromResult<IChatClient>(client);
    }
}

步骤 3：注册工厂

在你的模块的 ConfigureServices 方法中注册你的工厂：

public override void ConfigureServices(ServiceConfigurationContext context)
{
    Configure<ChatClientFactoryOptions>(options =>
    {
        options.AddFactory<OllamaChatClientFactory>("Ollama");
    });
}

[!提示] 对于生产场景，你可能需要为工厂配置添加验证。

可用配置属性

ChatClientCreationConfiguration 对象提供以下来自数据库的属性：

示例：Azure OpenAI 工厂

以下是实现 Azure OpenAI 工厂的示例：

using Azure.AI.OpenAI;
using Azure;
using Microsoft.Extensions.AI;
using Volo.AIManagement.Factory;
using Volo.Abp.DependencyInjection;

namespace YourNamespace;

public class AzureOpenAIChatClientFactory : IChatClientFactory, ITransientDependency
{
    public string Provider => "AzureOpenAI";

    public Task<IChatClient> CreateAsync(ChatClientCreationConfiguration configuration)
    {
        var client = new AzureOpenAIClient(
            new Uri(configuration.ApiBaseUrl ?? throw new ArgumentNullException(nameof(configuration.ApiBaseUrl))),
            new AzureKeyCredential(configuration.ApiKey ?? throw new ArgumentNullException(nameof(configuration.ApiKey)))
        );

        var chatClient = client.GetChatClient(configuration.ModelName);
        return Task.FromResult(chatClient.AsIChatClient());
    }
}

使用你的自定义提供程序

实现并注册你的工厂后：

1. 通过 UI：导航到 AI 管理工作区页面并创建新的工作区：

   • 选择你的提供程序名称（例如，"Ollama"、"AzureOpenAI"）
   • 配置 API 设置
   • 设置模型名称

2. 通过代码（数据种子）：

await _workspaceRepository.InsertAsync(new Workspace(
    GuidGenerator.Create(),
    "MyOllamaWorkspace",
    provider: "Ollama",
    modelName: "mistral",
    apiBaseUrl: "http://localhost:11434",
    description: "Local Ollama workspace"
));

提示：你在 AddFactory<TFactory>("ProviderName") 中使用的提供程序名称必须与数据库中工作区配置存储的提供程序名称匹配。

内部原理

领域层

AI 管理模块遵循领域驱动设计原则，并具有结构良好的领域层。

聚合

• Workspace：表示 AI 工作区配置的主要聚合根。

仓储

定义了以下自定义仓储：

• IWorkspaceRepository：用于工作区管理的仓储，包含自定义查询。

领域服务

• ApplicationWorkspaceManager：管理工作区操作和验证。
• WorkspaceConfigurationStore：检索工作区配置并带缓存。
• ChatClientResolver：为工作区解析适当的 IChatClient 实现。

集成服务

该模块为服务间通信暴露以下集成服务：

• IAIChatCompletionIntegrationService：远程执行 AI 聊天完成。
• IWorkspaceConfigurationIntegrationService：为远程设置检索工作区配置。
• IWorkspaceIntegrationService：远程管理工作区。

集成服务以 /integration-api 前缀暴露，并标记有 [IntegrationService] 属性。

应用层

应用服务

• WorkspaceAppService：工作区管理的 CRUD 操作。
• ChatCompletionClientAppService：客户端聊天完成服务。
• AIChatCompletionIntegrationService：用于远程 AI 执行的集成服务。

缓存

工作区配置会被缓存以提高性能。缓存键格式：

WorkspaceConfiguration:{ApplicationName}:{WorkspaceName}

当工作区被创建、更新或删除时，缓存会自动失效。

另请参阅

• 人工智能基础设施：了解底层的 AI 工作区基础设施
• Microsoft.Extensions.AI：微软的统一 AI 抽象
• Semantic Kernel：微软的 Semantic Kernel 集成