XIAOSUO 记录个人学习的足迹

摘要：一、核心概念 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 所需的完整能力。 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 中重复指定 适用场景：系统级工具（如时间、日期、日志） 与 ChatOptions.Tools 的关系：两者会合并，AdditionalTools 优先级更低 AllowConcurrentInvocation（并发调用） 用途：允许模型在单次响应中并发调用多个函数 性能优势：多个独立函数可并行执行，显著减少等待时间 注意事项：确保工具函数是线程安全的 示例场景：同时查询多个城市的天气 MaximumIteration…… 阅读全文

摘要：一、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 …… 阅读全文

摘要：一、MCP概述 MCP（Model Context Protocol）是由Anthropic于2024年底提出并开源的一种协议，旨在为AI系统（如AI编程助手、Agent等）提供安全、标准化的数据访问方式。它采用客户端-服务器架构，使AI工具（如Claude Desktop、IDE插件等）能够通过MCP客户端与MCP服务端交互，访问本地或远程数据源。 1. 基本流程 AI大模型---通过函数调用---函数列表---发送给大模型---判断调用函数+生成调用参数---应用将结果返回给大模型 函数调用---交互模式---调用规范 2. MCP的意义 日常开发中由于接口碎片化，我们可能需要开发搜索、SQL数据库、API调用工具等等。 有了MCP，我们可以将 工具开发，封装成MCP服务器 AI应用开发，连接MCP服务器 数据处理与隐私安全，MCP服务器可以在本地进程中运行，对接本地设备的私有数据 服务集成与扩展效率 MCP服务器可以方便集成 MCP服务器可以复用，配置即接入 AI应用只需要实现一次MCP接入，就拥有了与所有MCP服务器通信的能力 应用场景 企业办公场景 个人AI助手场景 总之：MCP就是AI应用与外部的工具。 3. 基础概念 MCP 是客户端-服务端架构，一个 Host 可以连接多个 MCP Server。 MCP Hosts（宿主程序）：如Claude Desktop、IDE等，通过MCP访问数据。 MCP Clients（客户端）：与服务器建立1:1连接，处理通信。 MCP Servers（服务端）：轻量级程序，提供标准化的数据或工具访问能力。 Local Data Sources（本地数据源）：如文件、数据库等，由MCP服务端安全访问。 Remote Services（远程服务）：如API、云服务等，MCP服务端可代理访问。 6. 协议层与传输层 协议层：负责消息封装（framing）、请求/响应关联、高级通信模式管理。 传输层：支持两种通信方式 Stdio传输（标准输入/输出）：适用于本地进程间通信。 HTTP + SSE传输： 服务端→客户端：Server-Sent Events（SSE） 客户端→服务端：HTTP POST 适用于远程网络通信。 所有传输均采用JSON-RPC 2.0进行消息交换…… 阅读全文

摘要：一、实现多格式文档解析器 1. 通用文档解析接口 我们先在ai文件夹创建一个名为parsers的pathon包，用来实现多格式文档解析器。 接着我们先定义一个解析器接口 # app/ai/parsers/base.py from abc import ABC, abstractmethod from typing import List, Dict, Any from pydantic import BaseModel class DocumentChunk(BaseModel): 文档块 content: str metadata: Dict[str, Any] chunk_index: int class DocumentParser(ABC): 文档解析器抽象基类 @abstractmethod def parse(self, file_path: str, file_content: bytes) - List[DocumentChunk]: 解析文档并返回文档块列表 pass DocumentChunk是文档解析器返回类型。 DocumentParser是抽象基类，通过继承ABC来定义。 2. 实现文本解析器 # app/ai/parsers/txt_parser.py from typing import List from langchain_text_splitters import RecursiveCharacterTextSplitter from app.ai.parsers.base import DocumentParser, DocumentChunk class TextParser(DocumentParser): 文本文件解析器 def __init__(self, chunk_size: int = 1000, chunk_overlap: int = 200): 初始化文本解析器 Args: chunk_size: 文档块大小 chunk_overlap: 文档块重叠大小 …… 阅读全文