UniGenAI 1.0.3

UniGenAI

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

架构概览

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. 引用依赖

在 ASP.NET Core Web 项目中添加项目引用：

dotnet add reference path/to/UniGenAI.Rag.AspNetCore/UniGenAI.Rag.AspNetCore.csproj

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' }
    }
}, '*');

文档索引

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

• 文档中心首页：全局导航与结构指南
• 10 分钟快速上手教程：从零构建第一个生成式 AI 知识库服务
• 企业级混合 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