UniGenAI 1.0.4

UniGenAI

UniGenAI 是专为 .NET 生态打造的高性能、跨平台生成式 AI 与企业级知识库（RAG）推理引擎。它将现代生成式 AI 技术与工业制造场景深度融合，不仅封装了底层的本地高性能推理框架（ONNX Runtime GenAI、Google LiteRT-LM、RT-DETR 计算机视觉），还提供了一体化的企业级混合检索 RAG、Microsoft Semantic Kernel 原生智能体、双向 Model Context Protocol (MCP) 接口及可嵌入的响应式 Web 浮窗助理。

📦 NuGet 包与模块依赖选型

UniGenAI 采用清晰的分层解耦多包架构，已在 NuGet.org 正式发布 1.0.3 版本。您可以根据具体业务需求按需引入最小依赖，避免不必要的体积与依赖膨胀。

1. NuGet 发布包概览

2. 模块依赖选型矩阵 (按需安装推荐)

各个功能模块所需要的依赖库不同，推荐按需安装最佳包，无需一股脑全部引入：

3. 多种安装方式

UniGenAI 支持所有主流的 .NET 包管理工具，优先推荐通过 NuGet 方式引入：

方式 A：.NET CLI（推荐，命令行极速安装）

# 1. 完整 Web RAG 助理与悬浮窗（推荐，一键装载全链路）
dotnet add package UniGenAI.Rag.AspNetCore --version 1.0.3

# 2. 纯核心引擎（OCR、RT-DETR、本地大模型、视觉推理）
dotnet add package UniGenAI --version 1.0.3

# 3. 独立 RAG 业务核心（控制台 / 后台 Worker / 无 Web UI）
dotnet add package UniGenAI.Rag --version 1.0.3

# 4. 仅轻量抽象契约（DDD 领域层 / 接口定义）
dotnet add package UniGenAI.Abstractions --version 1.0.3

# 5. 独立端侧 LiteRT 原生动态库资产
dotnet add package UniGenAI.LiteRT.Native --version 1.0.3

方式 B：Package Manager Console (PMC / Visual Studio)

# 完整 Web RAG 助理与悬浮窗
NuGet\Install-Package UniGenAI.Rag.AspNetCore -Version 1.0.3

# 核心推理引擎（OCR / RT-DETR / LLM）
NuGet\Install-Package UniGenAI -Version 1.0.3

# 独立 RAG 业务核心
NuGet\Install-Package UniGenAI.Rag -Version 1.0.3

# 轻量抽象契约
NuGet\Install-Package UniGenAI.Abstractions -Version 1.0.3

# LiteRT 原生动态库资产
NuGet\Install-Package UniGenAI.LiteRT.Native -Version 1.0.3

方式 C：PackageReference（直接编辑 .csproj 文件）

<ItemGroup>
  
  <PackageReference Include="UniGenAI.Rag.AspNetCore" Version="1.0.3" />

  
  <PackageReference Include="UniGenAI" Version="1.0.3" />

  
  <PackageReference Include="UniGenAI.Abstractions" Version="1.0.3" />
</ItemGroup>

方式 D：Paket CLI

paket add UniGenAI.Rag.AspNetCore --version 1.0.3
paket add UniGenAI --version 1.0.3
paket add UniGenAI.Abstractions --version 1.0.3

4. 依赖传递拓扑

graph TD
    ConsumerApp[您的应用程序]
    
    subgraph Packages [UniGenAI NuGet 体系]
        Abs[UniGenAI.Abstractions 1.0.3<br/>纯抽象契约 / 零原生依赖]
        Native[UniGenAI.LiteRT.Native 1.0.3<br/>跨平台 C++ 原生库资产 win/linux/osx]
        Core[UniGenAI 1.0.3<br/>OCR / RT-DETR / LLM / Vision]
        Rag[UniGenAI.Rag 1.0.3<br/>FTS5 + Vector + RRF + Reranker + SK]
        Web[UniGenAI.Rag.AspNetCore 1.0.3<br/>Web API + SSE + React UI + 浮窗]
    end

    Web -->|传递依赖| Rag
    Rag -->|传递依赖| Core
    Core -->|传递依赖| Native
    
    ConsumerApp -.->|开发 Web 智能助理| Web
    ConsumerApp -.->|仅使用 OCR / 目标检测| Core
    ConsumerApp -.->|类库定义契约| Abs

架构概览

graph TD
    User([终端用户 / 工业现场操作员]) --> WebUI[嵌入式浮窗 / Web 管理前台]
    HostApp[外部宿主系统 MES / ERP / WDS] -- postMessage 双向感知 --> WebUI
    ExternalAI[外部 AI: Claude / Cursor] -- MCP JSON-RPC --> McpServer[UniGenAI MCP Server]

    subgraph UniGenAI.Rag.AspNetCore [ASP.NET Core 服务层]
        WebUI --> ChatController[SSE 流式对话控制器]
        ChatController --> KbService[知识库服务 IKnowledgeBaseService]
        McpServer --> KbService
    end

    subgraph AgentExecution [Agent 智能体执行层]
        KbService --> Router{运行模式判定}
        Router -- API 模式 --> SKRunner[Microsoft Semantic Kernel Runner]
        Router -- 本地离线模式 --> LegacyLoop[自研 ToolAgentLoop 降级]
        SKRunner --> Plugins[SK Plugins: RAG / WebSearch / MCP Bridge]
    end

    subgraph HybridRAG [企业级混合检索流水线]
        KbService --> Rewriter[Query 语义重写与扩展]
        Rewriter --> FTS5[SQLite FTS5 BM25 全文检索]
        Rewriter --> Vector[SIMD 余弦向量检索]
        FTS5 --> RRF[倒数排名融合 RRF]
        Vector --> RRF
        RRF --> Reranker[ONNX Cross-Encoder 语义精排]
    end

    subgraph CoreEngines [核心推理引擎 UniGenAI]
        Plugins --> InferenceEngines
        LegacyLoop --> InferenceEngines
        subgraph InferenceEngines [统一推理引擎]
            ApiLlm[ApiLlmEngine: OpenAI 兼容端点]
            OnnxGenAi[LlmEngine: ONNX Runtime GenAI]
            LiteRt[LiteRtEngine: Google LiteRT-LM C++]
            Vision[VisionEngine / OcrEngine: VLM & GGUF mmproj]
            RtDetr[RtDetrDetector: 实时目标检测 Transformer]
        end
    end

核心特性

1. 企业级混合 RAG 检索流水线

• 双路并行召回：针对工业设备编码（如 PM5-DRYER-01、SAP MM03）容易在纯向量中失真的问题，内建 SQLite FTS5 BM25 关键词倒排与 SIMD 向量余弦检索 双路召回。
• 倒数排名融合 (RRF)：自适应将稀疏与稠密评分无量纲融合（$k=60.0$）。
• Cross-Encoder 语义精排：支持载入 ONNX bge-reranker 权重进行全局交叉注意力精排，未加载模型时自动直通降级。
• Markdown AST 章节语义切分：识别标题栈（#, ##, ###）切分，自动在切片首部注入语义面包屑（如 [PM5操作规范 > 干燥部 > 紧急停机]）。

2. Microsoft Semantic Kernel 原生智能体

• 原生 Function Calling：集成 Microsoft.SemanticKernel 1.80.1，通过 AutoInvokeKernelFunctions 与 JSON Schema 强类型约束驱动工具循环，告别正则脆弱解析。
• 标准 Plugin 封装：内建 RagKnowledgePlugin、WebSearchPlugin，支持自动多步检索与外部互联网补充。
• 动态工具桥接：提供 SemanticKernelPluginHelper，将外部 MCP 工具及宿主系统注册能力无损转为 SK 插件。
• 双轨自适应降级：云端 API 模式优先走 Semantic Kernel；断网离线工控机自动降级至轻量自研 ToolAgentLoop。

3. 双向 Model Context Protocol (MCP)

• 作为 MCP Server：对外暴露 POST /api/rag/mcp 端点，将系统内生产的 SOP 规程、文章与更新日志暴露为 MCP Resources，并将混合检索暴露为 MCP Tools。
• 作为 MCP Client：支持连接外部 Stdio/HTTP 格式的 MCP Server（如 PostgreSQL、OPC UA 工业网关）。

4. 宿主系统感知式悬浮窗 (Floating Chat Widget)

• 开箱即用 Web 组件：内置基于 React + TypeScript + Tailwind 的现代化管理后台与嵌入式悬浮抽屉。
• 跨窗口双向上下文感知：支持通过 iframe 嵌入任意系统，利用 postMessage 实时监听宿主活跃模块、工单与高选告警文本，生成交互式上下文药丸胶囊（Pill）。
• 思维链动效：支持三阶段流式状态展示（🔍 正在检索知识库 ➔ 🎯 正在重排序候选切片 ➔ 💡 正在组织回答）与快捷追问选项（Follow-up Chips）。

5. 全场景多模态与端侧推理

• API 与 Local 二选一热切换：支持标准 OpenAI 格式端点（DeepSeek、GPT、Qwen、Ollama、vLLM）与本地离线推理无缝切换。
• Google LiteRT-LM：基于 C++ 动态库 P/Invoke 驱动端侧轻量大模型。
• OCR 与 RT-DETR 视觉：支持 ONNX / GGUF-mmproj 双模文字识别与工业级实时目标检测 Transformer。

快速入门

1. 引入 NuGet 依赖

在 ASP.NET Core Web 项目中添加推荐的 NuGet 旗舰包：

dotnet add package UniGenAI.Rag.AspNetCore --version 1.0.3

2. 配置与启动

在 Program.cs 中添加服务：

using UniGenAI.Rag.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

// 注册 UniGenAI RAG 核心服务（自动装载 FTS5、Semantic Kernel 与 MCP）
builder.Services.AddRagServices(options =>
{
    options.StoragePath = "Data/KnowledgeBase.db";
    options.TopK = 5;
    options.EnableSemanticKernel = true;
});

var app = builder.Build();
app.UseRouting();

// 启用内置的管理后台与嵌入式悬浮窗中间件 (访问路径: /rag)
app.UseRagUI(options =>
{
    options.RoutePrefix = "rag";
    options.DocumentTitle = "UniGenAI 工业智能助理";
});

app.MapControllers();
app.Run();

代码示例

1. 使用 Semantic Kernel 执行多轮智能体对话

using UniGenAI.Entities.Data;
using UniGenAI.Rag.Core;
using UniGenAI.Rag.Core.Plugins;
using Microsoft.SemanticKernel;

var config = new GenAIConfig
{
    ModelType = "api",
    ApiEndpoint = "https://api.deepseek.com/v1",
    ApiKey = "sk-...",
    ApiModelName = "deepseek-chat"
};

var runner = new SemanticKernelAgentRunner();
var plugin = KernelPluginFactory.CreateFromType<RagKnowledgePlugin>(serviceProvider);

var history = new List<ChatMessage>
{
    new ChatMessage { Role = "user", Content = "查询 PM5-DRYER-01 的轴承维保规程" }
};

// 自动触发原生 Function Calling，调用混合检索并生成高置信度回答
string response = await runner.RunAgentTurnAsync(
    config: config,
    history: history,
    systemPrompt: "你是一名专业的工业技术专家助手。",
    plugins: new[] { plugin }
);

Console.WriteLine(response);

2. 宿主系统向嵌入式悬浮窗注入上下文

在外部 MES / ERP Web 系统的前端页面中：

// 获取悬浮窗 iframe 实例
const chatFrame = document.getElementById('unigenai-chat-iframe').contentWindow;

// 用户选中告警代码或切换设备时，主动下发上下文
chatFrame.postMessage({
    type: 'unigenai-host',
    action: 'set-context',
    payload: {
        module: '干部烘缸工段',
        selectedText: '告警 E-3012: 3号烘缸传动侧轴承温升超限',
        metadata: { machineId: 'PM5-DRYER-03' }
    }
}, '*');

3. 本地 OCR 文字识别（仅需安装 UniGenAI 包）

using UniGenAI.Core;
using UniGenAI.Entities.Data;

// 1. 配置 OCR 引擎参数（只需指向包含 det/rec/keys 的模型目录，或自动按需匹配）
var config = new OcrEngineConfig
{
    ModelPath = @"/data/models/PP-OCRv4",
    Device = DeviceType.Cpu,
    AllowCpuFallback = true
};

// 2. 初始化引擎并识别（支持文件路径、Stream 或 byte[] 图片）
using var ocrEngine = new PpOcrEngine(config);
var ocrResult = await ocrEngine.RecognizeAsync("invoice.png");

Console.WriteLine($"全文文本:\n{ocrResult.FullText}");
foreach (var line in ocrResult.Lines)
{
    Console.WriteLine($"[{line.Score:P0}] {line.Text}");
}

文档索引

本项目提供遵循 Diátaxis 框架的完备技术文档与说明文件：

• 文档中心首页：全局导航与结构指南
• 10 分钟快速上手教程：从零构建第一个生成式 AI 知识库服务
• NuGet 多包拆分与安装指南：五大包边界职责、依赖传递关系与多格式安装指令
• 企业级混合 RAG 配置指南：FTS5、向量检索、RRF 融合与 Reranker 详细配置
• Semantic Kernel 接入指南：原生 Function Calling 与动态 MCP 工具链
• MCP 双向通信指南：服务端暴露与客户端挂载
• 悬浮窗宿主嵌入指南：iframe 集成与 postMessage 双向通信
• RAG 权限认证与安全实战：宿主鉴权回调、ASP.NET Core 策略、Basic Auth 与跨域安全
• 本地与端侧模型调用案例：ONNX GenAI、Google LiteRT-LM、RT-DETR 目标检测与多模态 OCR
• 完整配置参数全集 (Configuration)：GenAIConfig、RagOptions、Vision 与 OCR 全量字典
• LLM 导航入口 (llms.txt)：面向大语言模型的标准化项目结构索引

验证与测试

本项目拥有完善的单元测试与端到端自动化测试覆盖。

# 编译整个解决方案
dotnet build UniGenAI.sln

# 运行全量单元测试（包含 FTS5、RRF、Reranker、Semantic Kernel Function Calling 等 49 项测试）
dotnet test UniGenAI.Tests/UniGenAI.Tests.csproj