DB-GPT Agentic RAG 对话原理从提问到带引用回答的 Agent 驱动检索全链路【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文以 DB-GPT 的 Agentic RAG 设计文档为主体完整拆解用户提问 → 带引用回答的端到端流程Agent 如何通过 ReAct 循环按需多轮检索、如何按场景裁剪工具集Knowledge-Agent vs Full-Agent、以及如何实现自动收集引用 后处理兜底标注的可溯源闭环。读完后你将能在产品与实现两个层面理解 DB-GPT 知识库对话的设计原则并能在 semantic_search_tool.py、react_final.py 等源码中定位到每一环节的真实实现。一、Agentic RAG vs 传统 RAG为什么单次检索不够用DB-GPT 知识库对话采用的不是一次检索定生死的传统 RAG而是由 ReAct Agent 驱动的多轮检索Agentic RAG。两种模式的对比如下传统 RAG (单次检索) ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 用户提问 │ → │ 一次检索 │ → │ 拼 Prompt │ → │ LLM 回答 │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ 检索一次 检索结果塞进 一次性生成 靠运气 context 缺点检索质量全靠一次相似度无法迭代修正无法多步查找 Agentic RAG (多轮检索) ← DB-GPT 采用 ┌──────────┐ ┌──────────────────────────────────────┐ ┌──────────┐ │ 用户提问 │ → │ ReAct Agent 循环 │ → │ 带引用的 │ └──────────┘ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ 最终回答 │ │ │ Thought│→ │ Action │→ │Observe │ │ └──────────┘ │ └────────┘ └────────┘ └────────┘ │ │ ↑ │ │ │ └───── 不满意再检索 ──┘ │ │ (可多轮按需调用不同工具) │ └──────────────────────────────────────┘ 优点按需迭代检索、可选多种工具、可溯源引用传统 RAG 的瓶颈检索质量完全依赖一次相似度计算的运气。如果 query 与目标 chunk 的向量距离恰好偏大或者问题的答案需要跨多个文档、多个片段拼装单次检索无法迭代修正也無法做先找目录、再读文件的多步查找。Agentic RAG 的改进检索变成 Agent 的一个可选动作。LLM 先思考Thought再决定调用哪个工具、传什么参数Action观察工具返回Observation判断信息是否足够——不够就换 query、换工具再检索。这正是 ReAct 范式的落地。从源码结构看该模式的入口在 agentic_data_api.py 中构建的 Agent 系统提示里其中明确向 LLM 声明了工具选择策略kb_grep: Search file contents by keyword (prefer for exact matches)semantic_search: Semantic search (use when kb_grep returns insufficient results)也就是说连先关键词、后语义的检索顺序都是由提示词层面的工具描述引导的而非硬编码流程。二、Agent 对话完整流程8 步下面以一次真实知识库对话为例展示从提问到带引用回答的完整链路用户提问: 提示词缓存设计哲学是啥 ▼ Step 1: Agent 思考 (Thought) 用户问缓存设计哲学我先去知识库语义搜一下 ▼ Step 2: 选择工具 (Action) 可用工具 (Knowledge-Agent 模式只含知识库工具): • kb_semantic_search 语义搜索 • kb_grep 关键词搜 • kb_cat 读文件 • kb_ls / kb_glob 列目录/找文件 • todowrite / terminate 任务管理/结束 Agent 选择: kb_semantic_search(query提示词缓存设计) ▼ Step 3: 执行 观察 (Observation) 工具返回 10 个 chunks每个带 score 和来源文件 Result 1 (score 0.67) [prompt cache.md] 设计代价对比表... Result 2 (score 0.66) [prompt cache.md] Hermes ephemeral 注入... ▼ Step 4: Agent 再思考 (Thought) 搜索结果丰富但对比表被截断我读一下完整文件 ▼ Step 5: 再选工具 (Action) → kb_cat(pathprompt cache.md) → Observation: 完整文件 315 行内容 ▼ Step 6: 收集引用 (Citation Collection) 每个工具返回的 chunk 被收集进 _cited_chunks 列表 去重 清洗 HTML 标签 → 得到干净的可溯源片段 ▼ Step 7: 终止并生成回答 (Terminate) Agent 判断信息足够 → 调用 terminate(result最终回答) 后端对回答做后处理: 1. _auto_annotate_citations: 把 [1][2] 角标插到引用处 2. _build_references_xml: 拼接 references 引用数据 ▼ Step 8: 前端渲染带引用的回答 Pi 每轮重建 system prompt[1] Hermes 冻结快照 ephemeral 注入[2][6] ↑ [1][2][3] 是蓝色角标, hover 显示对应 chunk 内容下面结合源码对关键步骤做纵深说明。Step 2-3知识库工具的真实实现Knowledge-Agent 模式下的每个kb_*工具都不是对 LLM 虚构的接口而是真实注册进 Agent 工具集的 Python 函数全部通过tool装饰器声明见 tools/init.pykb_semantic_search定义于 semantic_search_tool.py。签名为kb_semantic_search(knowledge_id, query, top_k5, score_threshold0.0)参数含义knowledge_id知识库空间的数字 ID 或空间名内部会先解析为实体再取数值 ID 发起检索请求top_k返回结果数默认 5score_threshold最小召回分数0-1默认 0.0。值得注意的是它的返回格式_format_chunk_resultssemantic_search_tool.py#L22-L37每条结果渲染为### Result N (score: 0.67) [file_path] chunk 正文并且累计超过 8000 字符即截断追加... N more results.。这个截断正是流程图中 Step 4 对比表被截断我读一下完整文件这一行为触发的直接原因——工具刻意只返回摘要级信息把是否需要读全文的决策权交给 Agent。kb_ls / kb_glob / kb_grep / kb_cat集中定义于 kb_file_tools.py。其中kb_ls(knowledge_id, path, offset0, limit200)kb_file_tools.py#L89-L95通过解析文档元数据中的file_path构造虚拟目录树输出形如src/\t(3 files)的目录文件列表kb_cat则按file_path反查文档 ID 后返回完整文件内容。这些工具让知识库在 Agent 眼中像一个文件系统从而支持先 ls 找文件、再 grep 定位、最后 cat 读全文的探索式检索。kb_codegraph_*代码图谱类工具定义于 codegraph_tools.py在需要时按需挂载到工具集见下文工具裁剪小节。Step 6-7引用的自动收集与后处理兜底文档强调引用自动收集不依赖 LLM 自觉标注。从源码结构看这条链路有两层实现Agentic 路径ReAct 终答接口react_final.py 中的引用组装器会对每轮工具调用执行assembler.observe(tool_name, args, observation)并内置_adapt_kb_cat、_adapt_kb_grep等适配器把kb_cat/kb_grep的原始文本输出转换为结构化引用。对应测试 test_react_final.py 中有test_kb_cat_becomes_a_structured_citation用例验证了一次 kb_cat 观察 → 一条结构化引用的契约。传统 KBQA 场景chat.py 中保存了检索片段chunks_with_score回答完成后调用_auto_annotate_citations与parse_source_view完成角标插入和referencesXML 拼接实现细节见第四节。后处理兜底第 4 条设计原则的核心是即使 LLM 完全没按提示词标注 [1][2]后端也能通过字符串匹配把角标补上。三、ReAct 循环机制Agent 的核心┌─────────────────┐ │ 用户提问 │ └────────┬────────┘ ▼ ┌─────────────────────────┐ │ Thought (LLM 推理) │ ← 分析当前状态,决定下一步 └────────────┬────────────┘ ▼ ┌─────────────────────────┐ │ Action (选工具参数) │ ← 从可用工具里选一个 └────────────┬────────────┘ ▼ ┌─────────────────────────┐ │ Observation (工具返回) │ ← 执行工具,拿结果 └────────────┬────────────┘ ▼ ┌────────┴────────┐ │ │ 信息足够? 还需要更多? ▼ │ ┌──────────┐ │ │ Terminate│ │ │ 生成回答 │ │ └──────────┘ │ │ yes → 回到 Thought (下一轮) (最多 N 轮, 防止死循环)关键点Agent 不是无脑检索一次而是根据 Observation 判断信息够不够不够就换工具/换 query 再搜。这个循环有三个工程约束终止条件Agent 通过terminate(result最终回答)显式结束循环回答内容即 terminate 的result参数而不是额外一轮生成轮数上限循环最多 N 轮防止 LLM 在再搜一次上陷入死循环这是所有 ReAct 实现的必要护栏工具白名单每轮 Action 只能从当前会话的工具集中选择工具集由会话模式决定见下节从机制上杜绝 Agent乱调 shell/sql。四、引用溯源链路可解释性的核心引用溯源分三个阶段工具执行 → 后端收集 → 前端展示工具执行 后端收集 前端展示 kb_semantic_search 返回 → _cited_chunks[0] { - [1] 蓝色角标 Result 1: Pi 每轮重建... content: Pi 每轮重建..., hover 显示: score: 0.67 recall_score: 0.67, Pi 每轮重建... 召回 0.67 kb_cat 返回 → _cited_chunks[1] { - [2] 蓝色角标 Hermes 冻结快照... content: Hermes 冻结..., recall_score: null, } 自动标注 → 回答正文里: → [1][2] 插在 _auto_annotate_citations Pi 每轮重建[1] 对应句子后 Hermes 冻结[2] 引用面板 → references XML - 查看回复引用 references[{ 点击弹出 Drawer name: prompt cache.md, 按文档分 Tab chunks: [{index:1,...}, 显示所有 chunk {index:2,...}]}]这条链路在源码中有两处可验证的实现4.1 自动标注算法_auto_annotate_citations传统 KBQA 场景chat.py#L132-L171给出了后处理兜底的完整算法将所有召回 chunk 按内容长度降序排序先匹配更长更具体的 chunk避免短 chunk 落在长 chunk 内部对每个长度 ≥ 10 字符的 chunk用滑动窗口在回答文本中寻找最长公共子串_longest_common_substring窗口在 80~10 字符之间从长到短扫描见 chat.py#L173-L191命中后在首次出现位置后插入[n]角标且若角标已存在则跳过避免重复标注。文档对此算法有一个重要说明第 5 条设计原则chunk 内容清洗去掉 HTML 标签后再匹配保证 LLM 干净文本和 chunk 能对上——因为 LLM 生成的是纯文本而 chunk 原文可能带 HTML 标签不清洗会导致公共子串匹配失败、角标插不进去。4.2 引用数据下发referencesXMLparse_source_viewchat.py#L249-L282把所有引用 chunk 按文档分组序列化为如下 XML 拼在回答末尾references titleReferences references[{name: aa.pdf, chunks: [{index: 1, id: 10, content: text, recall_score: 0.9}]}]/前端解析该 XML 后正文中的[n]渲染为蓝色角标hover 显示 chunk 内容与召回分侧边引用面板按文档分 Tab 展示全部 chunk。这就构成了文档所说的可溯源闭环每个角标 → 对应 chunk → 对应文档 → 可在引用面板查看原文。注意一个细节kb_semantic_search类工具返回的 chunk 带recall_score如 0.67而kb_cat读出的全文片段recall_score为 null——引用面板会如实区分召回证据与主动阅读证据这正是溯源粒度细于文档级引用的地方。五、工具模式Knowledge-Agent vs Full-AgentDB-GPT 按对话场景给 Agent 装配不同粒度的工具集知识库详情页对话 (knowledge-agent) 通用 Agent 对话 (react-agent) ┌─────────────────────────┐ ┌─────────────────────────────┐ │ 只含知识库工具: │ │ 全部工具: │ │ • kb_semantic_search │ │ • kb_* (知识库) │ │ • kb_grep / kb_cat │ │ • shell_interpreter (Shell) │ │ • kb_ls / kb_glob │ │ • sql_query (SQL) │ │ • kb_codegraph_* │ │ • html_interpreter (报表) │ │ • todowrite / terminate│ │ • code_interpreter (代码) │ └─────────────────────────┘ │ • execute_skill_script │ ↑ │ • todowrite / terminate │ 聚焦知识检索 └─────────────────────────────┘ 不引入无关工具噪音 ↑ 适合纯知识问答 能力全面,适合复杂任务 但工具多,易跑偏两种模式的设计取舍维度Knowledge-Agent知识库对话Full-Agent通用 Agent 对话工具范围仅kb_*系列 todowrite/terminate知识库 Shell SQL 代码解释器 报表 技能脚本典型场景纯知识问答、文档溯源复杂多步任务查数据→算→出报表风险特征工具少检索行为可预期工具多LLM 选择空间大容易跑偏从源码结构看工具裁剪发生在 Agent 装配阶段agentic_data_api.py 构建知识库型 Agent 时明确contains kb_semantic_search, kb_ls, kb_glob, kb_grep, kb_cat and optionally codegraph tools即代码图谱工具也是可选挂载而非默认全开。工具集越小LLM 的 Action 决策空间越小跑偏概率和 token 消耗越低——这是第 2 条设计原则工具按场景裁剪的工程动机。六、关键设计原则汇总原文档总结的 7 条原则逐条对照到实现后即是一个可落地的 checklistAgent 驱动检索不是一次检索定生死LLM 根据 Observation 决定是否再搜、换什么工具。工具描述本身参与引导策略use only when kb_grep returns insufficient results。工具按场景裁剪纯知识对话只给知识工具避免 Agent 乱调 shell/sqlKnowledge-Agent 白名单。引用自动收集每次工具返回的 chunk 都进引用列表Agentic 路径由 react_final 的 assembler 对observe结果做结构化适配不依赖 LLM 自觉标注。后处理兜底LLM 不按 prompt 标 [1][2] 时后端用最长公共子串匹配自动补角标_auto_annotate_citationsmin_len10 / max_len80 的启发式窗口。chunk 内容清洗去掉 HTML 标签后再匹配保证 LLM 干净文本和 chunk 能对上。引用数据随回答下发referencesXML 拼在回答末尾前端解析后渲染角标 引用面板。可溯源闭环每个角标 → 对应 chunk → 对应文档 → 可在引用面板查看原文。七、延伸阅读与源码索引围绕本文主题仓库内可进一步深入的入口设计文档英文原版agentic_rag_principles.mdRAG 模块总览含 MS-RAG 与 agentic 循环的关系rag.mdRAG 概念入门何时用 Agentic RAGrag.md知识库工具实现semantic_search_tool.py、kb_file_tools.py、codegraph_tools.pyReAct 终答与引用组装react_final.py 及其测试 test_react_final.py传统 KBQA 场景的标注与引用实现chat.py适用前提说明本文基于当前仓库版本的实现。文档中的_cited_chunks、_build_references_xml是对 Agentic 路径引用收集机制的描述性命名其对应实现分散在 react_final 的引用组装器与传统 KBQA 场景的_auto_annotate_citations/parse_source_view中具体字段名以你所查看的源码版本为准。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考