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

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

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

这一章讲 RAGFlow 如何把 PDF/Word/Excel 这类原始文件，自动变成向量库中可搜索调用的知识------即 RAG 中著名的数据注入（Ingestion） 过程。

RAGFlow 数据注入 整个链路：用户上传文件 → 后台异步消化 → 解析文档 → 切分块 → 向量化入库 ；还可额外做两件高级加工：分层摘要（RAPTOR） 和知识图谱（GraphRAG）。

一、整体比喻：做饭模型

原文用做饭类比，非常形象：

1. 结构化解析 DeepDoc = 洗菜切菜

把 PDF 中的标题、段落、表格、图片、公式区分开，不是一股脑拿纯文本。 2. 知识构建 = 烹饪调味

• 普通版：文本转向量；

• 高级版① RAPTOR：给长文档做多层总结；

• 高级版② GraphRAG：提取人物、事件、关系，做知识图谱。

1. 多模态索引 = 装盘贴标签

存到 ES/向量库，打上关键词索引 + 向量索引，后续用户提问时可以快速捞出。

这套体系要回答四个核心问题：

1. 数据怎么进来？（数据注入架构）

2. 大批量任务怎么调度跑起来？（异步生产者‑消费者）

3. 文件怎么变成向量片段 chunk？（标准流水线：DeepDoc → 分块 → Embedding → 入库）

4. 能不能做更高级的知识，不只是碎文本？（RAPTOR、GraphRAG 高阶知识构建）

二、数据注入架构：三步解耦（上传、关联、触发处理）

核心思想：上传文件不要当场卡死页面，前端只做登记，后台慢慢干活。

分成三个 API 步骤：

1. 上传托管 /upload

   用户选文件上传，文件丢进 MinIO 对象存储，数据库记一条 File 记录。

   ⚠️ 此时文件只是存上去，还不属于任何知识库，完全没解析。相当于把食材丢进仓库。

2. 关联建档 /convert

   把这个文件绑定到某一个知识库，生成 Document 文档记录。

   Document 记录：记录用哪个解析器、解析参数、指向刚才的 File。状态：UNSTART（待处理）。

   相当于：从仓库把食材拿到厨房台面，但还没开始切。

3. 触发处理 /run

   用户点击【开始处理】。系统把解析任务丢进 Redis 消息队列，状态改为 RUNNING（处理中），前端直接返回，不等待解析完成。后台 worker 慢慢消费队列干活。

额外两条快捷接口：

• /upload_and_parse：对话窗口上传文件立刻解析，一站式捷径；

• /parse：只解析预览，不存入知识库，临时用。

✅ 好处：大 PDF、几百 MB 文档上传，网页不会转圈卡死；可以多台机器横向扩容后台处理能力。

模块对应：document_app.py、file2document_app.py。

三、异步处理：生产者‑消费者模型（Redis 队列）

生产者：task_service.py；消息池：Redis Stream；消费者：task_executor.py

生产者 task_service.py：负责"规划任务"

当点击开始处理，queue_tasks() 函数干活：

1. 任务拆分

   不 把几百页 PDF 做成一个大任务，而是 拆小任务方便并发、断点续跑。

   • PDF 普通：12 页一个子任务；

   • 论文解析器：22 页一个子任务；

   • 如果要做 GraphRAG 全文理解：整篇文件作为 1 个任务；

   • Excel 表格：每 3000 行切一个子任务。

2. Digest 指纹（非常核心的优化）

   把解析配置、分块参数、页码全部算成一个指纹哈希值。

   作用：如果改完配置重新处理文档，某一段的指纹没变，说明这部分不需要重算，直接复用上次已经生成好的 chunk 向量，不用重复调用 LLM、Embedding，省钱省时间。

3. 过滤掉已经可以复用的任务，剩下真正要干活的任务扔进 Redis 队列。

消费者 task_executor.py：真正干活的工人进程

后台跑循环，不停监听 Redis 队列：

1. 优先处理崩溃没跑完、未确认（unacked）的任务，实现断点续跑；

2. 控制最大并发数，防止把 LLM、数据库打崩；不同操作单独限并发：图谱生成限制最多 2 路；

3. do_handle_task() 总调度：根据任务类型分发流水线

   • 普通文档 → 标准解析流水线；

   • RAPTOR 任务 → 执行分层摘要；

   • GraphRAG 任务 → 执行知识图谱抽取；

4. 处理完把 chunk 批量写入存储，更新进度。

简单理解：生产者负责切蛋糕、派工单；Redis 是任务看板；消费者工人拿工单干活；程序崩了重启，看板没做完的工单继续做，不会全部重来。

四、标准流水线：文档 → chunk → 向量 → 入库（最常用路径）

四步：DeepDoc 智能解析 → 分块 chunk → Embedding 向量化 → 写入存储

① DeepDoc 解析引擎（RAGFlow 核心自研）

普通 RAG 工具是粗暴把 PDF 当纯文本。DeepDoc 用 CV 视觉识别版面，识别：标题、正文、表格、图片、公式、页眉页脚。输出带坐标、类型的结构化 block。

• 扫描版 PDF：做 OCR 识别文字；

• 表格：还原跨行跨列表格，输出 markdown 表格；

• 图片：绑定图片 + 图片说明。

同时有解析器工厂，不同文件调用不同解析器：论文、书籍、PPT、法律文档、表格、简历、音频等。

两种模式：

• Plain Text 朴素模式：扔掉布局，机械切文本；

• DeepDOC 版面感知模式：保留文档结构，不把一个完整表格拆碎。

② Chunker 分块

基于 DeepDoc 输出的结构化内容，按 token 大小、分隔符切片段，支持重叠。

版面感知模式的优势：不会把一个表格、一个完整章节拦腰切断。

输出 chunk，每个 chunk 携带大量字段：原文、分词索引、页码坐标、图片 ID。还可可选调用 LLM 做增强：

• auto_keywords：自动提取关键词；

• auto_questions：为每一段生成"用户可能问的问题"。向量化优先使用生成出来的问题，检索效果更好。

③ Embedding 向量化

一个巧妙设计：标题向量和内容向量加权融合

最终向量 = 0.1 * 标题向量 + 0.9 * 内容向量

提高检索时对文档标题、文件名的匹配能力。

向量字段动态命名，如 q_1536_vec，维度跟随 embedding 模型自动变化。

④ 索引入库

1. DocStoreConnection 抽象适配层：屏蔽底层数据库差异。可以接 ElasticSearch，也可以接 Infinity 向量库。想换别的数据库只需新增适配器，业务代码不动。

2. mapping.json 约定优于配置：不用手动定义 ES 表结构。字段名后缀自动识别类型：

   • *_vec 自动识别为向量字段；

   • *_tks 文本分词；

   • *_kwd 精确关键词过滤。

普通 RAG 项目很多人要手动写复杂 ES Mapping；RAGFlow 靠命名约定自动搞定。

✅ 到此为止，普通 RAG 能力已经全部完成，可以做文档问答。

但是：标准流水线有短板：只有碎片化 chunk，没有全局视角，实体之间没有关系。长文档全局提问、实体关系推理会拉胯。

于是有两套高阶能力：RAPTOR、GraphRAG。

五、高级知识构建：RAPTOR 与 GraphRAG

维度	标准流水线	RAPTOR	GraphRAG
核心	文本片段 chunk	多层知识金字塔	实体+关系图网络
怎么做	DeepDoc 切分+向量化	UMAP 降维 + GMM 聚类 + LLM 递归摘要	LLM 抽取实体关系、社区发现
产出	零散向量块	底层原文块 + 多层高层摘要块	节点、边、社区报告
适合场景	普通文档问答	超长文档，需要全局概览	关系推理、人物事件梳理

RAPTOR：纵向，搭知识金字塔

类比人读厚书：摘抄细节，对几段做小结，再对小结做总结，一层一层往上归纳。

流程：

1. 底层原始 chunk 向量做 UMAP 降维；

2. GMM 高斯混合模型自动聚类，不需要手动指定簇数量；

3. 同一簇交给 LLM 生成摘要；摘要再次向量化，作为上一层输入；

4. 循环迭代，直到收敛。

检索时底层细节块、高层摘要块一起参与召回。用户问宏观问题召回高层摘要；问细节召回底层原文。解决长文档"只见树木不见森林"。

GraphRAG：横向，编织实体关系网络

目标：从文本抽【实体】【关系】，构建知识图谱。比如文档提到 A 公司和 B 公司签署合作协议。

流程：

1. 抽取子图：从单篇文档提取实体、关系；

2. 子图落盘，断点续跑；

3. 子图合并进知识库全局图谱；Redis 分布式锁保证同一个知识库图谱只能单任务写入，防止并发跑坏图谱；

4. 可选：实体消歧（把同义名字合并）；Leiden 算法做社区划分，生成社区报告；

5. 实体、关系、社区报告全部也当成特殊 chunk 存入 ES，和普通文本共用一套检索体系，靠字段 knowledge_graph_kwd 区分是实体还是关系。

当用户提问"A 和 B 有什么联系"，普通 RAG 检索只能命中零散段落；

GraphRAG 可以直接检索图里面的关系，推理答案，可解释性更强。

⚠️ 代价：大量调用 LLM，算力开销大。

六、整体分层复盘（看懂整个地基）

1. 注入层：上传‑关联‑触发三步解耦。解决前端交互体验，大文件不阻塞。

2. 调度层：生产者‑消费者 Redis 队列 + digest 指纹复用。解决高并发、断点续跑、减少重复计算。

3. 流水线层：DeepDoc 版面解析、版面感知分块、标题‑内容向量融合、存储适配层。解决复杂文档解析，产出高质量基础向量块。

4. 高阶知识层：RAPTOR（分层摘要）、GraphRAG（知识图谱）。解决长文档全局理解、实体关系推理。

七、组件名与流程角色映射表

原文模块	在流程中的角色
document_app.py / file2document_app.py	第一步：文件上传与建档的 API 入口
task_service.py 的 queue_tasks	第二步：生产者，把大文件拆成小任务塞进队列
Redis Stream + Consumer Group	第二步：任务队列，负责传话和断点续跑
task_executor.py 的 collect / do_handle_task	第二步：消费者，真正干活的 worker
DeepDoc + rag.app.* 解析器	第三步：深度解析文档版面
naive_merge / Chunker	第三步：把解析结果切成 chunk
embedding()	第四步：把 chunk 转成向量
DocStoreConnection / Elasticsearch	第四步：把 chunk 和向量写入索引库
rag/raptor.py	进阶：RAPTOR 层次摘要
graphrag/	进阶：GraphRAG 知识图谱

八、一句话总结RAGFlow 数据注入 的核心流程

RAGFlow 的数据注入不是"上传→切分→向量化"这么简单，而是一套异步解耦、版面感知、可复用、可编排的工程体系：

• 用 DeepDoc 解决"解析质量"

• 用生产者‑消费者模型解决"并发与可靠性"

• 用 RAPTOR/GraphRAG 解决"层次化与关系化知识组织"。

RAG 的质量天花板，取决于数据注入阶段对文档的理解深度。

RAGFlow 把大量工程复杂度都藏在"数据进去"这一步，换来的是"答案出来"时的高质量和可解释性。