Baike.dev
Log in
Back to tool/Back to issues
#5391·deer-flow

RFC: 内置本地知识库（Harness RAG）

Author: chenzhiya77Created Sep 13, 2026Updated Sep 16, 2026
Labelsenhancementneeds-triage

Before you start

Problem / motivation

状态： 草案，征集方向性反馈。本文不是应某个既有请求而发——它是对一条自主产品线的方向征询。 日期： 2026-09-13 相关议题（背景，见 §1）： #3268、#2974（需求）；#4900、#4955、#5209（既有路线）；#5238（在途 PR） 影响范围（若采纳）： backend/packages/harness/deerflow/knowledge/（新）、backend/packages/harness/deerflow/config/rag_config_file.py（新）、backend/app/gateway/routers/knowledge_bases.py 与 routers/rag_config.py（新）、backend/app/gateway/services/knowledge_service.py（新）、backend/packages/harness/deerflow/tools/builtins/ 新增三个检索工具（hybrid_search / wiki_search / graph_search）、frontend/src/app/workspace/knowledge/ 与 frontend/src/core/knowledge/（新）、config.example.yaml 新增 rag: 节与 rag tool group、9 个 Alembic 迁移（0011–0018 + 77df30935788）

TL;DR

  • DeerFlow 2.0 目前没有内置的私有语料能力。已合并的两次贡献（#4955 RAGFlow、#5209 LightRAG）与在途的 #5238 确立了「外部引擎 + 只读检索」的路线；#5238 进一步明确：工作区知识库管理面不做，管理留在外部引擎。
  • 本提案是一条不同形态：内置（不依赖外部引擎）的完整链路——结构感知解析（含表格与视频）、切分嵌入、图谱/wiki 加工、三路检索工具、工作区管理 UI、检索评测闭环。它已在一个分支上完成实现并自测（技术概览、界面与规模见 §4）。
  • 想先请你们对方向给个判断——内置路线是否符合项目规划，以及它与 #5238、与官方「LLM Wiki 式记忆」设想之间的关系。
  • 与既有原则的冲突已自知并明说（§3 末、§6 Q3）：本形态带有自有存储与迁移，偏离 #4900 的「不建表」原则。

1. 背景与既有路线

1.1 需求侧

#3268（RAG support，2026-05-27）下评论：

"we are considering a design similar to an LLM Wiki: using an improved hierarchical memory system to take on the role of a local knowledge base. Instead of adding a separate local KB module immediately, the follow-up plan is to make memory more structured and retrievable..."

即：需求被承认，但「独立本地 KB 模块」当时被明确推迟（#2974 是同类诉求；#3302、#2609 后续并入 #4900 的回应范围）。

1.2 既有路线（外部引擎 + 只读）

#4900（RFC，2026-08-19）为 RAGFlow 集成定下三原则：DeerFlow 不存知识库状态（不建表、不迁移、不同步）、外部引擎是唯一事实源、agent 只读（写入全是人类操作）。该路线已落地为 #4955（RAGFlow，已合并）与 #5209（LightRAG，已合并）；在途的 #5238 把交互推进到「对话级检索范围选择」，并在非目标里明确：

does not add a Knowledge item to the workspace sidebar or a /workspace/knowledge management page. Dataset and document management remains in RAGFlow.

1.3 在途碰撞（必须说明的关系）

#5238 与本提案在文件与命名上相邻：其 backend/app/gateway/routers/knowledge.py 与新配置 knowledge_base_config.py，对应本提案的 routers/knowledge_bases.py 与 rag: 配置节。两者不是同一功能——它是「把检索收窄到外部数据集」，本提案是「把语料与加工内置」——但共享「知识库」这一用户可见概念，且 UI 入口各有落点（对话输入框 vs 工作区页面）。如何分工是本文希望听到维护者意见的核心问题之一（§6 Q2）。

2. 问题陈述：provider 只读路线盖不住什么

先如实认：外部引擎 + 只读检索已覆盖的场景，本提案不主张替代——企业已有 RAGFlow 等引擎、语料已在其中、只想让 agent 能查到。

内置形态针对的是其余场景：

  1. 不依赖外部引擎：单机 / 离线 / 数据不出域部署，没有也不愿再运维第二个服务；
  2. 解析与加工的深度控制：结构感知切分（heading_path 入 chunk 元数据）、表格结构化（Excel / 分隔文本 → GFM 表，MinerU HTML 表规范化）、视频摄入（ASR + 关键帧 + 分镜卡）。在 provider 路线里这些是引擎黑盒，DeerFlow 侧无法改进、也无法评测；
  3. 引用与评测闭环：三路检索共享连续引用编号（citation_no），前端基于工具返回结构化回显「参考来源」；检索侧有一条可在 CI 里跑的回归门禁，LLM 评分类指标（RAGAS）则在评测页内运行；
  4. 工作区管理面：上传 / 解析进度 / 失败面板 / 切片编辑 / 删除影响预览与级联——#5238 明确不做的部分。

Proposed solution

3. 提案

一句话：把本实现作为 opt-in 的内置知识库子系统（或按切片选择性采纳），而不是默认开启的能力。

  • 默认不改变现有行为：三个检索工具属新建 rag tool group，全部 opt_in: true——默认 lead agent 看不到它们，仅 AgentConfig 显式列出 rag 组的 agent（内置 rag 问答 agent）才会装配；未绑定知识库时工具返回引导文案而非报错。
  • 访问边界：知识库属主私有，工具执行前做 owner 检查；不存在 agent 侧写入工具——上传 / 删除 / 触发解析全是人类操作（与 #4900 §8 的「agent 只读」一致）。
  • 与既有原则的偏离（明说）：#4900 的「不建表」在本形态下不可沿用——内置存储不是缓存而是功能本身。是否需要为「可选子系统」开一个口子，是 §6 Q3 想请教的问题；若结论是原则一贯适用，本提案退为只收不落表的切片。

4. 实现概览与证据（分支 feat/rag-knowledge-base）

4.1 系统总览

页面壳：/workspace/knowledge 为三栏结构——左栏知识库列表（含共享库预览），中栏六个 tab（文档 / 百科 / 检索测试 / 向量空间 / 知识图谱 / 评测），右栏绑定知识库的对话面板（其会话带 metadata.kb_id，与全局最近会话隔离）。

本节按五件事讲清系统的形状：全链路 → 全链路联动 → 可视化地图 → 差异化设计 → 质量闭环。

a. 全链路

上传（文档 / 表格 / 纯文本 / 图片 / 视频，共 19 种后缀）
  → 解析：MinerU（文档 / 图片）· 本地直读（`.md` / `.markdown` / `.txt`）· calamine（Excel 逐 sheet 转 GFM 表）· ASR + 关键帧 + 分镜卡（视频）
  → 切分：结构感知——heading_path 等结构元数据随 chunk 落库；表格按表头锚定行组
  → 实体抽取：逐切片抽取实体与关系
  → 归一化互联：片内两级合并（别名表：大小写 / 空白折叠、英文复数折叠、括号全名折叠；+ 嵌入相似度阈值）→ 跨片增量重解析五步链：合并实体行 → 重写关系端点（去重、去自环）→ 删别名向量并按合并后的描述重嵌代表 → 双写切片标签（业务库列 + Qdrant payload）→ 相关条目转 dirty
  → wiki 生成：资格制（卫生门槛 + 跨 ≥2 切片）→ 物料打包（源切片重叠 Jaccard ≥ 0.5、≤7 个一组，一次 LLM 产出多条）→ dirty 增量重生成并回填新合格条目
  → 存储：结构化数据在业务库（切片 / 实体 / 关系 / 条目 / 手工卡片 / 评测运行，走 Alembic 迁移）；四类向量与指针在 Qdrant（kb_chunks / kb_entities / kb_wiki_entries / kb_manual_cards）
  → 检索：三路工具——hybrid_search（混合召回 → RRF → 重排）· graph_search（实体关系多跳）· wiki_search
  → 回答：绑定知识库的对话（强制检索工作流 + 引用纪律），句末 [n] + 前端结构化「参考来源」

关键选型：嵌入与重排走 DashScope（qwen3.7-text-embedding 单次产出 dense+sparse；qwen3-rerank 精排）；索引由后台 worker 限并发、限速率执行。

支持的上传类型（19 种后缀，分三档处理）：经 MinerU 解析——.pdf / .doc / .docx / .ppt / .pptx / .png / .jpg / .jpeg；本地直读（不走网络）——.md / .markdown / .txt；表格本地归一为 GFM——.csv 始终可用，.xlsx / .xls / .tsv 由 rag.table.enabled 门控；视频——.mp4 / .mov / .mkv / .webm 由 rag.video.enabled 门控，其中 ASR（funasr / Paraformer）与关键帧 OCR（PaddleOCR）在本地运行。

b. 全链路联动（改动 → 下游传播）

上游动作 下游传播
编辑切片 就地重嵌入（同 point ID 覆盖旧向量）；实体保持不变——需重新理解内容时显式触发「重抽」，走下一行链路
重抽切片 撤旧抽取 → 清理孤实体（向量 + wiki 失格链）→ 按当前文本重新抽取（不重解析源文件）→ 归一化 → 合格实体标 wiki dirty
删除切片 级联五连：图谱贡献 → 孤实体向量 → wiki 失格链 → 向量点 → 业务行
新增文档 索引完成后图谱腿重解析触达实体 → 相关条目标 dirty → 增量重生成（并回填新合格条目）
删除文档 三存储级联（Qdrant → 图谱 → wiki 生命周期 → 业务行）；高频实体标 dirty、跌阈实体失格

不变量：幂等恢复（Qdrant 无事务，级联步骤均可重入）、失败不阻塞（单次解析/合并失败不影响文档到达 ready）、处理中 409 守卫（管线在飞时拒绝并发重抽/删除）、重排故障降级 RRF（向量路永不硬失败）。

c. 可视化地图（链路阶段 ↔ 观测入口）

链路阶段 观测入口
解析 / 切分 / 索引进度 文档 tab（逐路径状态 + 切片抽屉）
实体 / 归一化 / 关系 知识图谱 tab
wiki 条目生成与维护 百科 tab
三路检索命中对比 检索测试 tab
向量空间分布（切片/实体/百科/条目） 向量空间 tab
回答与引用回显 对话面板（右栏）
检索质量趋势 评测 tab

每一层加工都有对应观测入口——以下逐节展开（4.2–4.7 为六个 tab，4.8 为右栏对话面板，4.9 为规模与验证）。

d. 差异化设计

  • 检索联动跟随：检索测试或对话的每一轮命中，实时叠加到向量空间与知识图谱两个 tab（叠加染色 + 邻居高亮）；叠加走 merge 更新、不重跑力导向布局；两 tab 共享一个「跟随对话」开关（默认开，关闭即冻结供手动探索）；不引入独立过渡动画层。
  • wiki 全链路自动维护、且可定向：任何上游改动经 dirty 链增量重生成；生成粒度为增量 / 全量（规则升级）/ 按条目多选重建。
  • 通用会话导入知识库：任意会话可从导出菜单或最近会话右键菜单直接导入为知识库文档——复用导出格式化器与常规上传管线（无专用后端端点），重名自动分配 (2) 后缀。

e. 质量闭环

  • 两层评测：Layer-1 为确定性 IR 指标（命中率 / 召回@k / MRR / 路径准确率，可复现）；Layer-2 为 LLM 评分（RAGAS 类）。
  • 门禁分工：Layer-1 接入 CI（.github/workflows/rag-eval.yml，PR 触碰检索模块即跑并把摘要评回 PR）；Layer-2 只出报告、不设门禁，在夜间任务运行，报告预留人工校准位。
  • 题库来源：可从一篇或多篇文档联合生成候选题（1–10 道，默认 5），逐条人工采纳后才入库；也可手工添加。运行可见三阶段进度并可中止。

（逐项细节见 §4.7。）

4.2 文档 tab（解析与切片）

  • 视图：文档表（列可配置）、逐路径解析状态（向量 / 图谱 / wiki 三线）、失败面板（就地重试）、切片抽屉（tick 轨 + 卡片列表 + 编辑器）。
  • 内容：上传走库级菜单 + 拖拽（后缀白名单，表格类后缀由 rag.table.enabled 开关门控）；切片编辑即重嵌入、删除前有影响预览、单切片重抽；视频文档有在线播放、关键帧与重标注重跑。
更多截图：视频切片抽屉 / 文档切片抽屉 / 会话切片抽屉 / 类型展示 / 会话导入知识库（5 张）

4.3 百科 tab（生成条目 + 我的条目）

  • 视图：两区默认都展开——「生成条目」（AI）与「我的条目」（用户自建卡片）；顶部搜索覆盖两者；条目抽屉展开源切片（只读卡片）；右键单条 / 多选局部更新重建；全量重建确认弹窗；「新建卡片」在 ⋯ 菜单与区内双入口。
  • 内容：生成条目按实体资格自动维护；另有我的条目（人工卡片）——用户自建自管、不参与 AI 生命周期（不自动重生成、不失格），include_in_wiki_search（界面标签「混入搜索」）决定是否进入百科检索。
更多截图：wiki自动生成条目指定方向优化 / 用户自建wiki条目（2 张）

4.4 检索测试 tab（三路联测）

  • 视图：输入查询 → 向量 / 图谱 / wiki 三路命中并列（分数 + 跨路耗时排名着色）；wiki 命中可勾选折叠其源切片；图谱命中附迷你关系图。
  • 内容：检索结果可一键保存为评测题（多路 expected_paths 勾选）——测试与评测闭环相接。
更多截图：测试实体切换（1 张）

4.5 向量空间 tab（投影可视化）

  • 视图：切片 / 实体 / 百科 / 条目（用户自建）四类点的 2D/3D 投影散点；算法（PCA / UMAP）、维度、搜索范围可切；抽样徽标提示采样比例。
  • 内容：检索命中实时叠加（含查询点投影，仅 PCA）；「跟随对话」与知识图谱 tab 共享；投影内容变化时丢弃旧坐标系的叠加并提示。
更多截图：向量空间跳转（1 张）

4.6 知识图谱 tab（实体关系）

  • 视图：力导向图（ECharts）；LOD 档位——社区层可上卷查看全局结构；悬停高亮当前节点 + 一跳邻居。
  • 内容：检索叠加三层染色（种子 / 扩展 / 证据）；叠加变更不动布局；「跟随对话」共享开关。
更多截图：图谱放大1 / 图谱放大2（2 张）

4.7 评测 tab（质量闭环）

  • 视图：题库 / 总览 / 历史三视图；运行横幅（评测档位、三阶段进度、两步取消）；指标总览（指标卡 + sparkline）；趋势图（ECharts，按运行序数为横轴）。
  • 内容：题库可自动生成——选一篇或多篇文档联合出题，一次产出 1–10 道候选（默认 5），逐条采纳 / 忽略后才进题库；也可手工添加。指标含确定性 IR 与 LLM 评分两族，趋势带基线 / 阈值参考线。门禁分工：Layer-1 确定性指标接入 CI（rag-eval.yml，PR 触碰检索模块即跑并把摘要评回 PR）；Layer-2（LLM 评分 / RAGAS）只出报告、不设门禁，在夜间任务运行，报告预留人工校准位（每月抽样 ≥10% 回填 human_sample_ratio / cohens_kappa）。
更多截图：考题生成 / 考题评审 / 评测详情 / 评测历史（4 张）

4.8 对话面板与引用回显（右栏，非 tab）

  • 视图：与知识库绑定的对话；回答句末 [n] 标注，前端基于工具返回结构化渲染「参考来源」区。
  • 内容：强制检索工作流（向量保底；实体关系走图谱；概念定义走 wiki；深度检索模式三路并用）、引用编号由工具生成、模型只许照抄、无证据不作答（宁可拒答）；会话与知识库绑定（metadata.kb_id）并与全局最近会话隔离。

4.9 规模与验证

  • 模块规模（已核：fork 点 99c926b7 下 deerflow/knowledge/ 与 backend/tests/knowledge/ 均为 0 文件，以下全部为本分支新增）
    • harness backend/packages/harness/deerflow/knowledge/：50 个 Python 文件（目录内共 100 个文件）
    • 后端 backend/tests/knowledge/：72 个测试文件、1021 个测试函数
    • 前端 frontend/src/components/workspace/knowledge/：49 个组件文件；frontend/src/core/knowledge/：21 个模块文件；另有 /workspace/knowledge 页面
  • Gateway API：知识库 / 文档 / 切片 / 手工卡片 / 评测的完整 CRUD——含切片编辑重嵌入、删除影响预览、删除级联、原文下载、视频流与关键帧、重跑重标注。
  • CI 门禁：rag-eval.yml，PR 触碰检索模块时跑确定性 IR 指标并把摘要评回 PR。
  • 代码位置：完整实现位于一个 feature 分支（尚未提交上游）。

5. 边界与二期

  • 合入方式：接受整条合入，也接受按切片选择性采纳。
  • 不替换 #5238 的范围选择：若两者共存，最自然的结合是把「内置 KB」作为其 scope 框架的可选项之一（§6 Q2）。
  • agent 只读：不存在 agent 侧写入工具——上传 / 删除 / 触发解析均为人类操作。对齐 #4900 §8 已确立的设计立场，是设计选择而非缺口。
  • 访问模型为属主私有（v1 不做团队共享）：与平台按用户隔离的模型一致；schema 已预留 visibility 共享扩展位，访问判断收敛在单点 can_access()，二期引入共享只改一处。对照 RAGFlow 线的「单一租户 key、全员共享同一语料」——#4900 §6.2 曾为此要求在页面上专门警示用户。
  • 图谱/wiki 生成与视频管道属「二期可裁」——它们可以独立于核心检索被接受或拒绝。

6. 开放问题（恳请反馈）

  • Q1 方向：内置（不依赖外部引擎）的知识库子系统是否符合项目路线、值得推进么。
  • Q2 关系：若方向可行，它与 #5238 的对话级 scope、与 §1.1 中「LLM Wiki 式记忆」设想应该如何分工。我的理解：内置 KB 面向「人类整理的外部语料」，LLM Wiki / 记忆面向「agent 自身学到的」，生命周期与属主不同——#4900 §15 对记忆与语料做过同样的区分，可循先例。
  • Q3 原则边界：#4900 的「不建表」针对外部引擎集成（状态归引擎）是完全成立的；它是否也覆盖「内置子系统」形态——内置下存储是功能本身而非缓存。

7. 分阶段落地（若方向可行）

每阶段可独立提交、独立回退：

阶段 内容 层
P1 知识库核心：解析 / 切分 / 嵌入 / 存储 / 三路检索工具 + rag agent harness
P2 Gateway 管理 API（知识库 / 文档 / 切片） app
P3 工作区页面 /workspace/knowledge frontend
P4 评测闭环（题库 / 指标 / CI 门禁） app + CI
P5 图谱 / wiki 加工 harness
P6 视频摄入 harness + frontend

P1–P3 是主干；P4 可与主干解耦、先行落地；P5 / P6 为可裁增量。

Affected area(s)

Frontend (UI / Next.js), Backend API (gateway / endpoints / SSE), Agents / LangGraph (graph, prompts, langgraph.json), Config / setup, Docs

Alternatives considered

A. 只走外部引擎（#4900 已采纳的路线）——由 RAGFlow / LightRAG 等承担检索，DeerFlow 不存知识库状态。 未采用的原因：不覆盖离线 / 数据不出域部署；且解析、切分、表格与视频加工都在引擎内部，DeerFlow 侧无法改进、也无法评测。

B. 交给已有记忆系统承担本地 KB（#3268 回复里提到的 LLM-Wiki 式分层记忆方向）。 未采用的原因：记忆面向「agent 自身学到的、跨会话沉淀」，本形态面向「人类整理并持续维护的外部语料」——生命周期、属主与治理方式都不同（#4900 §15 对两者做过同样的区分）。

C. 只做检索侧、管理面留在外部引擎（即 #5238 的边界）。 部分接受：正文保留了「按切片选择性采纳」的退路，工作区管理面（上传 / 切片编辑 / 评测）属于可单独裁掉的部分。

Additional context

8. 其他在研方向（不在本提案范围）

同一分支上还有三条与本提案无关的独立方向，不随本提案请求评审：

  • Agent 观测宠物：把 Agent 运行状态投射为一个纯观察者（只读订阅 run 生命周期，不做任何注入或修改），形态与能力解耦；同类产品已有先例（Qoder / Codex / WorkBuddy）。
  • Harness 可视化：把中间件装配链与门控事件（read_gate / tool_progress / subagent_limit / tool_promotion / sandbox_audit / skill_policy）做成可观测面；数据侧（事件契约）与视图侧可分离。
  • 组装画布与对外 MCP：以画布方式组装工具 / 会话流程 / skills，并把组装结果作为 MCP 对外提供（目前仅到 spec , plan 阶段）。

Source: bytedance/deer-flow

View original on GitHubView discussion on GitHub