1. 从一次“答非所问”说起：多 Agent 知识库系统到底解决什么问题
企业知识库最容易翻车的地方，不是文档没上传，而是用户问一句“我们售后换货的时效和运费谁承担”，系统只把《售后服务制度》里一段无关的条款贴出来。传统固定流程 RAG 的做法是：把问题向量化，去 Milvus 里捞 Top-K 片段，拼进 Prompt 让模型回答。问题在于，它永远只有一条检索路径，遇到需要跨文档、跨主题、需要多步推理的问题就露馅。
多 Agent 知识库系统（Multi-Agent Knowledge Base）要解决的就是这件事：让系统先判断“这个问题该怎么查”，再决定用哪几条检索路径，最后把结果交给不同角色的 Agent 分工处理。它和普通 RAG 的区别，类似“一个实习生查一次资料就回答”和“一个调研小组先拆题、再分头查、再写报告、再互相挑错”。
Agentic RAG 是这套系统的检索内核。它不再是“一次向量召回”，而是 Agent 驱动动态检索：向量检索、关键词检索、BM25、Rerank 重排、联网搜索、长期记忆召回多路混合，根据问题类型智能匹配检索路径。Multi-Agent 协作则是业务管线：Planner 任务规划师把复杂问题拆成 3-5 个可并行调研的子主题，Researcher 调研员分头多源检索，Writer 撰写员整合成带引用标记的结构化 Markdown 报告，Critic 评审员从事实、完整度、引用维度校验打分，不合格自动触发重写。
这套东西适合谁？我梳理下来是三类人：一是想研究企业级 Multi-Agent + RAG 工程落地的开发者，二是准备基于源码二次开发搭 AI 知识产品的团队，三是正在准备大模型岗位面试、需要拿一个完整项目讲清楚“我懂 Agentic RAG 和 Multi-Agent 协作”的人。本文按源码级拆解的思路，给出可复制的目录结构、关键配置片段和本地启动验证步骤，你可以对照源码理解工程实现路径。
2. 源码目录结构与模块划分：多 Agent 知识库系统怎么组织代码
拿到一套企业级多 Agent 知识库系统源码，第一件事不是急着跑起来，而是先看目录结构，搞清楚模块边界。我按后端 Spring Boot + Spring AI、前端 Vue3 + TypeScript 的典型组织方式，把核心模块拆给你看。这套结构对应的是“知识库管理 + Agentic RAG 检索 + Multi-Agent 协作 + MCP 扩展”四条主线。
后端目录大致长这样：
backend/ ├── src/main/java/com/mindcrew/ │ ├── common/ # 通用返回、异常、常量、工具 │ ├── config/ # Spring AI、Milvus、Redis、SSE 配置 │ ├── auth/ # 登录注册、JWT、分级权限 │ ├── kb/ # 知识库全生命周期管理 │ │ ├── controller/ # 文档上传、解析、切片、向量化接口 │ │ ├── service/ # 解析器、切片器、Embedding 服务 │ │ └── mapper/ # MySQL 文档元数据 │ ├── rag/ # Agentic RAG 检索内核 │ │ ├── retriever/ # 向量、BM25、关键词、联网、记忆召回 │ │ ├── rerank/ # Rerank 重排 │ │ └── router/ # 检索路径动态路由 │ ├── agent/ # Multi-Agent 协作引擎 │ │ ├── planner/ # Planner 任务规划师 │ │ ├── researcher/ # Researcher 调研员 │ │ ├── writer/ # Writer 撰写员 │ │ ├── critic/ # Critic 评审员 │ │ └── graph/ # Agent 协作通信图谱、推理回放 │ ├── memory/ # 用户长期记忆模块 │ ├── mcp/ # MCP 第三方工具接入管控 │ └── sse/ # SSE 流式输出与实时事件推送 └── src/main/resources/ ├── application.yml ├── prompts/ # 各 Agent 的 Prompt 模板 └── db/init.sql # MySQL 初始化脚本前端目录：
frontend/ ├── src/ │ ├── api/ # 后端接口封装 │ ├── views/ │ │ ├── chat/ # 定向知识库智能问答 │ │ ├── research/ # 四 Agent 深度调研 │ │ ├── replay/ # Agent 推理步骤回放 │ │ ├── graph/ # Agent 协作关系可视化图谱 │ │ └── config/ # AI 参数配置中心、模型切换 │ ├── store/ # Pinia 状态管理 │ └── components/ # 溯源引用、工具调用记录组件模块划分背后是数据流转逻辑：文档上传后走kb模块完成解析、切片、向量化、索引构建，落到 Milvus 和 MySQL；用户提问进入rag模块，router根据问题类型决定走哪几条召回路径，多路结果经rerank重排后交给agent模块；如果是简单问答，直接流式返回；如果是复杂调研，Planner 拆题、Researcher 并行检索、Writer 撰写、Critic 评审，全程通过sse推送进度，graph记录协作关系，memory留存用户偏好。
这里有个容易忽略的点：Agentic RAG 的“动态”体现在router上。传统 RAG 是写死的retrieve -> prompt -> llm，而这套系统里，router 会先做问题预处理，适配复杂提问、口语化表述与多轮上下文连续追问，再决定检索策略。比如“帮我对比一下 A 产品和 B 产品的售后政策差异”这种问题，router 会识别出需要跨文档对比，触发多路召回而不是单次向量检索。
3. 可复制配置片段：Spring AI + Milvus + 四 Agent 参数怎么配
这一节给你可以直接抄的配置。先看application.yml的核心片段，路径与源码保持一致：
spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.3 vectorstore: milvus: client: host: 127.0.0.1 port: 19530 database-name: mindcrew collection-name: kb_chunks embedding-dimension: 1536 data: redis: host: 127.0.0.1 port: 6379 database: 0 mindcrew: rag: top-k: 8 rerank-top-n: 4 bm25-weight: 0.4 vector-weight: 0.6 enable-web-search: true enable-memory-recall: true agent: planner: max-subtopics: 5 model: qwen-plus researcher: parallel: true max-rounds: 3 writer: citation-required: true output-format: markdown critic: pass-score: 80 max-rewrite: 2 mcp: enabled: true server-port: 8090如果你用的是 OpenAI 兼容协议接入，把spring.ai.dashscope换成对应的 base-url 和 key 即可。这里我实测下来，把top-k设成 8、rerank-top-n设成 4 是个比较稳的平衡点，召回够全，重排后进 Prompt 的片段又不会太长导致模型跑偏。
四 Agent 的 Prompt 模板放在resources/prompts/下，Planner 的核心逻辑是拆题，配置片段：
你是任务规划师。请将用户问题拆解为 3-5 个可并行调研的子主题。 要求： 1. 每个子主题独立可检索，避免重叠； 2. 输出 JSON 数组，字段为 topic 和 query； 3. 若问题简单无需拆分，返回单元素数组。 用户问题：{{question}}Critic 的评审配置：
你是质量评审员。请从事实准确性、内容完整度、引用规范性三个维度打分（各 100 分）。 总分低于 {{passScore}} 时，指出具体问题并触发重写。 待评审报告：{{report}}MCP 接入配置，让知识库作为标准化知识工具对接第三方自研 Agent：
{ "mcpServers": { "mindcrew-kb": { "url": "http://127.0.0.1:8090/mcp", "tools": ["kb_search", "kb_ask", "research_report"] } } }这里要提醒一句：MCP 接入的是知识库检索能力，不要把它直连生产数据库。源码里mcp模块做了工具接入管控，只暴露检索和问答接口，这是企业合规的基本要求。
4. 本地启动与验证：从零跑通一次四 Agent 调研
配置写完，接下来是启动验证。按这个顺序来，能少踩很多坑。
第一步，起依赖服务。Milvus、MySQL、Redis 用 Docker 起最省事：
docker run -d --name milvus -p 19530:19530 -p 9091:9091 milvusdb/milvus:latest docker run -d --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root mysql:8.0 docker run -d --name redis -p 6379:6379 redis:7第二步，初始化数据库，执行db/init.sql，建表并插入默认管理员账号。
第三步，配置环境变量并启动后端：
export DASHSCOPE_API_KEY=你的key cd backend mvn spring-boot:run看到Started MindCrewApplication就说明后端起来了。前端：
cd frontend npm install npm run dev第四步，验证 Agentic RAG 检索。登录后上传一份 PDF 产品手册，等解析、切片、向量化完成，然后在问答框问一个需要跨段落的问题。观察后端日志，你应该能看到多路召回的执行记录：
[Router] question type = cross-doc, strategy = vector+bm25+rerank [Retriever] vector hit = 12, bm25 hit = 9 [Rerank] top-n = 4, scores = [0.91, 0.87, 0.83, 0.79] [SSE] push event = retrieval_done第五步，验证四 Agent 协作。切到深度调研模式，问一个复杂问题，比如“对比我们和竞品在售后政策上的差异并给出改进建议”。你会看到 SSE 实时推送各 Agent 进度：Planner 先输出 3-5 个子主题，Researcher 并行检索，Writer 生成带引用标记的 Markdown 报告，Critic 打分。如果 Critic 打分低于 80，会自动触发重写，日志里能看到[Critic] score = 72, trigger rewrite。
第六步，验证推理回放和协作图谱。调研完成后，进入回放页面，可以分步查看各 Agent 的出入参、耗时与运行状态；协作图谱会可视化展示 Planner、Researcher、Writer、Critic 之间的通信关系。这一步是企业合规核验的关键，问答结果全链路可追溯，附带资料来源引用、工具调用日志、完整推理链路、自检及评审得分。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth 怎么解
跑这套系统的过程中，我踩过的坑主要集中在四类报错上，逐个说。
第一类，401 Unauthorized。多数是 API Key 没配或配错。检查application.yml里的api-key是否读到了环境变量，或者前端配置中心里模型 Key 是否填对。如果是 MCP 接入报 401，检查mcp模块的鉴权配置，源码里默认走内部 Token 校验。
第二类，local proxy failed。这个通常出现在模型请求走本地代理配置时。检查application.yml里有没有残留的 proxy 配置，或者环境变量里有没有影响请求的代理设置。企业内网环境下，确认 Milvus、MySQL、Redis 的 host 和 port 能通，telnet 127.0.0.1 19530试一下。
第三类，reading choices相关报错。这是模型返回结构解析失败，常见于流式响应里 choices 字段为空。检查sse模块的响应解析逻辑，确认模型返回格式和解析代码匹配。如果是 Qwen 模型，注意qwen-plus和qwen-turbo的流式返回结构略有差异，源码里做了兼容，但如果你换了自定义模型，需要对照调整。
第四类，OAuth报错。出现在 MCP 第三方工具接入时，检查 OAuth 回调地址和 client 配置。源码里mcp模块的 OAuth 流程是标准实现，确认server-port和回调路径一致即可。
这里补一个三件套检查清单，凡是接入类问题，先核对这三项：Base URL、Key、Model ID。Base URL 指向模型服务地址，Key 是鉴权凭证，Model ID 要和实际调用的模型名一致。这三项对不上，报错基本跑不出上面四类。
6. 从源码到落地：多 Agent 知识库系统的二次开发路径
把这套源码跑通之后，真正的价值在于二次开发。我梳理几条落地路径给你参考。
第一条，替换模型。源码里默认用通义千问 Qwen，但模型切换是配置化的，你可以在配置中心自定义添加模型。只要符合 OpenAI 兼容协议，改 Base URL、Key、Model ID 三件套就能切。我试过把 Writer 换成更强的模型、Researcher 换成更快的模型，成本和效果能分开调。
第二条，扩展检索路径。Agentic RAG 的 router 是可插拔的，你可以在rag/retriever/下新增召回器，比如接入企业内部的 Elasticsearch 或图数据库，然后在 router 里注册新的检索策略。多路混合召回机制的好处就在这里，加一路不影响其他路。
第三条，定制 Agent 角色。四 Agent 协作引擎的 Prompt 模板都在resources/prompts/下，你可以按行业改。比如法务场景，Critic 的评审维度可以加上“法条引用准确性”；医疗场景，Researcher 的检索源可以限定在权威医学库。
第四条，MCP 对接业务流。知识库作为标准化知识工具，通过 MCP 协议对接第三方自研 Agent 和自动化业务流程。比如把kb_ask工具接到客服工单系统，工单创建时自动检索知识库给出建议回复。
第五条，私有化部署。整套系统支持私有化，Milvus、MySQL、Redis 都可以内网部署，模型可以走私有化推理服务。企业 AI 知识中台的落地，合规和可控是前提。
如果你在接入模型或配置 MCP 时遇到问题，可以对照接入文档排查；想先验证模型对话效果，可以直接在模型对话页面试；如果是长期做编码和 Agent 开发，Coding Plan 会更合适。源码拆解到这里，剩下的就是你自己动手跑一遍，把每个模块的日志打出来看，理解数据怎么在 Agentic RAG 和 Multi-Agent 之间流转。
