尧图网页设计 
1. 这期日报到底在聊什么先把话说在前头这不是一篇“行业综述”也不是那种读完就忘的快讯合集。我做 Agent 和 LLM 方向的技术跟踪已经有一段时间了每天刷的东西很杂——论文、开源仓库、社区讨论、踩坑记录全都看。时间久了会发现一个规律真正值得记下来的东西往往不是某个模型又刷了多少分而是工程实践中反复出现的那些卡点。这期日报的核心就是围绕 Agent、LLM、RAG、GraphRAG、MCP 这几个关键词把最近一段时间里最值得关注的动向和实操经验梳理一遍。如果你正在做 AI Agent 相关的项目或者正在搭建自己的 RAG 知识库又或者只是对 MCP 到底是什么、GraphRAG 和普通 RAG 有什么区别感到困惑那这篇内容应该能帮你省下不少翻文档的时间。我会尽量把每个技术点讲透不光说“是什么”还会说“为什么这么做”以及“实际做的时候会遇到什么问题”。这期内容适合几类人看一是刚入门 Agent 开发、想搞清楚整体架构和技术选型的新手二是已经在做 RAG 项目、但遇到了检索效果瓶颈的开发者三是对 MCP 协议感兴趣、想了解它到底解决了什么问题的工程师。不管你是哪一类我都建议你从头看因为这几个概念之间是有关联的跳着看容易断片。2. Agent 架构的核心思路与选型逻辑2.1 为什么 Agent 架构没有标准答案很多人一开始做 Agent 项目第一反应是去找一个“标准架构”照着搭。我刚开始也是这个思路后来发现根本行不通。Agent 架构的选型本质上取决于你的任务类型、对延迟的要求、以及你能接受的成本上限。这三个因素一变架构就得跟着变。举个很实际的例子。如果你做的是一个单轮问答型 Agent用户问一个问题Agent 调用一两个工具就能给出答案那你的架构可以非常简单一个 LLM 做决策几个工具函数做执行中间加一个循环控制就够了。但如果你做的是一个多步骤任务型 Agent比如让 Agent 自己去搜索资料、整理信息、生成报告那你就需要考虑任务分解、中间状态管理、错误恢复这些问题架构复杂度会直接上一个台阶。我见过不少人一上来就搞多 Agent 协作结果发现调试成本极高每个 Agent 之间的通信协议、状态同步、优先级冲突都要处理最后项目进度被拖得很难看。所以我的建议是从最简单的架构开始遇到瓶颈再升级。不要为了架构而架构。2.2 单 Agent 与多 Agent 的取舍单 Agent 架构的核心优势是链路短、调试简单。一个 LLM 负责所有决策工具调用和结果处理都在一个循环里完成。这种架构适合任务边界清晰、步骤数可控的场景。比如一个代码生成 Agent用户给需求Agent 生成代码、运行测试、根据报错修改这个流程用单 Agent 完全能搞定。多 Agent 架构的优势在于职责分离。当你的任务需要不同领域的专业知识时让一个 Agent 同时处理所有事情效果往往不好。比如一个 Agent 既要懂数据库查询又要懂前端渲染还要懂业务逻辑那它的 prompt 会变得极其臃肿决策质量会下降。这时候拆成多个专职 Agent每个 Agent 只关注自己的领域整体效果反而更好。但多 Agent 的代价也很明显。Agent 之间的通信需要定义协议状态需要同步错误需要传播和处理。我实测下来多 Agent 系统的调试时间通常是单 Agent 的三到五倍。所以我的判断标准是当单 Agent 的 prompt 超过 2000 字或者工具数量超过 15 个再考虑拆多 Agent。2.3 Agent 安全与容错控制的工程实践Agent 安全这个话题最近讨论得很多但很多讨论停留在理论层面。我从工程角度说说实际怎么做。第一层是输入过滤。用户输入进入 Agent 之前需要做一轮清洗把明显的注入攻击、越权指令过滤掉。这个用规则引擎就能做不需要上模型。第二层是工具调用权限控制。不是所有工具都对所有 Agent 开放。比如文件删除、数据库写入这类高危操作应该单独授权并且加上二次确认机制。我通常会在工具调用层加一个权限检查中间件根据当前 Agent 的角色和任务上下文决定是否放行。第三层是输出校验。Agent 生成的最终结果尤其是涉及代码执行、文件操作的需要经过一轮校验才能落地。校验规则可以很简单比如检查文件路径是否在允许范围内、检查 SQL 语句是否包含危险操作。容错控制这块核心思路是让 Agent 具备自我修复能力。具体做法是在 Agent 循环里加入错误分类和处理逻辑。工具调用失败时不是直接报错退出而是把错误信息返回给 LLM让它决定下一步怎么做。我试过在 prompt 里明确告诉 LLM“如果工具调用失败先分析失败原因然后决定是重试、换工具、还是放弃当前步骤。”实测下来这种方式的恢复成功率比硬编码重试逻辑高不少。3. RAG 的瓶颈到底在哪里3.1 从 RAG 到 GraphRAG 的演进逻辑RAG 的核心思路很简单把文档切块、向量化、存进向量数据库用户提问时检索最相关的块拼进 prompt 让 LLM 生成答案。这个思路在简单场景下很好用但一旦文档量大、问题复杂瓶颈就出来了。最大的瓶颈是检索粒度和语义完整性的矛盾。切块太小检索到的片段缺乏上下文LLM 拼不出完整答案切块太大检索精度下降噪音变多。我试过各种切块策略固定长度、按段落、按语义每种都有各自的适用场景但没有一种能通吃。GraphRAG 的思路不一样。它不依赖单纯的向量相似度而是先构建一个知识图谱把文档里的实体、关系、事件抽出来形成结构化的知识网络。用户提问时先在图谱上做推理和检索找到相关的实体和关系再把这些结构化信息喂给 LLM。这样做的好处是检索结果自带上下文和逻辑关系LLM 不需要自己去拼凑。但 GraphRAG 的代价也很明显。构建知识图谱需要额外的抽取和清洗流程成本比普通 RAG 高不少。而且图谱的质量直接决定检索效果如果实体抽取不准、关系定义混乱效果可能还不如普通 RAG。我的经验是文档量在 1000 篇以下、问题类型以事实查询为主普通 RAG 够用文档量超过 5000 篇、问题涉及多跳推理和关系查询再考虑上 GraphRAG。3.2 KG 知识库、RAG 知识库和结构化知识库的区别这三个概念经常被混在一起说但它们的定位和适用场景完全不同。KG 知识库的核心是实体和关系。它存储的是“A 是 B 的 C”这种三元组适合做推理和关系查询。比如你问“张三和李四是什么关系”KG 可以直接沿着关系边找到答案。但 KG 的构建和维护成本高需要定义本体、抽取实体、消歧、对齐每一步都有坑。RAG 知识库的核心是文本块和向量。它存储的是文档片段和对应的向量表示适合做语义检索和问答。你问“这份文档里关于 X 是怎么说的”RAG 可以找到最相关的片段。但 RAG 不擅长处理关系型问题因为它没有显式的结构信息。结构化知识库的范围更广包括关系型数据库、表格、JSON 文档等。它的优势是查询精确、更新方便但灵活性差不适合处理非结构化文本。实际项目中这三者往往是组合使用的。我的做法是用 RAG 做第一层检索找到相关文档片段如果问题涉及关系推理再查 KG 补充结构化信息最后把两者拼在一起喂给 LLM。这样既能利用 RAG 的灵活性又能借助 KG 的推理能力。3.3 RAG 知识库能存图片吗这个问题我被问过很多次。答案是能但不是直接存。RAG 知识库的核心是向量检索而向量检索的前提是把内容转成向量。图片本身不能直接转成文本向量需要先经过处理。常见的做法有两种第一种是图片描述生成。用多模态模型给每张图片生成一段文字描述然后把描述文本向量化存进知识库。检索时匹配的是描述文本返回的是图片链接或路径。这种方式的优点是实现简单缺点是描述质量依赖模型能力细节容易丢失。第二种是多模态向量化。直接用支持图文的多模态嵌入模型把图片和文本映射到同一个向量空间。检索时可以用文本查图片也可以用图片查图片。这种方式效果更好但对模型和基础设施的要求更高。我实测下来如果图片是流程图、架构图这类信息密度高的图第一种方式的效果往往不够好因为文字描述很难完整表达图里的结构信息。这时候可以考虑把图片里的关键信息手动提取出来做成结构化的文本描述再存进知识库。虽然麻烦一点但检索准确率会高很多。4. MCP 协议到底解决了什么问题4.1 MCP 是什么为什么突然火了MCP 的全称是 Model Context Protocol翻译过来就是“模型上下文协议”。它的核心目标是标准化 LLM 与外部工具、数据源之间的交互方式。在 MCP 出现之前每个 LLM 应用要接入外部工具都得自己定义一套接口。你接一个数据库是一个写法接一个 API 是另一个写法接一个文件系统又是另一个写法。代码重复度高维护成本大而且不同应用之间没法复用。MCP 的思路是定义一个统一的协议工具提供方按照协议实现服务端LLM 应用按照协议实现客户端双方通过标准化的消息格式通信。这样一来工具提供方只需要实现一次就能被所有支持 MCP 的应用使用应用方也只需要实现一次客户端就能接入所有支持 MCP 的工具。这个思路其实不新鲜类似 LSPLanguage Server Protocol在编辑器领域的做法。但 MCP 赶上了 LLM 应用爆发的时间点所以关注度很高。我实测下来MCP 确实能显著降低工具接入的成本尤其是当你需要接入多个外部服务时优势非常明显。4.2 MCP 的典型应用场景MCP 目前最常见的应用场景是开发工具集成。比如代码编辑器通过 MCP 接入代码分析工具、数据库客户端、API 调试工具让 LLM 能够直接操作这些工具完成开发任务。我试过用 MCP 把数据库查询工具接入到 Agent 里配置过程比之前自己写接口简单很多基本上就是填几个参数的事。另一个场景是知识库接入。通过 MCP 把向量数据库、文档管理系统、Wiki 接入到 LLM 应用里让 LLM 能够直接检索和引用这些知识源。这种方式比传统的 RAG 管道更灵活因为 MCP 支持动态发现工具和能力不需要提前硬编码。还有一个场景是多 Agent 协作。不同 Agent 之间通过 MCP 通信共享工具和数据源。这种方式的好处是解耦彻底每个 Agent 只需要关心自己的逻辑工具接入的事情交给 MCP 处理。4.3 MCP 接入的常见坑与排查MCP 虽然好用但实际接入过程中坑也不少。我整理了几个最常见的问题和排查思路。第一个坑是授权配置错误。MCP 服务端通常需要授权才能访问如果授权信息填错或者过期客户端会直接报错。排查方法是先单独测试服务端是否正常再检查客户端的授权配置。第二个坑是工具描述不清晰。MCP 服务端注册工具时需要提供工具的名称、描述、参数 schema。如果描述写得太模糊LLM 可能不知道该什么时候调用这个工具。我的经验是工具描述要写得像给新人看的文档把使用场景、输入输出、注意事项都写清楚。第三个坑是流式输出处理不当。MCP 支持流式输出但很多客户端实现没有正确处理流式消息导致内容丢失或顺序错乱。排查方法是先确认服务端是否正常发送流式消息再检查客户端的消息处理逻辑。第四个坑是版本兼容性问题。MCP 协议还在演进中不同版本之间可能有差异。如果客户端和服务端版本不匹配可能会出现各种奇怪的问题。建议在接入前先确认双方支持的协议版本。5. LLM 工程实践中的关键细节5.1 LLM as Judge 的使用边界LLM as Judge 这个思路最近很火核心是用 LLM 来评估另一个 LLM 的输出质量。这个思路在缺乏人工标注的场景下确实有用但用不好也会出问题。我踩过的坑是评估标准不一致。同一个输出不同的 prompt 模板给出的评分可能差很多。后来我的做法是把评估标准拆成多个维度每个维度单独评分最后加权汇总。比如评估一个问答结果可以拆成“事实准确性”“完整性”“表达清晰度”三个维度每个维度用独立的 prompt 来评。这样虽然麻烦一点但结果稳定很多。另一个坑是位置偏差。LLM 在对比两个输出时往往倾向于选择第一个或最后一个。解决办法是交换顺序多次评估取平均分。我通常会让 LLM 分别以 A-B 和 B-A 的顺序评估两次如果两次结果不一致就说明这两个输出质量接近需要更细粒度的评估。5.2 基于 LLM 的单元测试怎么做用 LLM 生成单元测试这个思路听起来很美但实际做的时候要注意几点。第一测试用例的覆盖范围要明确。LLM 生成的测试往往集中在正常路径对边界条件和异常路径覆盖不足。我的做法是先让 LLM 生成一批测试然后人工检查覆盖了哪些分支再针对未覆盖的分支补充 prompt 让 LLM 重新生成。第二断言要具体。LLM 生成的测试有时候断言写得太宽松比如只检查返回值不为空不检查具体内容。这种测试跑起来全是绿的但实际没什么用。我通常会在 prompt 里明确要求“断言必须检查具体的返回值、异常类型、调用次数。”第三测试要能独立运行。LLM 生成的测试有时候会依赖外部状态比如数据库连接、文件系统。这种测试在 CI 环境里很容易挂。解决办法是在 prompt 里要求使用 mock 和 stub把外部依赖隔离掉。5.3 LLM 请求失败的常见原因“LLM request failed: provider rejected the request schema or tool payload”这个报错我见过很多次原因通常有几个。最常见的是工具参数 schema 不匹配。你定义的工具参数类型和实际传入的类型不一致比如定义的是 integer传的是 string。排查方法是打印出实际的请求 payload和工具定义逐字段对比。另一个原因是请求体过大。有些 provider 对请求体大小有限制如果 prompt 太长或者工具定义太多请求会被拒绝。解决办法是精简 prompt或者把工具分组按需加载。还有一个原因是并发限制。有些 provider 对并发请求数有限制超过限制会直接拒绝。这种情况需要加退避重试逻辑我通常用指数退避初始间隔 1 秒最大重试 5 次。6. 实操过程中的关键环节记录6.1 在 Mac 上搭建 RAG 知识库的完整流程我在 Mac 上搭过好几套 RAG 知识库流程基本固定下来了。这里把关键步骤和参数选择记录一下。第一步是环境准备。Python 环境用 conda 管理创建一个独立环境避免依赖冲突。向量数据库我常用 Chroma轻量、易部署本地开发够用。嵌入模型用 sentence-transformers 的 all-MiniLM-L6-v2体积小、速度快适合本地跑。第二步是文档处理。把文档统一转成纯文本PDF 用 pdfplumber 提取Word 用 python-docxMarkdown 直接读。提取出来的文本要做清洗去掉页眉页脚、多余空行、特殊字符。第三步是切块策略。我试过固定长度切块和按语义切块最后发现按段落切块 最大长度限制效果最稳。具体做法是先按空行分段如果某段超过 500 字再按句子切分保证每块在 200 到 500 字之间。这个范围是我实测下来检索效果和上下文完整性的平衡点。第四步是向量化和存储。用嵌入模型把每个文本块转成向量存进 Chroma。存储时把原文、元数据来源、页码、时间一起存进去方便后续检索和引用。第五步是检索和生成。用户提问时先把问题向量化在 Chroma 里检索最相似的 top-k 个块k 一般取 3 到 5。然后把检索结果拼进 prompt让 LLM 生成答案。prompt 里要明确要求 LLM 基于检索内容回答不要自己编。6.2 使用 MCP 工具流式输出内容到文件这个场景我最近刚做过需求是把 Agent 生成的内容实时写入文件而不是等全部生成完再写。用 MCP 实现的话核心是服务端支持流式输出客户端正确处理流式消息。服务端这边工具的实现要支持分块返回。比如写文件工具不要一次性写入全部内容而是接收一个 chunk 参数每次写入一部分。客户端这边要监听流式消息每收到一个 chunk 就调用一次写文件工具。我踩过的坑是消息顺序问题。流式消息到达客户端的顺序不一定和发送顺序一致如果直接按到达顺序写入文件内容会乱。解决办法是在消息里加一个序号客户端按序号排序后再写入。另一个坑是错误处理。流式输出过程中如果某个 chunk 写入失败需要能够回滚或者重试。我的做法是在服务端维护一个写入状态客户端发现失败时发送重试请求服务端从上次成功的 chunk 继续写。6.3 Agent 项目的目录结构和配置管理Agent 项目做多了会发现目录结构对维护效率影响很大。我现在的习惯是分成几个固定目录agents/存放各个 Agent 的定义和 prompt 模板tools/存放工具实现每个工具一个文件configs/存放配置文件包括模型参数、工具权限、环境变量tests/存放测试用例logs/存放运行日志配置管理这块我强烈建议不要把配置硬编码在代码里。用 YAML 或 JSON 文件管理配置代码里只读配置。这样切换环境、调整参数的时候不需要改代码改配置文件就行。敏感信息比如 API key用环境变量注入不要写进配置文件。7. 常见问题与排查技巧实录7.1 Agent 开发中的典型问题速查问题现象可能原因排查思路解决方案Agent 循环不退出终止条件未触发打印每轮决策日志加最大轮次限制超限强制退出工具调用参数错误schema 定义不清晰对比实际参数和 schema完善工具描述加参数校验检索结果不相关切块策略或嵌入模型问题人工检查检索结果调整切块粒度换嵌入模型生成内容重复prompt 缺少去重指令检查 prompt 模板加“不要重复”指令加后处理去重响应延迟高工具调用串行执行分析各步骤耗时并行化独立工具调用7.2 我踩过的几个印象深刻的坑第一个坑是工具描述写得太简略。刚开始做 Agent 的时候工具描述就写一句话比如“查询数据库”。结果 LLM 经常在不该调用的时候调用该调用的时候不调用。后来我把描述改成“当用户询问具体数据、统计信息、或需要从数据库获取信息时调用此工具。输入为 SQL 查询语句输出为查询结果。”改完之后工具调用的准确率明显提升。第二个坑是没有做超时控制。有一次 Agent 调用一个外部 API那个 API 挂了请求一直不返回Agent 就卡在那里。后来我给所有工具调用都加了超时默认 30 秒超时后返回错误信息让 LLM 决定下一步。第三个坑是日志记录不完整。出问题的时候想排查发现日志里只有最终结果没有中间过程。后来我在 Agent 循环的每个关键节点都加了日志包括输入、决策、工具调用、返回结果。日志量大了很多但排查效率提升非常明显。7.3 性能优化的几个实用技巧缓存是最有效的优化手段。LLM 调用结果、嵌入向量、检索结果这些都可以缓存。我通常用 Redis 做缓存设置合理的过期时间。实测下来缓存能减少 30% 到 50% 的重复计算。批处理也很重要。如果有多个独立的 LLM 调用不要一个一个串行执行打包成一批并行发送。很多 provider 支持批量请求能显著降低总延迟。模型分级是另一个思路。不是所有任务都需要用最大的模型。简单的分类、抽取任务用小模型复杂的推理、生成任务用大模型。我通常会在 Agent 里配置多个模型根据任务类型动态选择。prompt 精简经常被忽视。prompt 越长推理时间越长成本越高。定期审查 prompt删掉不必要的内容合并重复的指令能省不少资源。8. 一些个人体会做 Agent 和 LLM 相关的工作最大的感受是变化太快。今天好用的方案明天可能就有更好的替代。所以我的习惯是保持关注但不盲目追新。新技术出来先小范围试验证有效再推广到项目里。另一个体会是工程能力比模型能力更重要。同样的模型不同的工程实现效果可能差好几倍。工具调用的稳定性、错误处理、状态管理、日志记录这些看起来不起眼的东西往往决定了项目能不能真正落地。最后说一个实际的小技巧给 Agent 加一个“思考日志”。让 Agent 在每一步决策前先输出一段简短的思考过程记录为什么选择这个工具、为什么这样处理。这个日志不一定要展示给用户但排查问题的时候非常有用。我试过之后调试效率至少提升了一倍。 Agent、LLM、RAG、GraphRAG、MCP工程实践与避坑指南
1. 这期日报到底在聊什么先把话说在前头这不是一篇“行业综述”也不是那种读完就忘的快讯合集。我做 Agent 和 LLM 方向的技术跟踪已经有一段时间了每天刷的东西很杂——论文、开源仓库、社区讨论、踩坑记录全都看。时间久了会发现一个规律真正值得记下来的东西往往不是某个模型又刷了多少分而是工程实践中反复出现的那些卡点。这期日报的核心就是围绕 Agent、LLM、RAG、GraphRAG、MCP 这几个关键词把最近一段时间里最值得关注的动向和实操经验梳理一遍。如果你正在做 AI Agent 相关的项目或者正在搭建自己的 RAG 知识库又或者只是对 MCP 到底是什么、GraphRAG 和普通 RAG 有什么区别感到困惑那这篇内容应该能帮你省下不少翻文档的时间。我会尽量把每个技术点讲透不光说“是什么”还会说“为什么这么做”以及“实际做的时候会遇到什么问题”。这期内容适合几类人看一是刚入门 Agent 开发、想搞清楚整体架构和技术选型的新手二是已经在做 RAG 项目、但遇到了检索效果瓶颈的开发者三是对 MCP 协议感兴趣、想了解它到底解决了什么问题的工程师。不管你是哪一类我都建议你从头看因为这几个概念之间是有关联的跳着看容易断片。2. Agent 架构的核心思路与选型逻辑2.1 为什么 Agent 架构没有标准答案很多人一开始做 Agent 项目第一反应是去找一个“标准架构”照着搭。我刚开始也是这个思路后来发现根本行不通。Agent 架构的选型本质上取决于你的任务类型、对延迟的要求、以及你能接受的成本上限。这三个因素一变架构就得跟着变。举个很实际的例子。如果你做的是一个单轮问答型 Agent用户问一个问题Agent 调用一两个工具就能给出答案那你的架构可以非常简单一个 LLM 做决策几个工具函数做执行中间加一个循环控制就够了。但如果你做的是一个多步骤任务型 Agent比如让 Agent 自己去搜索资料、整理信息、生成报告那你就需要考虑任务分解、中间状态管理、错误恢复这些问题架构复杂度会直接上一个台阶。我见过不少人一上来就搞多 Agent 协作结果发现调试成本极高每个 Agent 之间的通信协议、状态同步、优先级冲突都要处理最后项目进度被拖得很难看。所以我的建议是从最简单的架构开始遇到瓶颈再升级。不要为了架构而架构。2.2 单 Agent 与多 Agent 的取舍单 Agent 架构的核心优势是链路短、调试简单。一个 LLM 负责所有决策工具调用和结果处理都在一个循环里完成。这种架构适合任务边界清晰、步骤数可控的场景。比如一个代码生成 Agent用户给需求Agent 生成代码、运行测试、根据报错修改这个流程用单 Agent 完全能搞定。多 Agent 架构的优势在于职责分离。当你的任务需要不同领域的专业知识时让一个 Agent 同时处理所有事情效果往往不好。比如一个 Agent 既要懂数据库查询又要懂前端渲染还要懂业务逻辑那它的 prompt 会变得极其臃肿决策质量会下降。这时候拆成多个专职 Agent每个 Agent 只关注自己的领域整体效果反而更好。但多 Agent 的代价也很明显。Agent 之间的通信需要定义协议状态需要同步错误需要传播和处理。我实测下来多 Agent 系统的调试时间通常是单 Agent 的三到五倍。所以我的判断标准是当单 Agent 的 prompt 超过 2000 字或者工具数量超过 15 个再考虑拆多 Agent。2.3 Agent 安全与容错控制的工程实践Agent 安全这个话题最近讨论得很多但很多讨论停留在理论层面。我从工程角度说说实际怎么做。第一层是输入过滤。用户输入进入 Agent 之前需要做一轮清洗把明显的注入攻击、越权指令过滤掉。这个用规则引擎就能做不需要上模型。第二层是工具调用权限控制。不是所有工具都对所有 Agent 开放。比如文件删除、数据库写入这类高危操作应该单独授权并且加上二次确认机制。我通常会在工具调用层加一个权限检查中间件根据当前 Agent 的角色和任务上下文决定是否放行。第三层是输出校验。Agent 生成的最终结果尤其是涉及代码执行、文件操作的需要经过一轮校验才能落地。校验规则可以很简单比如检查文件路径是否在允许范围内、检查 SQL 语句是否包含危险操作。容错控制这块核心思路是让 Agent 具备自我修复能力。具体做法是在 Agent 循环里加入错误分类和处理逻辑。工具调用失败时不是直接报错退出而是把错误信息返回给 LLM让它决定下一步怎么做。我试过在 prompt 里明确告诉 LLM“如果工具调用失败先分析失败原因然后决定是重试、换工具、还是放弃当前步骤。”实测下来这种方式的恢复成功率比硬编码重试逻辑高不少。3. RAG 的瓶颈到底在哪里3.1 从 RAG 到 GraphRAG 的演进逻辑RAG 的核心思路很简单把文档切块、向量化、存进向量数据库用户提问时检索最相关的块拼进 prompt 让 LLM 生成答案。这个思路在简单场景下很好用但一旦文档量大、问题复杂瓶颈就出来了。最大的瓶颈是检索粒度和语义完整性的矛盾。切块太小检索到的片段缺乏上下文LLM 拼不出完整答案切块太大检索精度下降噪音变多。我试过各种切块策略固定长度、按段落、按语义每种都有各自的适用场景但没有一种能通吃。GraphRAG 的思路不一样。它不依赖单纯的向量相似度而是先构建一个知识图谱把文档里的实体、关系、事件抽出来形成结构化的知识网络。用户提问时先在图谱上做推理和检索找到相关的实体和关系再把这些结构化信息喂给 LLM。这样做的好处是检索结果自带上下文和逻辑关系LLM 不需要自己去拼凑。但 GraphRAG 的代价也很明显。构建知识图谱需要额外的抽取和清洗流程成本比普通 RAG 高不少。而且图谱的质量直接决定检索效果如果实体抽取不准、关系定义混乱效果可能还不如普通 RAG。我的经验是文档量在 1000 篇以下、问题类型以事实查询为主普通 RAG 够用文档量超过 5000 篇、问题涉及多跳推理和关系查询再考虑上 GraphRAG。3.2 KG 知识库、RAG 知识库和结构化知识库的区别这三个概念经常被混在一起说但它们的定位和适用场景完全不同。KG 知识库的核心是实体和关系。它存储的是“A 是 B 的 C”这种三元组适合做推理和关系查询。比如你问“张三和李四是什么关系”KG 可以直接沿着关系边找到答案。但 KG 的构建和维护成本高需要定义本体、抽取实体、消歧、对齐每一步都有坑。RAG 知识库的核心是文本块和向量。它存储的是文档片段和对应的向量表示适合做语义检索和问答。你问“这份文档里关于 X 是怎么说的”RAG 可以找到最相关的片段。但 RAG 不擅长处理关系型问题因为它没有显式的结构信息。结构化知识库的范围更广包括关系型数据库、表格、JSON 文档等。它的优势是查询精确、更新方便但灵活性差不适合处理非结构化文本。实际项目中这三者往往是组合使用的。我的做法是用 RAG 做第一层检索找到相关文档片段如果问题涉及关系推理再查 KG 补充结构化信息最后把两者拼在一起喂给 LLM。这样既能利用 RAG 的灵活性又能借助 KG 的推理能力。3.3 RAG 知识库能存图片吗这个问题我被问过很多次。答案是能但不是直接存。RAG 知识库的核心是向量检索而向量检索的前提是把内容转成向量。图片本身不能直接转成文本向量需要先经过处理。常见的做法有两种第一种是图片描述生成。用多模态模型给每张图片生成一段文字描述然后把描述文本向量化存进知识库。检索时匹配的是描述文本返回的是图片链接或路径。这种方式的优点是实现简单缺点是描述质量依赖模型能力细节容易丢失。第二种是多模态向量化。直接用支持图文的多模态嵌入模型把图片和文本映射到同一个向量空间。检索时可以用文本查图片也可以用图片查图片。这种方式效果更好但对模型和基础设施的要求更高。我实测下来如果图片是流程图、架构图这类信息密度高的图第一种方式的效果往往不够好因为文字描述很难完整表达图里的结构信息。这时候可以考虑把图片里的关键信息手动提取出来做成结构化的文本描述再存进知识库。虽然麻烦一点但检索准确率会高很多。4. MCP 协议到底解决了什么问题4.1 MCP 是什么为什么突然火了MCP 的全称是 Model Context Protocol翻译过来就是“模型上下文协议”。它的核心目标是标准化 LLM 与外部工具、数据源之间的交互方式。在 MCP 出现之前每个 LLM 应用要接入外部工具都得自己定义一套接口。你接一个数据库是一个写法接一个 API 是另一个写法接一个文件系统又是另一个写法。代码重复度高维护成本大而且不同应用之间没法复用。MCP 的思路是定义一个统一的协议工具提供方按照协议实现服务端LLM 应用按照协议实现客户端双方通过标准化的消息格式通信。这样一来工具提供方只需要实现一次就能被所有支持 MCP 的应用使用应用方也只需要实现一次客户端就能接入所有支持 MCP 的工具。这个思路其实不新鲜类似 LSPLanguage Server Protocol在编辑器领域的做法。但 MCP 赶上了 LLM 应用爆发的时间点所以关注度很高。我实测下来MCP 确实能显著降低工具接入的成本尤其是当你需要接入多个外部服务时优势非常明显。4.2 MCP 的典型应用场景MCP 目前最常见的应用场景是开发工具集成。比如代码编辑器通过 MCP 接入代码分析工具、数据库客户端、API 调试工具让 LLM 能够直接操作这些工具完成开发任务。我试过用 MCP 把数据库查询工具接入到 Agent 里配置过程比之前自己写接口简单很多基本上就是填几个参数的事。另一个场景是知识库接入。通过 MCP 把向量数据库、文档管理系统、Wiki 接入到 LLM 应用里让 LLM 能够直接检索和引用这些知识源。这种方式比传统的 RAG 管道更灵活因为 MCP 支持动态发现工具和能力不需要提前硬编码。还有一个场景是多 Agent 协作。不同 Agent 之间通过 MCP 通信共享工具和数据源。这种方式的好处是解耦彻底每个 Agent 只需要关心自己的逻辑工具接入的事情交给 MCP 处理。4.3 MCP 接入的常见坑与排查MCP 虽然好用但实际接入过程中坑也不少。我整理了几个最常见的问题和排查思路。第一个坑是授权配置错误。MCP 服务端通常需要授权才能访问如果授权信息填错或者过期客户端会直接报错。排查方法是先单独测试服务端是否正常再检查客户端的授权配置。第二个坑是工具描述不清晰。MCP 服务端注册工具时需要提供工具的名称、描述、参数 schema。如果描述写得太模糊LLM 可能不知道该什么时候调用这个工具。我的经验是工具描述要写得像给新人看的文档把使用场景、输入输出、注意事项都写清楚。第三个坑是流式输出处理不当。MCP 支持流式输出但很多客户端实现没有正确处理流式消息导致内容丢失或顺序错乱。排查方法是先确认服务端是否正常发送流式消息再检查客户端的消息处理逻辑。第四个坑是版本兼容性问题。MCP 协议还在演进中不同版本之间可能有差异。如果客户端和服务端版本不匹配可能会出现各种奇怪的问题。建议在接入前先确认双方支持的协议版本。5. LLM 工程实践中的关键细节5.1 LLM as Judge 的使用边界LLM as Judge 这个思路最近很火核心是用 LLM 来评估另一个 LLM 的输出质量。这个思路在缺乏人工标注的场景下确实有用但用不好也会出问题。我踩过的坑是评估标准不一致。同一个输出不同的 prompt 模板给出的评分可能差很多。后来我的做法是把评估标准拆成多个维度每个维度单独评分最后加权汇总。比如评估一个问答结果可以拆成“事实准确性”“完整性”“表达清晰度”三个维度每个维度用独立的 prompt 来评。这样虽然麻烦一点但结果稳定很多。另一个坑是位置偏差。LLM 在对比两个输出时往往倾向于选择第一个或最后一个。解决办法是交换顺序多次评估取平均分。我通常会让 LLM 分别以 A-B 和 B-A 的顺序评估两次如果两次结果不一致就说明这两个输出质量接近需要更细粒度的评估。5.2 基于 LLM 的单元测试怎么做用 LLM 生成单元测试这个思路听起来很美但实际做的时候要注意几点。第一测试用例的覆盖范围要明确。LLM 生成的测试往往集中在正常路径对边界条件和异常路径覆盖不足。我的做法是先让 LLM 生成一批测试然后人工检查覆盖了哪些分支再针对未覆盖的分支补充 prompt 让 LLM 重新生成。第二断言要具体。LLM 生成的测试有时候断言写得太宽松比如只检查返回值不为空不检查具体内容。这种测试跑起来全是绿的但实际没什么用。我通常会在 prompt 里明确要求“断言必须检查具体的返回值、异常类型、调用次数。”第三测试要能独立运行。LLM 生成的测试有时候会依赖外部状态比如数据库连接、文件系统。这种测试在 CI 环境里很容易挂。解决办法是在 prompt 里要求使用 mock 和 stub把外部依赖隔离掉。5.3 LLM 请求失败的常见原因“LLM request failed: provider rejected the request schema or tool payload”这个报错我见过很多次原因通常有几个。最常见的是工具参数 schema 不匹配。你定义的工具参数类型和实际传入的类型不一致比如定义的是 integer传的是 string。排查方法是打印出实际的请求 payload和工具定义逐字段对比。另一个原因是请求体过大。有些 provider 对请求体大小有限制如果 prompt 太长或者工具定义太多请求会被拒绝。解决办法是精简 prompt或者把工具分组按需加载。还有一个原因是并发限制。有些 provider 对并发请求数有限制超过限制会直接拒绝。这种情况需要加退避重试逻辑我通常用指数退避初始间隔 1 秒最大重试 5 次。6. 实操过程中的关键环节记录6.1 在 Mac 上搭建 RAG 知识库的完整流程我在 Mac 上搭过好几套 RAG 知识库流程基本固定下来了。这里把关键步骤和参数选择记录一下。第一步是环境准备。Python 环境用 conda 管理创建一个独立环境避免依赖冲突。向量数据库我常用 Chroma轻量、易部署本地开发够用。嵌入模型用 sentence-transformers 的 all-MiniLM-L6-v2体积小、速度快适合本地跑。第二步是文档处理。把文档统一转成纯文本PDF 用 pdfplumber 提取Word 用 python-docxMarkdown 直接读。提取出来的文本要做清洗去掉页眉页脚、多余空行、特殊字符。第三步是切块策略。我试过固定长度切块和按语义切块最后发现按段落切块 最大长度限制效果最稳。具体做法是先按空行分段如果某段超过 500 字再按句子切分保证每块在 200 到 500 字之间。这个范围是我实测下来检索效果和上下文完整性的平衡点。第四步是向量化和存储。用嵌入模型把每个文本块转成向量存进 Chroma。存储时把原文、元数据来源、页码、时间一起存进去方便后续检索和引用。第五步是检索和生成。用户提问时先把问题向量化在 Chroma 里检索最相似的 top-k 个块k 一般取 3 到 5。然后把检索结果拼进 prompt让 LLM 生成答案。prompt 里要明确要求 LLM 基于检索内容回答不要自己编。6.2 使用 MCP 工具流式输出内容到文件这个场景我最近刚做过需求是把 Agent 生成的内容实时写入文件而不是等全部生成完再写。用 MCP 实现的话核心是服务端支持流式输出客户端正确处理流式消息。服务端这边工具的实现要支持分块返回。比如写文件工具不要一次性写入全部内容而是接收一个 chunk 参数每次写入一部分。客户端这边要监听流式消息每收到一个 chunk 就调用一次写文件工具。我踩过的坑是消息顺序问题。流式消息到达客户端的顺序不一定和发送顺序一致如果直接按到达顺序写入文件内容会乱。解决办法是在消息里加一个序号客户端按序号排序后再写入。另一个坑是错误处理。流式输出过程中如果某个 chunk 写入失败需要能够回滚或者重试。我的做法是在服务端维护一个写入状态客户端发现失败时发送重试请求服务端从上次成功的 chunk 继续写。6.3 Agent 项目的目录结构和配置管理Agent 项目做多了会发现目录结构对维护效率影响很大。我现在的习惯是分成几个固定目录agents/存放各个 Agent 的定义和 prompt 模板tools/存放工具实现每个工具一个文件configs/存放配置文件包括模型参数、工具权限、环境变量tests/存放测试用例logs/存放运行日志配置管理这块我强烈建议不要把配置硬编码在代码里。用 YAML 或 JSON 文件管理配置代码里只读配置。这样切换环境、调整参数的时候不需要改代码改配置文件就行。敏感信息比如 API key用环境变量注入不要写进配置文件。7. 常见问题与排查技巧实录7.1 Agent 开发中的典型问题速查问题现象可能原因排查思路解决方案Agent 循环不退出终止条件未触发打印每轮决策日志加最大轮次限制超限强制退出工具调用参数错误schema 定义不清晰对比实际参数和 schema完善工具描述加参数校验检索结果不相关切块策略或嵌入模型问题人工检查检索结果调整切块粒度换嵌入模型生成内容重复prompt 缺少去重指令检查 prompt 模板加“不要重复”指令加后处理去重响应延迟高工具调用串行执行分析各步骤耗时并行化独立工具调用7.2 我踩过的几个印象深刻的坑第一个坑是工具描述写得太简略。刚开始做 Agent 的时候工具描述就写一句话比如“查询数据库”。结果 LLM 经常在不该调用的时候调用该调用的时候不调用。后来我把描述改成“当用户询问具体数据、统计信息、或需要从数据库获取信息时调用此工具。输入为 SQL 查询语句输出为查询结果。”改完之后工具调用的准确率明显提升。第二个坑是没有做超时控制。有一次 Agent 调用一个外部 API那个 API 挂了请求一直不返回Agent 就卡在那里。后来我给所有工具调用都加了超时默认 30 秒超时后返回错误信息让 LLM 决定下一步。第三个坑是日志记录不完整。出问题的时候想排查发现日志里只有最终结果没有中间过程。后来我在 Agent 循环的每个关键节点都加了日志包括输入、决策、工具调用、返回结果。日志量大了很多但排查效率提升非常明显。7.3 性能优化的几个实用技巧缓存是最有效的优化手段。LLM 调用结果、嵌入向量、检索结果这些都可以缓存。我通常用 Redis 做缓存设置合理的过期时间。实测下来缓存能减少 30% 到 50% 的重复计算。批处理也很重要。如果有多个独立的 LLM 调用不要一个一个串行执行打包成一批并行发送。很多 provider 支持批量请求能显著降低总延迟。模型分级是另一个思路。不是所有任务都需要用最大的模型。简单的分类、抽取任务用小模型复杂的推理、生成任务用大模型。我通常会在 Agent 里配置多个模型根据任务类型动态选择。prompt 精简经常被忽视。prompt 越长推理时间越长成本越高。定期审查 prompt删掉不必要的内容合并重复的指令能省不少资源。8. 一些个人体会做 Agent 和 LLM 相关的工作最大的感受是变化太快。今天好用的方案明天可能就有更好的替代。所以我的习惯是保持关注但不盲目追新。新技术出来先小范围试验证有效再推广到项目里。另一个体会是工程能力比模型能力更重要。同样的模型不同的工程实现效果可能差好几倍。工具调用的稳定性、错误处理、状态管理、日志记录这些看起来不起眼的东西往往决定了项目能不能真正落地。最后说一个实际的小技巧给 Agent 加一个“思考日志”。让 Agent 在每一步决策前先输出一段简短的思考过程记录为什么选择这个工具、为什么这样处理。这个日志不一定要展示给用户但排查问题的时候非常有用。我试过之后调试效率至少提升了一倍。