RAGFlow 三大引擎 详解：DeepDoc、RAPTOR、GraphRAG

RAGFlow 三大引擎 详解：DeepDoc、RAPTOR、GraphRAG

参考文章 1：16-07.RagFlow 知识解析与构建：RAGFlow 异步+高阶知识架构 的数据处理核心流程设计

参考文章 2：RAGFlow 数据注入（Ingestion） 通俗解读：数据解析与知识构建 的 大白话介绍

三大引擎核心定位：

三大引擎并非平级替代品，而是处于数据处理的不同层级：

• DeepDoc（底层文档解析引擎，地基）------ 负责把原始文件变成结构化文本块，是RAG的输入源头；

• RAPTOR（分层摘要检索引擎，纵向知识金字塔）------ 解决长文档全局理解，做纵向语义层级；

• GraphRAG（知识图谱检索引擎，横向关系网络）------ 解决实体、关系推理，做横向语义关联。
  重要区分：

• DeepDoc 完全自研，随 RAGFlow 开源，不可独立 pip 安装；

• RAPTOR、GraphRAG 算法思想分别来自斯坦福 ICLR2024 论文和微软 GraphRAG 范式，但代码全部自研重写，没有直接引入第三方 pip 包，深度接入了 RAGFlow 的任务队列、缓存、存储体系。

---

一、DeepDoc 深度文档解析引擎

代码路径 ：项目根目录 deepdoc/，随 RAGFlow 开源。

1. 定位

RAGFlow 最底层的输入引擎，把 PDF、Word、扫描件、PPT、Excel 等杂乱文件，输出带版面信息的结构化 Block。

普通 RAG 只做纯文本抽取；DeepDoc 将文档解析视为计算机视觉问题，先识别页面布局，再提取内容，而非简单捞文字。

2. 核心流水线

DeepDoc 的解析流程（以 PDF 为例）：

PDF 页面 → 图像提取与 OCR → 版面分析 → 表格结构识别 → 文本合并 → 结构化输出

1. OCR 文字识别 ：扫描件、图片 PDF 做文字提取，保留每个文字块的坐标 bbox；底层调用 PaddleOCR。当 PDF 内嵌文字可直接提取时，优先用原生文本（精度更高），并实现两套乱码检测策略（PUA/CID 占位符、字体编码乱码），一旦发现乱码则强制降级到 OCR。
2. Layout 版面分析（DLA）：使用 YOLO 检测 10 类版面元素：标题、正文、表格、图片、公式、页眉、页脚、列表等，输出带类型、坐标的 block 对象。这一步是多栏文档不出错的关键：先搞清阅读顺序，再提取内容，避免左右栏文字混排。
3. TSR 表格结构识别：识别跨行、跨列合并单元格，还原表格，输出 Markdown 格式。这是 DeepDoc 的最强能力之一，传统解析器读表格只是"按行扫成数字流"，而 DeepDoc 能保留表头与单元格的对应关系。
4. 文本合并 ：使用 XGBoost 二分类模型判断相邻文本块是否属于同一段落------这是一个工程上非常务实的选择：用轻量机器学习而非深度学习来解决跨行/跨页文本合并问题。
5. 图文关联：把图片和其图注 caption 绑定在一起。
6. 版面感知分块：不粗暴按 token 切割，尽量保证完整表格、完整段落不被拆碎。

最终每个页面输出为带类型的 blocks：

{
    "page_num": 1,
    "blocks": [
        {"type": "title",      "content": "章节标题",      "bbox": [x0, y0, x1, y1]},
        {"type": "paragraph",  "content": "正文内容...",    "bbox": [x0, y0, x1, y1]},
        {"type": "table",      "content": "<table>...</table>", "markdown": "|...|"}
    ]
}

3. 架构：parser/ 与 vision/ 双模块

DeepDoc 代码库分为两个子模块，分工明确：

• parser/：文档格式解析器，负责把各种文件格式（PDF、DOCX、Excel、PPT、图片等）转换为"文本 + 位置信息"的统一中间表示。共 11 个标准解析器，按复杂度分三层：
  • 轻量文本解析器：TxtParser、JsonParser、HtmlParser、MarkdownParser、EpubParser（不依赖视觉模型）
  • Office 文档解析器：DocxParser、ExcelParser、PptParser（利用格式自带的结构信息）
  • 视觉 AI 解析器 ：RAGFlowPdfParser（核心，2019 行）、VisionParser、MinerUParser、DoclingParser、TCADPParser、PaddleOCRParser
• vision/：视觉 AI 模型，提供 OCR 文字检测/识别、Layout 版面识别、TSR 表格结构识别等底层能力。

4. 模板化分块：15+ 种解析模板

DeepDoc 不是"一种解析打天下"，而是按文档类型提供不同模板：

模板	适用场景	分块策略
Paper	学术论文	保留摘要、方法、结果作为独立单元
Book	书籍	按章节层级
Manual	产品手册	尊重标题和操作步骤
Q&A	问答对	每个问题与其答案绑定
Table	表格数据	表格转 Markdown 后整表成块
Resume	简历	识别技能、经历等区块
Laws	法律文书	保留法条完整性
General / Naive	通用文档	按分隔符 + token 数

5. 两种工作模式

• DeepDOC 模式（默认）：开启视觉版面识别，保留标题、表格、图片结构；适合企业 PDF、合同、手册。消耗 GPU/CPU 资源更高。
• Plain Text 朴素模式：关闭 CV 识别，直接抽取文本，机械切分；速度快，丢失版面信息。

此外还支持外接第三方解析器：MinerU（论文公式强）、Docling，作为备选替换 DeepDoc。

6. 优点

• 复杂版式 PDF、扫描件、带大量表格文档的召回质量显著高于普通文本解析；
• 版面感知分块，避免把表格、章节拦腰切断，减少幻觉；
• 输出携带页码、坐标，支持答案溯源、原文定位。

7. 局限

• 消耗算力大，大文件解析慢；
• 多栏复杂排版、手写文档识别会出错；
• OCR 效果依赖图片清晰度。

8. 适用场景

企业 PDF、合同、产品手册、扫描档案、大量表格文档。所有 RAGFlow 知识库默认都跑 DeepDoc，是一切的起点。

DeepDoc 把"文档解析"从一个简单的 I/O 步骤，升级成了一门视觉 AI + NLP 融合的工程技术。它输出的每个 chunk 都带有页码、坐标、版面类型等元数据------这正是 RAGFlow 能做到"答案可追溯、可高亮原文"的根本原因。

二、RAPTOR 分层递归摘要引擎

代码路径 ：rag/raptor.py；思想来自斯坦福 ICLR2024 RAPTOR 论文，无第三方库导入，完全自研重写改造。

1. 定位：构建知识 纵向 金字塔，解决长文档痛点 。

普通 RAG 只有底层碎片化 chunk，问 起 文档全局总结、跨章节综合问题时，容易只召回局部片段，回答片面。

RAPTOR 自底向上做递归聚类 + LLM 摘要，产出多层级的知识块：

• 底层是原文细节，
• 上层是章节/全文摘要。

检索时底层、高层摘要块一起参与向量召回。

2. 完整工作流程

1. 输入：DeepDoc 解析输出的原始 chunk（叶子节点，细节层）。

2. 向量化与降维 ：对所有 chunk 做 Embedding，然后用 UMAP 降维（目标维度 min(12, len(embeddings)-2)，距离度量用 cosine）。

3. 自动确定最优簇数 ：使用 BIC（贝叶斯信息准则） 在候选簇数范围内选出最优值------避免人工指定聚类数的主观性。这是 RAGFlow 相对于原版论文的自研优化。

4. 聚类：

   • 默认模式 ：GMM 高斯混合模型做软聚类，每个点得到属于各个簇的概率分布，低于阈值 _threshold=0.1 的点被过滤。
   • Ψ-RAG（AHC 模式）：新版本新增分层聚合聚类，速度更快，语义损失更小，可切换。

5. LLM 摘要：对每个簇内的块截断、拼接，送进聊天模型生成摘要。

   这些摘要不是贴回原块，而是作为全新的独立 chunk 追加到集合末尾，形成上一层节点。

6. 递归：把新生成的摘要 chunk 作为下一轮的输入，重复"降维→聚类→摘要"，直到只剩一个簇（根节点）。

7. 存储：所有层级（原始 chunk + 各层摘要）全部作为普通 chunk 写入 ES/Infinity 向量库，共享同一套索引。这种"折叠树检索"不维护复杂内存树结构，检索直接向量相似度召回各层级节点，工程实现简单稳定。

3. 优点

• 同时支持细节提问 + 宏观总结提问；问细节召回底层原文，问全局召回高层摘要；
• 超长文档（几百页手册、书籍）综合问答效果提升明显；
• 完整接入 RAGFlow 体系：digest 指纹缓存、任务队列、限流、断点续跑。

4. 缺点

• 大量调用 LLM，token 消耗高，构建索引慢；
• 回答质量严重依赖摘要的生成质量；摘要一旦出错，上层全部出错；
• 不适合短文档，短文档开启 RAPTOR 收益很小，浪费算力。

5. 适用场景

几百页长文档、产品手册、书籍，需要做全局总结、跨章节综合问答；短文档不建议开启。

三、GraphRAG 知识图谱引擎

代码路径 ：graphrag/*；算法范式借鉴微软 GraphRAG 思路，没有 import 微软 graphrag 包，全部自研重写工程化实现。

1. 定位

横向编织实体‑关系网络，解决实体关联、多跳推理类问题。

普通向量 RAG 擅长语义相似度匹配，但面对"A 和 B 是什么关系？A 参与了哪些项目？"这类需要显式推理的问题效果差。

GraphRAG 从文本抽取实体、关系，构建知识图谱；实体、关系、社区报告全部转成特殊的 chunk 存入向量库，做向量 + 图谱混合检索。

2. 核心流程（RAGFlow 自研流水线）

原始文档分块 → 子图生成 → 图合并 → 实体解析(可选) → 社区检测(可选) → 存储

1. **抽取子图（generate_subgraph）：**基于 DeepDoc 输出的 chunk，使用抽取器提取实体和关系三元组。提供两种模式：
   • Light 方法（默认）：基于 LightRAG 的提示词，消耗的 token、内存和计算更少；
   • General 方法 ：基于微软 GraphRAG 的提示词，多轮提取，质量更高但成本高。
     抽取结果构建为 NetworkX 子图，立即以 knowledge_graph_kwd="subgraph" 写入文档存储，便于断点续跑。
2. 图合并（merge_subgraph） ：把新子图并入全局图，通过 graph_merge() 合并节点与边（重复节点合并描述与来源，重复边累加权重），并重新计算 PageRank 作为后续检索的排序特征。Redis 分布式锁保证同一个知识库图谱串行写入，防止并发任务把图谱写乱------微软原版没有该工程能力。
3. 实体解析（resolve_entities，可选）：相当于"实体去重开关"。先用编辑距离、字符集合相似度等规则筛选候选同义实体对，再用 LLM 判断是否合并。可权衡成本与精度。
4. 社区检测（extract_community，可选） ：用 Leiden 算法 划分社区，再用 CommunityReportsExtractor 为每个社区生成结构化报告（标题、摘要、findings、评分）。可关闭以降低 token 开销。
5. 存储 ：所有图谱元素都以 chunk 形式写入文档存储，通过 knowledge_graph_kwd 字段区分类型：

Chunk 类型	含义
graph	完整知识图谱（NetworkX JSON 序列化）
subgraph	单篇文档的子图
entity	实体节点
relation	关系边
community_report	社区摘要报告

重点区别微软原版 GraphRAG：

• 微软原版：文件 CSV 存储图谱，不支持增量更新；
• RAGFlow：实体关系和普通文档统一存在向量检索引擎，支持单文档增量构建图谱，新增文档不需要全量重建。

3. 检索时的双检索器架构

GraphRAG 启用后，RAGFlow 走双检索器并行：

• 向量检索器（Dealer）：传统向量 + BM25 全文检索；
• 图检索器（KGSearch）：实体向量搜索 → 关系向量搜索 → N 跳邻居探索 → 社区检索。

融合时图结果优先 前置插入到位置 0，评分公式为：P(E|Q) = PageRank × Similarity。

4. 优点

• 擅长关系推理、多跳问答、人物/事件梳理；答案可追溯实体来源，降低幻觉；
• 支持增量更新图谱，新增文档追加，不用全量重建；
• 可开关实体消歧、社区报告，灵活控制 token 开销；
• 完全复用 RAGFlow 任务调度、限流、缓存、断点续跑。

5. 缺点

• 构建图谱 token 消耗巨大，成本高；知识库越大建图越慢；
• LLM 抽取实体会产生错误三元组，带来图谱噪声；
• 简单 FAQ 场景开启 GraphRAG 几乎没有收益。

6. 适用场景

法律文档、企业档案、人物事件、合同，大量实体关系，需要做关联推理；简单问答不建议开启。

---

四、三大引擎横向对比总表

引擎	归属本质	核心作用	解决痛点	算力消耗	适合场景
DeepDoc	✅ RAGFlow 自研底层解析引擎	文档版面解析、表格、图文结构化输出	PDF/扫描件/表格解析差，分块破碎	中	全部企业知识库的基础，默认开启
RAPTOR	论文思路，代码自研重写	纵向构建分层知识金字塔；多层摘要	长文档全局总结、跨章节问答	高	几百页长文档、手册、书籍
GraphRAG	微软 GraphRAG 范式，代码自研重写	横向构建实体关系知识图谱；多跳推理	实体关联、关系推理类问题	很高	法律、档案、合同，大量实体关系推理

---

五、三大引擎的协同关系与实践建议

协同关系图

用户上传 PDF/Word/Excel/PPT/图片
        ↓
┌─────────────────────────────────────────┐
│  ① DeepDoc 引擎（解析层，必选）          │
│     版面识别 + OCR + TSR + 公式识别       │
│     → 结构化 blocks                     │
└─────────────────────────────────────────┘
        ↓
┌─────────────────────────────────────────┐
│  标准流水线：分块 → 向量化 → 入库         │
│     → 扁平 chunk（细节检索的基础）        │
└─────────────────────────────────────────┘
        ↓
   ┌────────────────┴────────────────┐
   ↓                                 ↓
┌──────────────────┐    ┌──────────────────────────┐
│ ② RAPTOR（纵向） │    │ ③ GraphRAG（横向）         │
│ 递归聚类+摘要    │    │ 实体关系抽取+社区发现      │
│ → 层次化摘要树   │    │ → 知识图谱+社区报告        │
│ 解决：长文档多跳 │    │ 解决：实体推理多跳         │
└──────────────────┘    └──────────────────────────┘

关键认知

1. DeepDoc 是基础，RAPTOR 和 GraphRAG 是增强。没有 DeepDoc 的高质量解析，后两者的输入就是噪声。
2. RAPTOR 和 GraphRAG 解决的是不同维度的"多跳"问题：RAPTOR 擅长"从细节到全局"的层次化理解，GraphRAG 擅长"从实体 A 到实体 B"的关系推理。
3. 三者不是互斥选择。实际生产中，DeepDoc 必然开启；RAPTOR 和 GraphRAG 根据业务需求选择性开启，但要评估 token 成本和计算开销。

实践建议

你的文档类型	推荐配置
短文档、FAQ、单一主题	仅 DeepDoc + 标准流水线
长篇技术手册、研究论文、书籍	DeepDoc + RAPTOR
企业知识库、涉及多实体关系（人物/组织/产品）	DeepDoc + GraphRAG
复杂企业文档（长 + 多实体）	DeepDoc + RAPTOR + GraphRAG（成本最高）