外观
Agentic RAG 改造执行计划
本文档是 DocMind 向《企业技术文档 Agent 最佳实践》对齐的多 Phase 执行计划。每个 Phase 在独立会话窗口中完成。会话开始前先读本文档定位当前进度。
进度跟踪
| Phase | 状态 | 完成日期 | Commit Hash |
|---|---|---|---|
| Phase 1 - 基础铺垫 | ✅ 完成 | 2026-05-05 | e4803908 |
| Phase 2 - Agentic 核心改造 | ✅ 完成 | 2026-05-05 | eb8b6ff9 |
| Phase 3 - 检索增强 | ✅ 完成 | 2026-05-05 | 8c55bddc |
| Phase 4 - 用户体验收尾 | ✅ 完成 | 2026-05-05 | 126c8023 |
| Phase 5 - 范畴判定与检索置信度评估 | ✅ 完成 | 2026-05-07 | 829a2e78 |
| Phase 6 - 路由精简 + Langfuse OTel + 前端时间线 | ✅ 完成 | 2026-05-09 | 3bedf29f |
| Step 11 - 评测对照 | ⏳ 待开始 | - | - |
每完成一个 Step,把状态从 ⏳ 改为 ✅;每完成一个 Phase,记录日期与 commit。
差距对比总览
高级 RAG 维度(来源:最佳实践第三章查询流程)
| 最佳实践要求 | DocMind 现状 | 差距 |
|---|---|---|
| Top-50~100 候选 → 重排到 Top-5~10 | ✅ Top-50 候选 → 重排 Top-8 | |
| HyDE 假设文档生成(+20-35% 模糊查询) | ✅ HyDEGenerator(specificity=FUZZY 自动触发) | |
| Parent Document Retrieval(小块匹配 / 大块生成) | ✅ 400 字子块 + 1500 字父块 | |
| MMR 多样性保证 | ✅ MMRDiversifier λ=0.7 | |
| 同义词 / 术语扩展 | 无显式扩展 | 🟡 中 |
| 丰富元数据(version/tags/effective_date/access_level) | ✅ tags/docVersion/effectiveDate/sourceFileName | |
| 自省失败 → 重检索(扩大范围/换策略) | ✅ ObservationEvaluator 5 种降级动作 | |
| 输出置信度标注(高/中/低) | ✅ 三级置信度徽章 + SSE confidence_warning | |
| 推荐进一步阅读 | ✅ RecommendationGenerator |
Agentic RAG 维度(来源:最佳实践 1.3 节)
| 最佳实践要求 | DocMind 现状 | 差距 |
|---|---|---|
| Supervisor-Worker 多 Agent 拓扑 | ✅ SupervisorAgent + 4 Worker | |
| Plan-and-Execute(先规划后执行) | ✅ PlanGenerator + PlanExecutor | |
| 迭代式 ReAct(Thought→Action→Observation 循环) | ✅ IterationDecider + ObservationEvaluator | |
| Agent 状态机(已尝试策略 / 证据累积) | ✅ AgentState + Evidence + triedStrategies | |
| 动态重规划 | ✅ 5 种降级动作 + CRAG Web 补偿 | |
| 专业化 Worker | ✅ 4 Worker(Retrieval/Web/Memory/Analysis) |
Phase 1:基础铺垫
目标:先把检索质量打扎实,让后续 Agentic 改造的每个 Worker 都基于可靠输出运作。 风险:低;改动局部。
Step 1:扩大检索候选池 Top-20 → Top-50
- 修改文件:
src/main/java/com/simon/DocMind/service/rag/VectorRetriever.java— DEFAULT_TOP_K 改 50src/main/java/com/simon/DocMind/service/rag/BM25Retriever.java— DEFAULT_TOP_K 改 50src/main/java/com/simon/DocMind/config/AiConfigHolder— 增加retrieve_top_k_candidate=50、rerank_top_k_final=8docs/docmind.sql—sys_ai_config增加默认值src/main/java/com/simon/DocMind/service/rag/CrossEncoderReranker.java— 重排输出读rerank_top_k_final
- 依赖:无
- 验证:跑现有 query,对比改动前后召回 chunk 数与最终引用质量
- 文档同步:
03-检索与排序链路.md、04-优化迭代记录.md
Step 2:MMR 多样性重排
- 新增文件:
src/main/java/com/simon/DocMind/service/rag/MMRDiversifier.java - 修改文件:
src/main/java/com/simon/DocMind/agent/DocMindAgent.java— 在 CrossEncoderReranker 之后调用 MMRDiversifier- AiConfigHolder — 增加
mmr_lambda=0.7、mmr_enabled=true
- 算法:
MMR = λ * relevance(q,d) - (1-λ) * max sim(d, selected);相似度可用 chunk embedding cosine 或 Jaccard - 依赖:Step 1
- 验证:构造 Top-K 全来自同一文档的查询,验证 MMR 后能拉入其他文档
- 文档同步:
03-检索与排序链路.md、04-优化迭代记录.md、11-面试高频质疑应答.md
Step 3:丰富 Chunk 元数据
- 修改文件:
entity/KbChunk.java— 增加tags(JSON 数组)、docVersion、effectiveDate、sourceFileNamedocs/docmind.sql—kb_chunk表 ALTER 增加列;提供迁移 SQLsrc/main/java/com/simon/DocMind/service/knowledge/TextChunker.java— 元数据生成填充新字段- Milvus schema 增加
tags(VARCHAR) 用于过滤 VectorRetriever.java— 支持 tags 过滤表达式src/main/java/com/simon/DocMind/service/rag/PromptAssembler.java— 引用注入新元数据
- 新增:tags 自动提取小工具(基于章节标题 + 关键词抽取)
- 依赖:建议 Step 1/2 后做
- 风险:DB schema 变更需迁移脚本,可能需重建部分历史索引
- 验证:上传新文档,确认 tags、docVersion 入库且可被检索过滤
- 文档同步:
03-检索与排序链路.md、04-优化迭代记录.md
Phase 2:Agentic RAG 核心改造
目标:把单 Agent 改造为 Supervisor-Worker 多 Agent 拓扑,引入迭代决策与动态规划。 风险:高;架构级改动;建议每个 Step 单独 commit。
Step 4:Supervisor-Worker 拓扑骨架
- 新增包:
agent/supervisor/、agent/worker/ - 新增文件:
agent/supervisor/SupervisorAgent.javaagent/worker/Worker.java(接口:execute(WorkerRequest) → WorkerResult)agent/worker/RetrievalWorker.java(封装 vector + BM25 + RRF + 重排 + MMR)agent/worker/WebWorker.java(封装 WebSearchTool)agent/worker/MemoryWorker.java(封装 MemoryTool)agent/worker/AnalysisWorker.java(新:多文档对比/综合)agent/state/AgentState.java(共享状态)agent/state/Evidence.java(标准证据结构)
- 重构:DocMindAgent 内部链路拆解,原逻辑迁移到对应 Worker
- 保留:MCP 工具暴露不变;DocMindAgent 作为 SupervisorAgent 的薄壳保持外部签名
- 依赖:Step 1-3
- 验证:原 SSE 主链路功能不退化,所有现有测试通过
- ⚠️ 风险点:建议拆 3-4 个 commit(接口 → 各 Worker 迁移 → Supervisor 重构)
- 文档同步:
01-项目全景与架构设计.md(架构图替换)、02-Agentic-RAG核心设计.md(核心改写)、04-优化迭代记录.md、07-项目深度扩展方向.md(移除已实现项)
Step 5:迭代式 ReAct 循环 + AgentState
- 修改:
SupervisorAgent.java— 引入 max_iterations 循环(默认 3)AgentState.java— 跟踪 triedStrategies、accumulatedEvidence、confidenceTrajectory、remainingBudget
- 新增:
agent/supervisor/IterationDecider.java(决策"继续 / 换策略 / 终止") - 终止条件:confidence ≥ 0.85 OR iterations ≥ max OR 连续两轮 confidence 无提升
- 依赖:Step 4
- 验证:简单查询 1 轮终止;复杂查询 2-3 轮
- 文档同步:
02-Agentic-RAG核心设计.md、04-优化迭代记录.md
Step 6:Plan-and-Execute 模式
- 新增:
agent/supervisor/PlanGenerator.java(LLM 产出结构化 ExecutionPlan)agent/supervisor/ExecutionPlan.java(数据模型)agent/supervisor/PlanExecutor.java(按计划调度 Workers)prompts/plan_generation.txt
- 触发条件:query.complexity == COMPLEX 走 Plan-and-Execute;其他走 Step 5 的反应式 ReAct
- 依赖:Step 4 + Step 5
- 验证:复杂多跳查询能产出多步计划并按步骤执行
- 文档同步:
02-Agentic-RAG核心设计.md、04-优化迭代记录.md、11-面试高频质疑应答.md
Step 7:动态重规划与降级链(合并优化 5 / 11)
- 修改:
SupervisorAgent.java— 加入 ObservationEvaluator 调用IterationDecider.java— 升级决策逻辑agent/SelfReflection.java— 提供更结构化的 issues 给 ObservationEvaluator
- 新增:
agent/supervisor/ObservationEvaluator.java - 决策图:
- 召回为空 → 切到 WebWorker
- 召回分数 < threshold → 触发 HyDE 重写后重检索(先打桩,等 Step 8 实现)
- 多文档冲突信号 → 调用 AnalysisWorker
- 自省失败 → 重新规划(不只是重写答案)
- 依赖:Step 4-6
- 验证:构造空召回场景验证自动切 Web;构造低分场景验证降级链
- 文档同步:
02-Agentic-RAG核心设计.md、04-优化迭代记录.md、08-RAG系统痛点分析与优化路径.md
Phase 3:检索增强
目标:在新架构上加 HyDE 与 Parent Document Retrieval。 风险:中;都在 RetrievalWorker 内部,不影响外部架构。
Step 8:HyDE 假设文档生成
- 新增:
service/rag/HyDEGenerator.java、prompts/hyde_generation.txt - 修改:
RetrievalWorker.java— specificity == FUZZY 时先调 HyDE 生成假设答案,再用其 embedding 检索- AiConfigHolder — 增加
hyde_enabled=true、hyde_model=qwen-turbo
- 依赖:Step 4
- 验证:模糊查询走 HyDE,日志可见生成的假设文档
- 文档同步:
03-检索与排序链路.md、04-优化迭代记录.md
Step 9:Parent Document Retrieval
- 新增字段:
kb_chunk.parent_chunk_id - 修改:
TextChunker.java— 双层切块:父块 1500 字符(生成用)、子块 400 字符(检索用),子块记录 parent_id- Milvus schema — embedding 仅存子块;父块只存 MySQL
RetrievalWorker.java— 命中子块后查询父块返回到上下文
- 风险:需重建索引,提供后台任务
- 依赖:Step 4
- 验证:检索命中的 chunk 在 PromptAssembler 中显示为父块完整段落
- 文档同步:
03-检索与排序链路.md、04-优化迭代记录.md
Phase 4:用户体验收尾
Step 10:输出置信度标注 + 推荐阅读
- 修改:
controller/DocMindChatController.java—doneSSE 事件增加confidenceLevel(高/中/低)、recommendations数组SelfReflection.java— confidence 数值映射等级(≥0.8 高 / ≥0.6 中 / 其他 低)DocMind-frontend/src/views/chat/ChatView.vue— 渲染置信度徽章 + 推荐卡片
- 新增:
service/rag/RecommendationGenerator.java(基于 chunk tags/category 反查同主题文档) - 依赖:Step 3(用 tags)+ Step 7(用 confidence)
- 验证:前端能看到"置信度: 高"标识和"延伸阅读"卡片
- 文档同步:
05-工程化实践.md、04-优化迭代记录.md
Phase 5:范畴判定与检索置信度评估
触发原因:用户在某次对话中输入"总结上面的对话",系统把这句话的关键词拿去 Milvus 做向量检索,召回了 12 条与对话主题完全无关的切片,然后用这些无关内容生成回答,置信度 0% 仍然推送给前端。这是一个真实出现过的 bug,根因是只有一层意图分类(factoid / procedural / comparison / opinion / chitchat),五个取值都默认要去查知识库。
解决思路:在原有意图分类之上加一层"要不要查知识库"的判断;在检索完成后再加一道"查到的内容跟问题对不对得上"的检查。两道闸都做了降级路径,任何一道判错或调用失败都会回到原来的流程。
Step 12:顶层范畴判定(Tier-0 规则 + Tier-1 模型)
决定一条问题进入哪条处理路径。区分四种情况:要查知识库、要看历史对话、闲聊、超出范围。
- 新增:
agent/ScopeDecision.java— record,包含范畴、置信度、是否走规则、判定理由agent/MetaIntentDetector.java— 纯正则识别高置信度的元对话指令("总结上面"、"翻译你刚才说的")和闲聊("你好"、"谢谢")agent/ScopeRouter.java— 调小模型给出范畴决策,输出 JSONprompts/scope_routing.txt— 提示词,含 8 个边界示例
- 修改:
agent/DocMindAgent.java— 紧急词检查之后、缓存查询之前插入decideScope();新增handleConversationOnly、handleChitchat、handleRefuse三个短路方法。元对话路径完全不调用任何 Worker、不查 Milvus、不查 BM25,仅基于历史对话回答agent/state/AgentState.java— 新增scopeDecision字段- 配置:
scope.fast_path_enabled/scope.llm_enabled/scope.history_limit
- 降级:规则路径异常 → 让模型路径兜;模型路径异常 → 默认按知识查询走原流程
- 依赖:无
- 验证:
- 单元测试
MetaIntentDetectorTest(11 条用例覆盖 META_CONVERSATION / CHITCHAT / 不命中) - 端到端:先正常问答建立历史,再问"总结上面的对话",预期 SSE 流出现
scope=META_CONVERSATION,没有retrieval/rerank事件
- 单元测试
- 文档同步:
02-Agentic-RAG核心设计.md、04-优化迭代记录.md、11-面试高频质疑应答.md、13-简历素材与STAR故事.md
Step 13:检索结果三档置信度评估
检索完成后给一道分。CRAG 论文(Yan et al. 2024)的做法是用一个独立的小模型评估检索质量,分三档触发不同后续动作。
- 新增:
service/rag/GradeResult.java— record(HIGH / AMBIGUOUS / LOW + topScore + avgScore + reason)service/rag/RetrievalGrader.java— 三档评估器
- 修改:
service/rag/RetrievedChunk.java— 加topicRelevance字段(评估时标注用)agent/worker/RetrievalWorker.java— Cross-Encoder 重排 + MMR + 父块展开之后调用retrievalGrader.grade(),结果写入 Evidence metadataagent/DocMindAgent.java— 从 metadata 提取 grader 结果,发 SSEgrader事件,LOW 档让现有 fallback 路径接管
- 评估策略(避免每条查询都额外调一次模型):
- 快路径:rerank 顶分 ≥ 0.65 直接判 HIGH,≤ 0.25 直接判 LOW,无需仲裁
- 灰区四种模式:
cross_encoder(默认)— 把 top-3 切片拼接成一段上下文,让 reranker 对 (问题, 上下文) 这一对单独打分。一次 reranker 调用 ≈ 50msllm— 调小模型仲裁(保留为对比基线)heuristic— 用分数分布规则判定(顶分与次分的差、前三平均分),零额外调用disabled— 直接判 AMBIGUOUS
- 配置:
grader.high_threshold/grader.low_threshold/grader.arbitration_mode - 依赖:Step 4(Worker 接口)
- 验证:单元测试
RetrievalGraderTest(12 条用例覆盖四种模式 + 异常降级 + 旧配置兼容) - 文档同步:
02-Agentic-RAG核心设计.md、03-检索与排序链路.md、04-优化迭代记录.md
Step 14:自纠错增加切题度检查
原 SelfReflection 只检查事实一致性、完整性、来源匹配、表达质量,无法识别"检索到的内容跟问题完全不是一个主题"。Step 13 的 LOW 档可以兜住一部分,但漏判时仍可能进入生成。在反思阶段加最后一道闸。
- 修改:
agent/SelfReflection.java—ReflectionResultrecord 加topicMismatch+topicMismatchReason两个字段;反思提示词追加切题度检查项agent/DocMindAgent.java— 反思命中跑题时跳过重写直接走 fallback(重写救不回主题不对的引用,反而浪费一次模型调用)
- 配置:
reflection.topic_check_enabled - 依赖:Step 12 / 13
- 验证:手动触发场景——查询主题与所选知识库内容不相关,预期反思日志
topicMismatch=true,前端显示低置信度警告 - 文档同步:
02-Agentic-RAG核心设计.md、04-优化迭代记录.md
Step 15:合并模式与前端可视化
上面三步先按"独立组件、独立调用"实现,便于单独调试。可观测、可证伪后再做两个工程优化。
- 优化 1:把范畴判定合并进 QueryUnderstanding 一次模型调用
- 把 scope 字段加到
QueryClassification和query_understanding.txt提示词 - 合并模式开启时(
scope.merge_with_understanding=true,默认开),decideScope直接调 QueryUnderstanding 拿到 scope + 改写 + 分类,结果缓存到AgentState.cachedUnderstanding,runReActLoop复用 - 知识查询路径整条流程只调一次路由模型(原本 2 次:ScopeRouter + QueryUnderstanding),节省 ~250ms
- 关闭合并时回到独立 ScopeRouter(便于排错)
- 把 scope 字段加到
- 优化 2:灰区仲裁默认走 Cross-Encoder 而不是模型生成
- DashScope
gte-rerank单对调用 ≈ 50ms,是模型生成调用的 1/5 时延 - 灰区命中率 ~10%,整体省 ~75% 的灰区仲裁成本
- DashScope
- 优化 3:前端展示范畴和检索置信度
ChatView.vue监听scope与graderSSE 事件- 气泡顶部新增两枚徽章:「范畴:元对话/闲聊/知识查询/任务执行/越界」+「检索:高/中/低」
- 鼠标悬停展示置信度数字、判定来源(规则/模型)、判定理由
- 推理过程列表加 scope / grader 两类步骤
- 新增单元测试:
MetaIntentDetectorTest(11 用例)RetrievalGraderTest(12 用例覆盖四种仲裁模式 + 异常降级 + 旧配置兼容)
- 文档同步:
02-Agentic-RAG核心设计.md、05-工程化实践.md、13-简历素材与STAR故事.md
Phase 5 调研依据
实施前调研了 12 个生产级框架/产品 + 3 篇核心论文,结论汇总:
| 来源 | 关键做法 |
|---|---|
| LangGraph Adaptive RAG 教程 | 用结构化输出做条件路由,检索后再加一道 grade_documents 闸 |
| AWS Bedrock Agents | 6 个内置提示词模板,其中 Pre-processing 和 Memory Summarization 是独立阶段 |
| Perplexity 工程博客 | 把后续追问先重写为独立查询;引用历史对话的请求在重写阶段就识别出来 |
| LinkedIn 工程博客 | 三段式:路由 → 检索 → 生成;路由用小模型,决定是否在范围内 |
| CRAG 论文(Yan 2024) | 检索后用独立评估器,分 Correct / Ambiguous / Incorrect 三档 |
| Self-RAG 论文(Asai 2023) | 在词表里加反思 token,让模型自己决定是否检索(需要微调,未采用) |
| Adaptive-RAG 论文(Jeong 2024) | 用 T5-Large 分类器决定零检索 / 单步 / 多步(外部分类器思路) |
| NeMo Guardrails | 输入栏、对话栏、检索栏、输出栏多层检查 |
被弃用的方案:
- 纯靠模型函数调用决定是否检索:LinkedIn、Airbnb v1→v2、Microsoft Semantic Kernel 都从这个路径迁出,原因是模型容易过度检索、识别不出元对话
- 用单一阈值硬切 HIGH / LOW:CRAG 专门留了 Ambiguous 一档应对评估器不准的场景
改动清单总览
| 文件 | 类型 | 作用 |
|---|---|---|
agent/ScopeDecision.java | 新增 record | 范畴判定结果 |
agent/MetaIntentDetector.java | 新增组件 | 规则路径 |
agent/ScopeRouter.java | 新增组件 | 模型路径 |
service/rag/RetrievalGrader.java | 新增组件 | 检索三档评估 |
service/rag/GradeResult.java | 新增 record | 评估结果 |
service/rag/RetrievedChunk.java | 加字段 | topicRelevance |
prompts/scope_routing.txt | 新增提示词 | 拆分模式用 |
prompts/query_understanding.txt | 增加 scope 字段 | 合并模式用 |
agent/DocMindAgent.java | 路由分发 + 三个短路方法 | 决策入口 |
agent/SelfReflection.java | 加切题度检查 | 反思阶段最后一道闸 |
agent/worker/RetrievalWorker.java | 调用 grader | 检索后评估 |
agent/state/AgentState.java | 加缓存字段 | scope + understanding |
config/AiConfigHolder.java | 加 getBool | 配置读取 |
config/AiConfigInitializer.java | 增量插入 9 条配置 | 启动期初始化 |
docs/docmind.sql | 9 条 INSERT 兜底 | 数据库基线 |
DocMind-frontend/src/views/chat/ChatView.vue | SSE 监听 + 徽章 + CSS | 前端可视化 |
| 单元测试 | 23 条新增 | MetaIntentDetectorTest 11 + RetrievalGraderTest 12 |
Step 11:评测对照(每个 Phase 完成后追加)
- 跑
09-评测体系建设.md中的评测脚本 - 把 Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 的指标变化记录到
10-评测结果与发现.md - 跟踪指标:Recall@5、回答正确率、平均延迟、Token 消耗
提交粒度建议
| Step | commit 数 |
|---|---|
| Step 1, 2 | 各 1 |
| Step 3 | 2(schema + 代码) |
| Step 4 | 3-4(接口 + Worker 迁移 + Supervisor) |
| Step 5, 6, 7 | 各 1 |
| Step 8, 9 | 各 1-2(Step 9 含 schema) |
| Step 10 | 2(后端 + 前端) |
面试文档同步对照表
| 优化项 | 主要更新文档 |
|---|---|
| Step 1/2/3(Phase 1) | 03-检索与排序链路.md、04-优化迭代记录.md |
| Step 4(Supervisor-Worker) | 01-项目全景.md、02-Agentic-RAG核心设计.md、04-优化迭代记录.md、07-项目深度扩展方向.md |
| Step 5/6/7(Agentic 核心) | 02-Agentic-RAG核心设计.md、07-项目深度扩展方向.md、04-优化迭代记录.md |
| Step 8/9(Phase 3) | 03-检索与排序链路.md、04-优化迭代记录.md |
| Step 10(Phase 4) | 05-工程化实践.md、04-优化迭代记录.md |
| Step 12-15(Phase 5) | 02-Agentic-RAG核心设计.md、04-优化迭代记录.md、11-面试高频质疑应答.md、13-简历素材与STAR故事.md、06-待优化清单.md |
| 全部 | 06-待优化清单.md(划除已完成)、11-面试高频质疑应答.md(补新质疑) |
每条 04 迭代记录格式:背景痛点 → 方案设计 → 实现细节 → 数据对比 → 面试话术。
新会话续作时的引导词
我要开始 Phase X,先读
interview-docs/12-Agentic-RAG改造执行计划.md定位当前进度,然后按 Step 顺序执行该 Phase 的任务。每完成一个 Step 后更新进度跟踪表,并按"面试文档同步对照表"更新对应面试文档。