XIAOSUO 记录个人学习的足迹

摘要：一、第一个智能体 1. 什么是 MAF Microsoft Agent Framework (MAF) 是微软推出的企业级 AI Agent 开发框架，构建在 Microsoft.Extensions.AI (MEAI) 之上，提供了构建生产级 AI Agent 所需的完整能力。 flowchart TB subgraph "应用层" A[你的应用] end subgraph "Agent 框架层" B[Microsoft Agent Framework] end subgraph "AI 抽象层" C[Microsoft.Extensions.AIbr/>IChatClient] end subgraph "AI 服务层" D1[Azure OpenAI] D2[OpenAI] D3[DeepSeek] D4[其他模型] end A --> B B --> C C --> D1 C --> D2 C --> D3 C --> D4 style B fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#fff style C fill:#2196F3,stroke:#1565C0,stroke-width:2px,color:#fff Agent vs ChatClient - 什么时候用 Agent? 特性 IChatClient AIAgent 定位 底层 AI 调用抽象 高级智能体封装 状态管理 无状态，每次调用独立 内置对话线程 (AgentThread) 身份定义 需要手动在每次调用中传入 System Message 固定的 Instructions 和 Name 工具管理 需要手动配置 ChatOptions.Tools Agent 级别统一管理工具 使用场景 构建自定义 AI 功能，单次对话场景 企业级对话系统，多轮交互场景 简单来说: ChatClient 就像一个纯函数…… 阅读全文

摘要：一、自定义传输协议 我们已经知道 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 …… 阅读全文

摘要：一、函数调用进阶 1. FunctionInvokingChatClient 深入解析 FunctionInvokingChatClient 是 MEAI 中负责函数调用的核心中间件。当我们调用 UseFunctionInvocation() 时，实际上是在管道中插入了这个强大的中间件，它会自动处理模型的函数调用请求。 工作原理与执行流程 FunctionInvokingChatClient 作为装饰器包装底层的 IChatClient，拦截对话请求并自动处理函数调用循环： 发送初始请求：将用户消息和可用工具传递给模型 检测函数调用：模型返回时，检查响应中是否包含 FunctionCallContent 执行函数：自动调用被请求的函数，获取执行结果 回传结果：将函数结果作为 FunctionResultContent 添加到对话历史 继续迭代：再次调用模型，让它基于函数结果生成最终回答 返回响应：直到模型不再请求函数调用，返回最终答案 这个循环过程完全自动化，开发者无需手动管理函数调用状态。 用户消息 → 模型(发现需要调用函数) → 执行函数 → 模型(基于结果) → 最终答案 ↑_______________________________________________| (自动迭代，最多 MaximumIterationsPerRequest 次) 核心配置选项 通过 UseFunctionInvocation(configure: options = ) 可以访问 FunctionInvokingChatClient 的配置选项。以下是各属性的详细说明： AdditionalTools（全局工具集） 用途：提供额外的工具供函数调用时查找，但不会发送给模型 重要限制：模型不知道这些工具的存在，除非服务端已预先配置 工作机制：当模型请求调用某个工具时，先查找 ChatOptions.Tools，如果找不到再查找 AdditionalTools 适用场景： 服务端预配置的工具（如 Azure OpenAI 的 Assistants API） 作为回退工具集 与 ChatOptions.Tools 的关系：ChatOptions.Tools 优先级更高，同名工具会覆盖 AdditionalTools 中的…… 阅读全文

摘要：一、M.E.AI概述 1. 引言 Microsoft.Extensions.AI (MEAI) 定位于.NET 生态系统的 AI 功能基础抽象层，提供如 IChatClient 和 IEmbeddingGenerator 等核心接口，旨在统一和简化.NET 应用与各类 AI 服务的集成方式 。 Microsoft.Extensions.AI (MEAI) 是一系列旨在为.NET 开发者提供与各种人工智能服务进行集成和交互的统一方法的库 。它的核心目标是提供一组通用的抽象，从而简化.NET 应用程序中生成式 AI 组件的表示，并实现与不同 AI 服务的无缝集成和互操作性。 MEAI 的核心功能主要围绕两个关键接口展开：ChatClient 和 IEmbeddingGeneratorTInput, TEmbedding。 2. MEAI 的核心功能和优势 IChatClient：用于与聊天型 AI 服务交互的客户端接口，支持多模态消息传递和流式响应。 IEmbeddingGeneratorTInput, TEmbedding：用于生成向量嵌入的通用接口，支持多种输入类型。 依赖注入 (DI) 和中间件支持：利用.NET 的成熟 DI 和中间件模式，简化组件集成。 这使得开发者可以轻松地将自动函数工具调用、遥测和缓存等功能集成到应用程序中。 服务无关性：MEAI 的设计目标是实现与特定 AI 服务的解耦，使得开发者可以在不同的 AI 提供商之间轻松切换，而无需修改应用代码。 这不仅提高了代码的可移植性，还简化了测试和模拟过程。 多模态支持：IChatClient 接口支持文本、图像和音频等多种消息类型，满足现代 AI 应用的需求。 流式响应：IChatClient 支持流式响应，允许应用程序逐步处理来自 AI 服务的输出，提升用户体验。 扩展性：MEAI 的设计允许开发者为不同的 AI 服务实现自定义的客户端和嵌入生成器，促进生态系统的多样化和创新。 与 Semantic Kernel 的集成：MEAI 提供了与 Semantic Kernel 的无缝集成，允许开发者利用 SK 的高级功能，同时享受 MEAI 提供的统一接口和抽象。 与 Microsoft Agent Framework 的集成：MEAI 还与 Microsoft Agent Framework …… 阅读全文

摘要：一、Magentic-One系统解析 1. Magentic-One定位与价值 预构建专家系统：Magentic-One是一个基于AutoGen框架构建的预构建通用任务解决专家系统，具备处理复杂任务的能力。 双重价值：Magentic-One既可以作为强大的工具直接使用，也是学习复杂多智能体设计的最佳实践蓝图，为开发者提供设计参考。 2. 编排者双循环机制 内循环执行与反思：编排者的内循环围绕进度分类账进行任务执行与即时反思，快速迭代以确保任务按计划推进。 外循环规划调整：当内循环陷入停滞时，编排者启动外循环，重新审视任务分类账，调整宏观计划以应对复杂情况。 自适应能力：双循环机制赋予Magentic-One强大的自适应能力，使其能够灵活应对复杂多变的任务环境。 3. 专家角色能力矩阵 WebSurfer：负责网页浏览与交互，能够控制浏览器状态，执行网页导航、交互和内容阅读等操作。 FileSurfer：专注于本地文件系统操作，支持读取多种文件格式、浏览目录结构和文件管理。 Coder：擅长代码编写和数据分析，根据任务需求生成Python脚本等代码，完成数据处理和信息整合。 ComputerTerminal：为Coder提供安全的代码执行环境，确保代码安全运行并处理依赖库安装等。 4. 环境安装与安全守则 安装准备：运行Magentic-One前需安装autogen-ext[magentic-one]、Playwright及Chromium等依赖，确保环境完备。 安全运行建议：建议在Docker容器中运行Magentic-One，以隔离环境风险，保护系统安全。 人工审批机制：引入人工审批机制，对代码执行等关键操作进行审核，防止潜在风险。 pip install autogen-ext[magentic-one] # 时间比较长，耐心等待 playwrithr install --with-deps chromium # PowerShell 下运行 # https://chocolatey.org/install Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Ne…… 阅读全文

摘要：一、框架概览 1. 框架概览 框架背景：AutoGen是由微软推出的开源框架，专为构建基于大型语言模型的复杂应用而设计。它改变了传统AI应用开发的方式，不再依赖单一的‘超级英雄’式智能体，而是通过多个智能体的协作来解决复杂任务。 核心思想：其核心思想是通过智能体间的对话与协作来动态驱动任务的解决。这种模式将任务分解为多个子任务，并分配给不同的智能体，每个智能体专注于特定的角色和任务，从而实现高效的协作。 架构优势：AutoGen框架的出现是对早期单一、巨型智能体设计局限性的一种回应。它通过任务分解和角色专业化，优化了问题解决的效率，提升了系统的灵活性和可扩展性。 2. 与LangChain和SK对比 LangChain与Semantic Kernel：LangChain通过模块化和组件化编排任务逻辑，形成‘链’或‘图’；Semantic Kernel则侧重于将大型语言模型的能力集成到企业级应用中，通过‘内核’与‘插件’动态编排执行计划。 AutoGen的独特性：AutoGen的核心抽象是‘对话’，通过智能体间的协作与对话隐式地驱动任务解决。开发者的工作重心从编排任务逻辑转向设计智能体团队，这种方式更加灵活，能够适应复杂的任务需求。 3. 设计理念深度解析 以对话为中心：AutoGen的设计理念是‘以多智能体对话为中心’，对话不仅是信息交换的形式，更是整个应用框架的计算核心。通过对话结构，开发者可以管理复杂的控制流，包括条件逻辑、循环和错误处理。 动态执行图：对话被抽象为动态的执行图，开发者可以通过设计智能体的角色、目标和沟通规则来间接引导应用程序的行为，这种方式更灵活、更具适应性。 决策与推理的转移：这种设计理念将应用程序的决策和推理部分从代码转移到对话本身，充分发挥了大型语言模型的自然语言理解和生成能力。 灵活性与适应性：开发者通过设计智能体的角色和沟通规则来引导应用程序的行为，这种方式不仅灵活，还能更好地适应不同的任务需求，契合了大型语言模型的特性。 4. 分层架构设计 核心API 功能：核心API是AutoGen框架的基石，提供最基础、最通用的构建模块，关注底层消息传递机制、智能体的生命周期管理以及对本地与分布式运行时的支持。 使用场景：当开发者需要构建全新的智能体交互模式或将其集成到已有的事件驱动系统中时，核心API提供了必要的灵活性和控…… 阅读全文

摘要：一、RAG核心机制与组件 1. SK RAG架构与抽象层 抽象层转变 Semantic Kernel为RAG应用提供了现代化、企业级的抽象层，从单一组件向精细、解耦、类型安全的抽象转变。这种转变使得系统更加健壮、可维护，分离了数据存储、嵌入生成和信息检索的关注点，提升了模块化和可测试性。 数据模型映射 通过定义C#类和添加特性，可以将数据模型映射到向量数据库的模式。例如，使用VectorStoreKey、VectorStoreData等特性，能够简化与数据库的交互，避免编写复杂的数据库迁移代码，提高代码的可维护性和可扩展性。 技术选型灵活性 这种架构设计增强了技术选型的灵活性，允许开发者根据项目需求选择合适的数据库和嵌入模型，同时保持系统的稳定性和可扩展性。 2. RAG完整生命周期 生命周期阶段 RAG应用的核心生命周期包括数据加载与预处理、文本分块、嵌入、索引、检索和增强生成六个阶段。每个阶段都有明确的作用和输入输出，例如数据加载阶段负责读取数据，嵌入阶段将文本转换为向量。 标准性与通用性 与LangChain课程中提到的生命周期相比，SemanticKernel的RAG生命周期更加标准化和通用化，适用于多种数据类型和应用场景，为开发者提供了一套清晰的开发流程。 二、文本预处理与分块 文本分块的重要性 文本分块是RAG流程中的关键步骤，能够将长文本分割成适合嵌入和检索的小块，从而提高检索的准确性和效率。 自定义Token计算器 默认的Token计算器在处理中文分词时存在局限性，通过自定义Token计算器可以解决这一问题，确保分块的准确性。 TextChunker静态类 Semantic Kernel提供了TextChunker静态类，包含按行分割和段落组合等核心方法。通过设置最大Token数量和重叠Token参数，可以灵活地控制分块的粒度。 封装不稳定依赖 为了隔离变更风险，可以创建稳定的ITextSplitter接口和SemanticKernelTextSplitter包装类，封装不稳定的依赖，提高代码的稳定性和可维护性。 public interface ITextSplitter { Liststring Split(string text, int maxTokensPerChunk, int overlapTokens)…… 阅读全文

摘要：一、流程框架设计理念 探索性AI与企业级应用差异：探索性AI高度自主，适合创意生成；企业级应用需确定性、可重复性、可审计性。 流程框架关键转变：从“让AI决定做什么”转变为“让AI高效执行预定义流程”，开发者通过声明式语法控制业务流程。 应用场景与优势：插件数量多时，单纯依靠大语言模型编排函数调用不可靠，流程框架可解决此挑战。 架构基础：事件驱动架构 优势 高度解耦与模块化：每个步骤独立开发、测试和替换，提升系统可维护性。 异步与并发：步骤发布事件后无需等待响应，实现高性能并行处理。 灵活性与可扩展性：修改事件路由规则或增加新步骤即可适应业务变更。 云原生环境支持 支持本地与分布式部署：流程框架支持本地开发环境及Dapr、Orleans等分布式云原生环境。 无缝迁移与扩展：本地定义的流程可无缝迁移到生产环境，无需修改核心业务逻辑。 核心概念详解 流程 定义与构成：流程是顶层容器，由步骤和事件路由规则构成，代表端到端业务目标。 生命周期与状态：每个流程实例有独立生命周期和状态。 步骤 基本执行单元：步骤是流程的原子性活动，封装具体业务逻辑，遵循单一职责原则。 内核函数：步骤类中用[KernelFunction]标记的方法，可被流程框架调用。 事件 信息传递与触发载体：事件由特定类表示，包含Id和Data属性，用于步骤间传递信息。 事件路由：事件路由基于Id，决定事件的流向。 上下文 运行时关键组件：上下文对象提供运行时信息和提交事件的方法，实现复杂流程控制逻辑。 SK的流程框架还在预发布版本，最终版代码可能会有偏差，但不影响我们学习。 二、构建第一个线性流程 1. 环境准备与项目设置 创建.NET控制台应用程序项目，安装Semantic Kernel流程框架核心依赖包。 Process.Core是核心库 Process.LocalRuntime提供本地运行组件。 PropertyGroup NoWarnSKEXP0080/NoWarn !-- 关闭警告 -- /PropertyGroup ItemGroup PackageReference Include=Microsoft.Extensions.Configuration Version=9.0.8 / …… 阅读全文

摘要：一、Semantic Kernel概述 1. 与LangChain对比 设计理念：LangChain以社区驱动，快速迭代，适合原型验证；Semantic Kernel则以企业级应用为目标，注重稳定性与可维护性。 核心概念：提供LangChain与Semantic Kernel的核心概念映射表，帮助开发者快速理解两者差异。 适用场景：LangChain适合快速开发和试验，Semantic Kernel更适合企业级应用，强调与现有系统的深度融合。 LangChain概念 Semantic Kernel对应概念 备注说明 Agent Agent(Planner) / Kernel Agent类似于一个高级的Agent，能根据用户目标自动生成执行计划(Plan)。而Kernel(内核)则扮演了AgentExecutor角色，是负责实际执行这个计划的核心引擎。 Tool Plugin(插件) / KernelFunction(内核函数) Plugin是SK中与tool对等的概念，代表一个能力的集合。SK的一个重要设计是它明确地将能力分成两种 Chain 手动调用链 LangChain的Chain是一种预先定义好的、线性的调用序列。在SK中，我们可以通过编写代码来手动实现类似的函数调用链，这种确定性的编排方式是理解后续自动化规划器工作原理的基础。 Memory Memory(记忆) 这个概念在两个框架中基本一致，都用于在多次交互中保持状态和上下午，从而实现连贯的对话或复杂的任务处理。 PromptTemplate 提示模版 SK将提示模板的工程化提到了一个新的高度。与LangChain中通常的代码里定义的字符串模板不同，SK推荐将提示模版做为独立的文件进行管理，并配有专门的配置文件，使其成为一个可复用、可配置的软件工件。 2. 架构概览 内核：内核是Semantic Kernel的核心，负责接收请求、编排插件、管理服务和执行任务。 插件：插件是功能扩展的核心机制，包含语义函数和原生函数，实现AI能力与传统代码的融合。 记忆：记忆模块使AI应用能够保持上下文，支持连贯对话和复杂任务处理。 3. 搭建Semantic Kernel应用 创建一个.NET项目，如控制台应用程序，并添加Semantic Kernel的NuGet包。 …… 阅读全文