Skip to content

Agentic RAG 改造执行计划

本文档是 DocMind 向《企业技术文档 Agent 最佳实践》对齐的多 Phase 执行计划。每个 Phase 在独立会话窗口中完成。会话开始前先读本文档定位当前进度。


进度跟踪

Phase状态完成日期Commit Hash
Phase 1 - 基础铺垫✅ 完成2026-05-05e4803908
Phase 2 - Agentic 核心改造✅ 完成2026-05-05eb8b6ff9
Phase 3 - 检索增强✅ 完成2026-05-058c55bddc
Phase 4 - 用户体验收尾✅ 完成2026-05-05126c8023
Phase 5 - 范畴判定与检索置信度评估✅ 完成2026-05-07829a2e78
Phase 6 - 路由精简 + Langfuse OTel + 前端时间线✅ 完成2026-05-093bedf29f
Step 11 - 评测对照⏳ 待开始--

每完成一个 Step,把状态从 ⏳ 改为 ✅;每完成一个 Phase,记录日期与 commit。


差距对比总览

高级 RAG 维度(来源:最佳实践第三章查询流程)

最佳实践要求DocMind 现状差距
Top-50~100 候选 → 重排到 Top-5~10✅ Top-50 候选 → 重排 Top-8🔴 ✅ Phase 1
HyDE 假设文档生成(+20-35% 模糊查询)✅ HyDEGenerator(specificity=FUZZY 自动触发)🔴 ✅ Phase 3
Parent Document Retrieval(小块匹配 / 大块生成)✅ 400 字子块 + 1500 字父块🔴 ✅ Phase 3
MMR 多样性保证✅ MMRDiversifier λ=0.7🟡 ✅ Phase 1
同义词 / 术语扩展无显式扩展🟡 中
丰富元数据(version/tags/effective_date/access_level)✅ tags/docVersion/effectiveDate/sourceFileName🟡 ✅ Phase 1
自省失败 → 重检索(扩大范围/换策略)✅ ObservationEvaluator 5 种降级动作🟡 ✅ Phase 2
输出置信度标注(高/中/低)✅ 三级置信度徽章 + SSE confidence_warning🟢 ✅ Phase 4
推荐进一步阅读✅ RecommendationGenerator🟢 ✅ Phase 4

Agentic RAG 维度(来源:最佳实践 1.3 节)

最佳实践要求DocMind 现状差距
Supervisor-Worker 多 Agent 拓扑✅ SupervisorAgent + 4 Worker🔴 ✅ Phase 2
Plan-and-Execute(先规划后执行)✅ PlanGenerator + PlanExecutor🔴 ✅ Phase 2
迭代式 ReAct(Thought→Action→Observation 循环)✅ IterationDecider + ObservationEvaluator🔴 ✅ Phase 2
Agent 状态机(已尝试策略 / 证据累积)✅ AgentState + Evidence + triedStrategies🟡 ✅ Phase 2
动态重规划✅ 5 种降级动作 + CRAG Web 补偿🟡 ✅ Phase 2+5
专业化 Worker✅ 4 Worker(Retrieval/Web/Memory/Analysis)🟡 ✅ Phase 2

Phase 1:基础铺垫

目标:先把检索质量打扎实,让后续 Agentic 改造的每个 Worker 都基于可靠输出运作。 风险:低;改动局部。

Step 1:扩大检索候选池 Top-20 → Top-50

  • 修改文件
    • src/main/java/com/simon/DocMind/service/rag/VectorRetriever.java — DEFAULT_TOP_K 改 50
    • src/main/java/com/simon/DocMind/service/rag/BM25Retriever.java — DEFAULT_TOP_K 改 50
    • src/main/java/com/simon/DocMind/config/AiConfigHolder — 增加 retrieve_top_k_candidate=50rerank_top_k_final=8
    • docs/docmind.sqlsys_ai_config 增加默认值
    • src/main/java/com/simon/DocMind/service/rag/CrossEncoderReranker.java — 重排输出读 rerank_top_k_final
  • 依赖:无
  • 验证:跑现有 query,对比改动前后召回 chunk 数与最终引用质量
  • 文档同步03-检索与排序链路.md04-优化迭代记录.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.7mmr_enabled=true
  • 算法MMR = λ * relevance(q,d) - (1-λ) * max sim(d, selected);相似度可用 chunk embedding cosine 或 Jaccard
  • 依赖:Step 1
  • 验证:构造 Top-K 全来自同一文档的查询,验证 MMR 后能拉入其他文档
  • 文档同步03-检索与排序链路.md04-优化迭代记录.md11-面试高频质疑应答.md

Step 3:丰富 Chunk 元数据

  • 修改文件
    • entity/KbChunk.java — 增加 tags(JSON 数组)、docVersioneffectiveDatesourceFileName
    • docs/docmind.sqlkb_chunk 表 ALTER 增加列;提供迁移 SQL
    • src/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-检索与排序链路.md04-优化迭代记录.md

Phase 2:Agentic RAG 核心改造

目标:把单 Agent 改造为 Supervisor-Worker 多 Agent 拓扑,引入迭代决策与动态规划。 风险:高;架构级改动;建议每个 Step 单独 commit。

Step 4:Supervisor-Worker 拓扑骨架

  • 新增包agent/supervisor/agent/worker/
  • 新增文件
    • agent/supervisor/SupervisorAgent.java
    • agent/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-优化迭代记录.md07-项目深度扩展方向.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核心设计.md04-优化迭代记录.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核心设计.md04-优化迭代记录.md11-面试高频质疑应答.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核心设计.md04-优化迭代记录.md08-RAG系统痛点分析与优化路径.md

Phase 3:检索增强

目标:在新架构上加 HyDE 与 Parent Document Retrieval。 风险:中;都在 RetrievalWorker 内部,不影响外部架构。

Step 8:HyDE 假设文档生成

  • 新增service/rag/HyDEGenerator.javaprompts/hyde_generation.txt
  • 修改
    • RetrievalWorker.java — specificity == FUZZY 时先调 HyDE 生成假设答案,再用其 embedding 检索
    • AiConfigHolder — 增加 hyde_enabled=truehyde_model=qwen-turbo
  • 依赖:Step 4
  • 验证:模糊查询走 HyDE,日志可见生成的假设文档
  • 文档同步03-检索与排序链路.md04-优化迭代记录.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-检索与排序链路.md04-优化迭代记录.md

Phase 4:用户体验收尾

Step 10:输出置信度标注 + 推荐阅读

  • 修改
    • controller/DocMindChatController.javadone SSE 事件增加 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-工程化实践.md04-优化迭代记录.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 — 调小模型给出范畴决策,输出 JSON
    • prompts/scope_routing.txt — 提示词,含 8 个边界示例
  • 修改
    • agent/DocMindAgent.java — 紧急词检查之后、缓存查询之前插入 decideScope();新增 handleConversationOnlyhandleChitchathandleRefuse 三个短路方法。元对话路径完全不调用任何 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核心设计.md04-优化迭代记录.md11-面试高频质疑应答.md13-简历素材与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 metadata
    • agent/DocMindAgent.java — 从 metadata 提取 grader 结果,发 SSE grader 事件,LOW 档让现有 fallback 路径接管
  • 评估策略(避免每条查询都额外调一次模型):
    • 快路径:rerank 顶分 ≥ 0.65 直接判 HIGH,≤ 0.25 直接判 LOW,无需仲裁
    • 灰区四种模式:
      • cross_encoder(默认)— 把 top-3 切片拼接成一段上下文,让 reranker 对 (问题, 上下文) 这一对单独打分。一次 reranker 调用 ≈ 50ms
      • llm — 调小模型仲裁(保留为对比基线)
      • heuristic — 用分数分布规则判定(顶分与次分的差、前三平均分),零额外调用
      • disabled — 直接判 AMBIGUOUS
  • 配置grader.high_threshold / grader.low_threshold / grader.arbitration_mode
  • 依赖:Step 4(Worker 接口)
  • 验证:单元测试 RetrievalGraderTest(12 条用例覆盖四种模式 + 异常降级 + 旧配置兼容)
  • 文档同步02-Agentic-RAG核心设计.md03-检索与排序链路.md04-优化迭代记录.md

Step 14:自纠错增加切题度检查

原 SelfReflection 只检查事实一致性、完整性、来源匹配、表达质量,无法识别"检索到的内容跟问题完全不是一个主题"。Step 13 的 LOW 档可以兜住一部分,但漏判时仍可能进入生成。在反思阶段加最后一道闸。

  • 修改
    • agent/SelfReflection.javaReflectionResult record 加 topicMismatch + topicMismatchReason 两个字段;反思提示词追加切题度检查项
    • agent/DocMindAgent.java — 反思命中跑题时跳过重写直接走 fallback(重写救不回主题不对的引用,反而浪费一次模型调用)
  • 配置reflection.topic_check_enabled
  • 依赖:Step 12 / 13
  • 验证:手动触发场景——查询主题与所选知识库内容不相关,预期反思日志 topicMismatch=true,前端显示低置信度警告
  • 文档同步02-Agentic-RAG核心设计.md04-优化迭代记录.md

Step 15:合并模式与前端可视化

上面三步先按"独立组件、独立调用"实现,便于单独调试。可观测、可证伪后再做两个工程优化。

  • 优化 1:把范畴判定合并进 QueryUnderstanding 一次模型调用
    • 把 scope 字段加到 QueryClassificationquery_understanding.txt 提示词
    • 合并模式开启时(scope.merge_with_understanding=true,默认开),decideScope 直接调 QueryUnderstanding 拿到 scope + 改写 + 分类,结果缓存到 AgentState.cachedUnderstandingrunReActLoop 复用
    • 知识查询路径整条流程只调一次路由模型(原本 2 次:ScopeRouter + QueryUnderstanding),节省 ~250ms
    • 关闭合并时回到独立 ScopeRouter(便于排错)
  • 优化 2:灰区仲裁默认走 Cross-Encoder 而不是模型生成
    • DashScope gte-rerank 单对调用 ≈ 50ms,是模型生成调用的 1/5 时延
    • 灰区命中率 ~10%,整体省 ~75% 的灰区仲裁成本
  • 优化 3:前端展示范畴和检索置信度
    • ChatView.vue 监听 scopegrader SSE 事件
    • 气泡顶部新增两枚徽章:「范畴:元对话/闲聊/知识查询/任务执行/越界」+「检索:高/中/低」
    • 鼠标悬停展示置信度数字、判定来源(规则/模型)、判定理由
    • 推理过程列表加 scope / grader 两类步骤
  • 新增单元测试
    • MetaIntentDetectorTest(11 用例)
    • RetrievalGraderTest(12 用例覆盖四种仲裁模式 + 异常降级 + 旧配置兼容)
  • 文档同步02-Agentic-RAG核心设计.md05-工程化实践.md13-简历素材与STAR故事.md

Phase 5 调研依据

实施前调研了 12 个生产级框架/产品 + 3 篇核心论文,结论汇总:

来源关键做法
LangGraph Adaptive RAG 教程用结构化输出做条件路由,检索后再加一道 grade_documents
AWS Bedrock Agents6 个内置提示词模板,其中 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.javagetBool配置读取
config/AiConfigInitializer.java增量插入 9 条配置启动期初始化
docs/docmind.sql9 条 INSERT 兜底数据库基线
DocMind-frontend/src/views/chat/ChatView.vueSSE 监听 + 徽章 + 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 消耗

提交粒度建议

Stepcommit 数
Step 1, 2各 1
Step 32(schema + 代码)
Step 43-4(接口 + Worker 迁移 + Supervisor)
Step 5, 6, 7各 1
Step 8, 9各 1-2(Step 9 含 schema)
Step 102(后端 + 前端)

面试文档同步对照表

优化项主要更新文档
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 后更新进度跟踪表,并按"面试文档同步对照表"更新对应面试文档。