XIAOSUO 记录个人学习的足迹

摘要：一、理论基础 1. RAG 概述 RAG：检索增强生成技术，我们先用一个例子来介绍一下什么是检索增强生成。 想象一下，你是一个很聪明的小学生，但你的知识都记在脑子里。如果老师问你一个很难的问题，比如：“恐龙是怎么消失的？”。你可能记得一些，但不完整。 这时候老师说：“来，我们开卷考！你可以去书架上查百科全书，然后再回答。” RAG 就是这样： 你有大脑（AI 的记忆）→ 你本来就知道很多事。 但遇到不知道的问题→ 你先跑去“书库”（数据库、网络等）快速查找相关的资料。 把查到的资料和你原来的知识合在一起，用你自己的话给出一个更好的答案。 所以，RAG 就是：先查资料，再结合自己的知识回答问题。这样就不会瞎编，答案更准确、更新鲜！是不是很像写作业时“先翻书，再总结”呢？ 企业应用使用大模型时，至少会遇到下面2个问题： 大模型一旦训练结束，它就不会在知道结束时间之后发生的事了，也就是它有时效性缺失 另外，通用的大模型是使用公共数据来训练的，它没有企业私有的数据，也就是私有领域空白 为了解决上面2类问题，我们可以使用 RAG 技术，为模型提供一个图书馆，也就是通常说的企业知识库。 2. RAG 工作流程 在让 LLM 回答问题之前，先去外部知识库中检索相关的信息，然后将检索到的信息作为参考资料喂给LLM，让它基于资料生成答案。RAG 分为2个阶段： 索引阶段：后台异步运行的数据处理流程，将文本转换为向量，构建语义索引。 检索与生成阶段：能够在线实时响应用户请求的流程 ETL（提取、转换、加载）流： 加载：格式解析、编码标准化、元数据提取； 分割：LLM的上下文窗口有限，所以需要递归字符分割，分割可能造成语义不完整，所以在分割的2段语句通常会添加重叠窗口； 嵌入：人类语言翻译成机器语言，使用嵌入模型，将文本转换为高维向量，即高维的语义空间，后续可以使用余弦相似度 -1 ~ 1进行检索； 存储：将文本块内容、向量数据、元数据，持久化存储到向量数据库。 3. 嵌入模型选型 我们把文本转换成高维向量时，需要使用嵌入模型，那如何选择嵌入模型呢？ 我们先看一下都有哪些选择： 闭源厂商云端模型 API： 优势：接入成本低、弹性扩展 劣势：数据隐私风险、长期成本不可控、网络延迟 开源模型本地私有化： 优势：绝对的数据安全、零增量成本、高性能与低延迟 劣…… 阅读全文

摘要：上一篇我们已经搭建好了 AI 应用的基础设施，今天我们开始创建企业助理智能体。 一、AI 网关集成 Agent 框架 关于 MAF 部分的内容，可以查看 Agent 智能体 ，我们这里直接上代码。 我们在 Qjy.AICopilot.AiGatewayService 项目添加一个 Agents 文件夹。 1. 创建聊天智能体 由于我们是一个多模型聊天应用，聊天模型数据是从数据库动态加载的。因而我们首先要创建一个工厂类，用来根据数据库中的数据来动态创建 Agent。 public class ChatAgentFactory(IServiceProvider serviceProvider) { public ChatClientAgent CreateAgentAsync(LanguageModel model, ConversationTemplate template) { using var scope = serviceProvider.CreateScope(); var httpClientFactory = scope.ServiceProvider.GetRequiredServiceIHttpClientFactory(); // 创建专属 HttpClient 对象 var httpClient = httpClientFactory.CreateClient(OpenAI); var chatClientBuilder = new OpenAIClient( new ApiKeyCredential(model.ApiKey ?? string.Empty), new OpenAIClientOptions { Endpoint = new Uri(model.BaseUrl), // 接管 OpenAI 的底层传输 Transport = new HttpClientPipelineTransport(httpClien…… 阅读全文

摘要：前面我做了一个使用 LangChain 做的 AI 通用聊天平台的示例，接下来我们回到 .NET 环境，完成一个企业级的 .NET+AI 的项目。目标是为企业通电，完成一个可扩展、可私有化部署的 AI 应用。让企业能用自然语音操作内部其他系统（ERP/CRM/OA）、获取知识、分析报告。 一、项目分析 1. 背景 我们需要完成一个AI企业助理系统，在现有的系统之上，覆盖一层“智能化层”，完成： 智能体和工具调用：赋予 AI 行动能力。 检索增强生成，企业知识中枢：赋予 AI 记忆和知识能力 AI数据分析，一句话生成可视化报表：赋予 AI 分析能力，如 NL2SQL 2. 需求分析 通过背景分析，我们梳理一下大致需要完成的功能： 智能助理（Agent）：AI 交互入口（大脑） 对话与上下文管理：支持多轮上下文 意图识别：准确分析用户的输入，判断命令意图 工具调用：调用通过 MCP 接入的外部插件 富响应生成：响应不能局限于纯文本，包含表格、图表 企业知识中枢（RAG）：处理非结构化知识（记忆） 文档处理流程：支持多种文档格式上传，实现自动解析、自动分块、向量化计算（嵌入）、向量存储 检索与回答：支持语义搜索，结合LLM生成精准、有来源依据的问答 企业级特性：权限控制、数据时效性 数据报表分析（NL2SQL）：处理结构化数据（分析） NL2SQL引擎：自然语言翻译成 SQL 查询 多数据源支持 自动化分析与可视化：自动生成可视化图表，利用LLM总结图表中的趋势 报告导出 MCP 接入管理（Tools）：负责连接外部系统（行动） 服务发现与管理：实现 MCP 服务的注册，注册到AI的能力库 调试与权限：确保操作安全 3. 技术选型 后端框架：ASP.NET Core（.NET 10） AI 框架：Semantic Kernerl（SK）、Agent Framework 知识库：向量数据库（Qdrant）+关系型数据库（PostgreSQL + pgvector） 大模型：兼容 OpenAI 接口、支持私有化部署 安全方案：Jwt + RABC 开发方式：云原生开发 .NET Aspire 部署方案：容器化部署 4. 开发流程 搭建环境与项目骨架 实现核心服务（认证 + AI 网关） 构建知识中枢（RAG …… 阅读全文

摘要：一、自定义工作流事件 1. 为什么需要自定义事件？ 场景 内置事件 自定义事件 粒度 Executor 级别 业务逻辑级别 语义 系统通用 (调用、完成) 业务特定 (审核通过、风险预警) 数据 执行元数据 业务数据 (敏感词、风险分数) 监控 技术监控 业务监控 + 审计 前端 通用进度条 具体业务状态展示 2. 自定义事件类定义 基本定义模式：自定义事件本质上就是继承 WorkflowEvent 的普通 C# 类。让我们从最简单的开始： /// summary /// 表示检测到敏感词的事件 /// /summary public class SensitiveWordDetectedEvent : WorkflowEvent { public SensitiveWordDetectedEvent(string word, int position) : base(data: null) // 可以传递简单数据到 base { Word = word; Position = position; } public string Word { get; } public int Position { get; } } 设计原则 DO (推荐做法)： 类名以 Event 结尾，语义清晰 使用只读属性 ({ get; })，确保事件不可变 添加 XML 注释说明事件的业务含义 属性类型尽量简单（string, int, DateTime 等可序列化类型） DON'T (避免做法)： 不要在事件类中包含方法逻辑 不要引用不可序列化的对象（如 DbContext, HttpClient） 不要使用可变属性（{ get; set; }） 不要在构造函数中执行耗时操作 3. 携带复杂数据的事件 当需要传递更复杂的业务数据时，有两种设计模式： 模式 1: 使用属性传递结构化数据 /// summary /// 风险评估完成事件 /// /summary public class RiskAssessmentCompletedEvent : WorkflowEvent { public RiskAssessmentCom…… 阅读全文

摘要：一、工作流核心概念 1. Executor（执行器） Executor（执行器） 是 Workflow 中的最小工作单元，类似于： 类比 说明 工厂里的工人 每个工人负责一道工序 乐高积木块 每个积木有特定功能，组合成整体 电路中的元件 接收输入信号，输出处理结果 flowchart LR Input[输入消息] --> Executor[Executor\n执行器] Executor --> Output[输出消息] style Executor fill:#4CAF50,color:white Executor 的核心特征 唯一标识（Id）：每个 Executor 有一个唯一的 ID，用于在 Workflow 中引用 消息处理：接收特定类型的输入消息，处理后产生输出消息 路由配置：通过 ConfigureRoutes 方法定义能处理哪些类型的消息 状态感知：可以通过 IWorkflowContext 访问和修改工作流状态 Executor 的类型层次：MAF 提供了多种 Executor 类型，满足不同场景需求 classDiagram class Executor { +string Id +ExecuteAsync() #ConfigureRoutes() } class Executor~TInput~ { +HandleAsync(TInput) } class Executor~TInput,TOutput~ { +HandleAsync(TInput) TOutput } class FunctionExecutor~TInput~ { +委托函数处理 } class FunctionExecutor~TInput,TOutput~ { +委托函数处理 } class StatefulExecutor~TState~ { +TState State +ReadStateAsync() …… 阅读全文

摘要：一、自定义 Agent 的实现 1. 场景分析 在大多数场景下，使用 chatClient.CreateAIAgent() 创建的标准 Agent 已经足够强大。但在某些特殊场景下，自定义 Agent 实现能带来更大的价值： 场景 1：规则引擎替代 AI（成本优化） 问题：客服系统每天处理数万次重复性问题(营业时间？，退货流程？)，每次调用 AI 模型都会产生成本。 解决方案：自定义 Agent 使用 FAQ 知识库进行关键词匹配，只在无法匹配时才调用 AI。 收益： 成本降低 70-90%（高频简单问题零成本） 响应速度提升 10 倍（无需等待 AI 推理） 答案一致性更高（预定义标准答案） 场景 2：遗留系统集成（ERP/CRM/工作流引擎） 问题：企业内部有成熟的审批工作流引擎，需要将其包装为 Agent 供统一调度。 解决方案：自定义 Agent 作为适配器，将工作流引擎的 API 转换为 Agent 接口。 收益： 无缝集成现有系统（无需重构） 复用企业级规则引擎（审批、权限、流程） 数据安全可控（不发送敏感数据到外部 AI） 场景 3：测试模拟（Mock Agent） 问题：开发和测试环境中，不希望调用真实 AI 模型（成本、稳定性、可预测性）。 解决方案：自定义 Agent 返回固定或可配置的测试数据。 收益： 单元测试更可靠（确定性输出） 开发环境零成本 CI/CD 管道更快（无需等待 AI 响应） 场景 4：混合模式（规则 + AI） 问题：希望结合规则引擎的确定性和 AI 的灵活性。 解决方案：自定义 Agent 先尝试规则匹配，失败后转发给 AI Agent。 收益： 平衡成本与效果 灵活的分流策略（按优先级、置信度） 逐步优化规则库（分析 AI 处理的高频问题） 对比: 标准 Agent vs 自定义 Agent 特性 ChatClientAgent(标准) 自定义 Agent 说明 创建方式 chatClient.CreateAIAgent() 继承 AIAgent 抽象类 标准方式更简单 开发复杂度 低 高 自定义需实现所有核心方法 灵活性 受限于 IChatClient 能力 完全可控 自定义可实现任意逻辑 成本 按 Token 计费…… 阅读全文

摘要：一、自定义文件消息存储 1. ChatMessageStore 架构概览 classDiagram class ChatMessageStore { abstract>> #IChatReducer? ChatReducer +AddMessagesAsync(messages) +GetMessagesAsync() +ClearAsync() +Serialize() +Deserialize(state) } class InMemoryChatMessageStore { -List~ChatMessage~ _messages +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } class FileChatMessageStore { -string _filePath -SemaphoreSlim _lock +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } class RedisChatMessageStore { -IConnectionMultiplexer _redis +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } ChatMessageStore |-- InMemoryChatMessageStore ChatMessageStore |-- FileChatMessageStore ChatMessageStore |-- RedisChatMessageStore ChatMessageStore 抽象类核心方法职责 方法 职责 使用场景 AddMessagesAsync 添加新消…… 阅读全文

摘要：一、第一个智能体 1. 什么是 MAF Microsoft Agent Framework (MAF) 是微软推出的企业级 AI Agent 开发框架，构建在 Microsoft.Extensions.AI (MEAI) 之上，提供了构建生产级 AI Agent 所需的完整能力。 Agent vs ChatClient - 什么时候用 Agent? 特性 IChatClient AIAgent 定位 底层 AI 调用抽象 高级智能体封装 状态管理 无状态，每次调用独立 内置对话线程 (AgentThread) 身份定义 需要手动在每次调用中传入 System Message 固定的 Instructions 和 Name 工具管理 需要手动配置 ChatOptions.Tools Agent 级别统一管理工具 使用场景 构建自定义 AI 功能，单次对话场景 企业级对话系统，多轮交互场景 简单来说: ChatClient 就像一个纯函数：给定输入，返回输出，不保留状态 Agent 就像一个有记忆的助手： 有固定身份、能记住上下文、能使用工具 2. MAF 的核心概念 MAF 围绕以下核心概念构建: AIAgent - 智能代理：Agent 是具有特定身份和能力的智能实体，包含： Name (名称)：Agent 的唯一标识 Instructions (指令)：Agent 的系统提示词，定义其行为和角色 Tools (工具)：Agent 可以调用的函数工具集合 AgentThread - 对话线程：每个 Agent 可以有多个对话线程，每个线程维护独立的对话历史： 自动管理消息历史 支持序列化/反序列化 (持久化) 线程隔离，互不干扰 AgentRun - 执行实例：每次调用 Agent 都会创建一个 Run： 同步调用：RunAsync() → 返回完整响应 流式调用：RunStreamingAsync() → 返回增量更新流 3. 快速开始 让我们通过创建一个口语教练 Agent 来快速入门 MAF。 // 步骤 1: 获取底层获取 ChatClient var chatClient = ChatClientFactory.GetQwenClient(); // 步骤 2: 创建口语教…… 阅读全文

摘要：一、自定义传输协议 我们已经知道 MCP 的 Stdio 和 HTTP 传输协议了，今天我们深入探索一下 InMemory Transport（进程内传输）的实现原理，以及如何创建自定义传输协议。InMemory Transport 特别适合单进程内的 MCP 通信、单元测试和高性能场景。 1. InMemory Transport 原理 InMemory Transport 是一种在单进程内实现 MCP Client 和 Server 通信的传输方式。它使用内存中的数据结构（如 Pipe、Channel）进行消息传递，避免了跨进程通信的开销。 主要优势： 高性能：无需序列化到文件或网络，直接在内存中传递消息 易于测试：非常适合编写单元测试，不依赖外部进程或网络 同步控制：Client 和 Server 在同一进程，便于调试和状态管理 零依赖：不需要启动外部进程或监听端口 实现原理：InMemory Transport 基于 Pipe（管道）实现双向通信： 创建两个 Pipe： clientToServerPipe：Client → Server 方向 serverToClientPipe：Server → Client 方向 连接读写端： Client 写入 clientToServerPipe.Writer，Server 读取 clientToServerPipe.Reader Server 写入 serverToClientPipe.Writer，Client 读取 serverToClientPipe.Reader 消息序列化： 使用 JSON-RPC 格式序列化消息 每条消息以换行符 \n 分隔 sequenceDiagram participant C as McpClient participant CTP as clientToServerPipe participant STP as serverToClientPipe participant S as McpServer Note over C,S: 初始化连接 C->>CTP: Write (Request) CTP->>S: Read (Request) S->>STP: Wr…… 阅读全文

摘要：一、MCP 协议基础 1. 协议概述 MCP 是一个基于 JSON-RPC 2.0 的应用层协议，专为 AI 应用程序设计。它定义了： 标准化消息格式：统一的请求/响应/通知结构 能力协商机制：Client 和 Server 协商支持的功能 双向通信：支持请求-响应和异步通知 错误处理：标准化的错误代码和异常处理 MCP 协议栈 MCP 协议建立在 JSON-RPC 2.0 之上，提供了额外的语义和约定： ┌─────────────────────────────────────────┐ │ AI Application Layer │ ← 使用 MCP 的应用 ├─────────────────────────────────────────┤ │ MCP Protocol Layer (Application) │ ← MCP 协议语义 │ (Tools, Resources, Prompts, etc.) │ ├─────────────────────────────────────────┤ │ JSON-RPC 2.0 Layer │ ← 基础 RPC 协议 ├─────────────────────────────────────────┤ │ Transport Layer (Stdio/HTTP) │ ← 传输机制 └─────────────────────────────────────────┘ 核心设计原则 原则 说明 示例 标准化 统一的协议格式 所有工具调用使用 tools/call 方法 协商式 能力协商机制 Client 和 Server 协商支持的功能 双向通信 支持请求和通知 Server 可以主动发送日志通知 类型安全 JSON Schema 验证 参数和返回值都有明确的类型定义 可扩展 支持自定义扩展 可以添加自定义 Capabilities MCP vs 其他协议 协议 用途 MCP 的优势 REST API 通用 Web 服务 MCP 专为 AI 上下文设计，支持工具发现和类型安全 gRPC 高性能 RPC MCP …… 阅读全文