# Ragflow-Plus 文档处理流水线教程

本文档详细介绍了 Ragflow-Plus 的文档处理流水线系统。该流水线负责接收、解析和索引文档到知识库，处理从原始文件上传到智能内容提取、嵌入生成和可搜索索引存储的完整工作流。系统支持多种文档格式，包括 PDF、Word、Excel、PowerPoint、图像和纯文本文件，利用 MinerU 库进行高级文档解析和 OCR 功能。

有关知识库管理和管理的详细信息，请参阅 知识库管理系统。有关使用这些已处理文档的 RAG 检索过程的详细信息，请参阅 RAG 引擎与搜索。

1. 流水线概述 #

文档处理流水线由多个集成阶段组成，将上传的文件转换为适合检索增强生成的可搜索索引内容。

1.1 核心处理流程 #

文件上传 (File Upload)
         ↓
文档解析器 (perform_parse())
         ↓
MinerU 引擎 (MinerU Engine)
         ↓
OCR 分类 (ds.classify())
         ↓
处理模式选择 (Processing Mode)
    ↙              ↘
OCR 模式         文本模式
(pipe_ocr_mode)  (pipe_txt_mode)
    ↓              ↓
内容提取 (get_content_list())
         ↓
分块处理 (Chunk Processing)
    ↙              ↘
向量生成         文本分词
(Embedding)      (tokenize_text)
    ↓              ↓
Elasticsearch   Elasticsearch
存储            索引
    ↓
MinIO 图像存储

1.2 处理阶段说明 #

文档处理流水线包含以下主要阶段：

1. 文件上传与存储：文件通过管理界面上传，存储在 MinIO 中，元数据记录在 MySQL 中
2. 文档解析引擎：使用 MinerU 进行智能文档处理，支持 OCR 和多格式支持
3. 内容提取与分块：从解析结果中提取结构化块，包含文本、表格、公式和图像
4. 嵌入生成：将文本块转换为向量表示，用于语义搜索
5. 存储与索引：处理后的内容存储在 Elasticsearch 中，支持动态模式管理

2. 文件上传与存储 #

流水线从通过管理界面的文件上传开始，文件存储在 MinIO 中，元数据记录在 MySQL 中。

2.1 文件上传流程 #

文件上传过程在多个数据库表中创建记录，以维护文件、文档和知识库之间的关系。文件使用 parent_id 作为存储桶名称，文件名作为对象键存储在 MinIO 存储桶中。

2.2 存储架构 #

┌─────────────────────────────────────────┐
│      文件上传层 (File Upload Layer)        │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │ 管理界面  │  │ API 路由 │  │ 文件 │  │
│  │          │  │          │  │ 服务 │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────┐
│      存储层 (Storage Layer)                │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │ MinIO    │  │ MySQL    │  │ ES   │  │
│  │ 文件存储 │  │ 元数据    │  │ 索引 │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘

3. 文档解析引擎 #

解析引擎利用 MinerU 进行智能文档处理，支持 OCR 功能和多格式支持。

3.1 解析器选择与初始化 #

解析器选择逻辑在 perform_parse() 中实现，根据文档特征支持不同的处理模式。对于扫描的 PDF 和图像，自动选择 OCR 模式，而对于可提取文本的文档，使用文本模式。

3.2 文件类型处理流程 #

doc_info
    ↓
File Type?
    ↙    ↘    ↘    ↘
PDF  Word/PPT Excel Image
    ↓    ↓    ↓    ↓
解析器选择
    ↓
处理模式检测
    ↙    ↘
OCR  文本模式
模式
    ↓
内容提取

3.3 MinerU 集成组件 #

系统集成了多个 MinerU 组件，用于全面的文档分析：

组件	用途	说明
PymuDocDataset	PDF 文档分析	PDF 文档数据集处理
FileBasedDataReader	文件内容读取	读取文件内容
FileBasedDataWriter	图像提取	提取并写入图像
doc_analyze	文档结构分析	分析文档结构
read_local_office	Office 文档处理	处理 Word/PPT 文档
read_local_images	图像文档处理	处理图像文档

3.4 处理模式选择 #

系统根据文档类型和内容特征自动选择处理模式：

• OCR 模式：用于扫描的 PDF 和图像文件
• 文本模式：用于包含可提取文本的文档
• 表格格式：用于 Excel 文件，保持表格结构

4. 内容提取与分块 #

内容提取过程产生包含文本、表格、公式和图像的结构化块，并带有位置元数据。

4.1 内容提取流程 #

pipe_result
    ↙              ↘
get_content_list  get_middle_json
    ↓              ↓
For each chunk   Extract block_info_list
    ↓              ↓
内容类型分类      Extract page_idx + bbox
    ↙    ↘    ↘    ↘    ↓
Text Table Eq Image  Map to content chunks
    ↓    ↓    ↓    ↓
处理    处理  处理  上传到MinIO
    ↓    ↓    ↓    ↓
准备嵌入生成

4.2 分块类型与处理 #

分块过程通过从 MinerU 中间 JSON 输出中提取边界框坐标并将它们映射到内容块来维护空间关系。这实现了精确的文档导航和引用。

分块类型	处理方法	存储格式
文本	Markdown 符号过滤	纯文本内容
表格	标题 + 正文 HTML	HTML 表格结构
公式	直接文本提取	LaTeX/文本格式
图像	MinIO 上传 + URL 生成	MinIO 对象引用

4.3 空间关系维护 #

系统通过以下方式维护文档的空间关系：

• 页面索引：记录每个块所在的页面
• 边界框坐标：记录块在页面中的位置
• 位置信息：记录块在文档中的顺序位置

5. 嵌入生成 #

嵌入生成过程将文本块转换为向量表示，用于语义搜索功能。

5.1 嵌入生成流程 #

嵌入系统支持多个提供程序，并根据端点 URL 自动检测适当的 API 格式。向量维度根据预期的模型输出进行验证，以确保一致性。

5.2 嵌入配置 #

嵌入配置由知识库设置确定，支持动态模型选择：

配置项	来源	默认值
llm_name	知识库 embd_id	bge-m3
api_base	嵌入配置	http://localhost:11434
api_key	嵌入配置	可选

5.3 向量维度管理 #

系统支持不同嵌入模型的向量维度，并动态创建相应的向量字段：

• 动态字段创建：根据嵌入模型维度创建向量字段
• 多模型支持：同一租户内可共存多个嵌入模型
• 维度验证：验证向量维度与模型输出的一致性

6. 存储与索引 #

处理后的内容存储在 Elasticsearch 中，支持不同嵌入维度的动态模式管理。

6.1 索引管理流程 #

Chunk + Embedding
    ↓
Prepare ES Document
    ↓
Index Exists?
    ↙              ↘
No                Yes
    ↓              ↓
Create Index     Vector Field Exists?
    ↓              ↙              ↘
Set Mapping     No                Yes
    ↓              ↓              ↓
Index Doc       Add Field      Index Doc
    ↓              ↓              ↓
Update chunk statistics
    ↓
Create task record

6.2 Elasticsearch 文档结构 #

Elasticsearch 索引使用基于租户的命名方案（ragflow_{tenant_id}），并根据嵌入模型维度动态创建向量字段。这允许同一租户内共存多个嵌入模型。

6.3 文档模式 #

Elasticsearch 文档模式包括可搜索内容和向量表示：

文本字段：

• docnm_kwd：文档名称关键词
• title_tks：标题分词
• content_with_weight：带权重的内容
• content_ltks：内容分词

空间字段：

• page_num_int：页码
• position_int：位置
• top_int：顶部位置

向量字段：

• q_embedding_dim_vec：嵌入向量（维度动态）

元数据字段：

• create_time：创建时间
• create_timestamp_flt：创建时间戳
• img_id：图像 ID

7. 进度跟踪与状态管理 #

流水线包括全面的进度跟踪，具有实时更新和错误处理。

7.1 进度跟踪流程 #

Parse Start
    ↓
Update Status → Document table
    ↓
MinerU stdout/stderr
    ↓
Capture Progress
    ↓
Filter Progress Keywords
    ↓
Rate Limit Updates
    ↓
Update Progress Message
    ↓
Parse Complete/Error
    ↓
Final Status Update
    ↙              ↘
Update Chunk Count  Create Task Record

7.2 状态值 #

系统使用以下状态值跟踪文档处理进度：

文档状态：

• status: 0 = 待处理 (Pending)
• status: 1 = 完成 (Complete)
• status: 2 = 处理中 (Processing)

运行状态：

• run: 0 = 失败 (Failed)
• run: 1 = 运行中 (Running)
• run: 3 = 成功 (Success)

7.3 进度关键词与过滤 #

系统监控 MinerU 输出中的特定关键词，以识别有意义的进度更新：

关键词模式	用途	示例
Predict:	OCR 进度	模型预测状态
`%\	`	进度条	完成百分比
Processing pages:	页面处理	当前处理的页面
OCR-, MFD, MFR	组件状态	特定 OCR 组件
Table	表格提取	表格处理进度

7.4 实时进度更新 #

进度跟踪系统实时捕获 MinerU 输出，并使用有意义的进度指示器更新数据库。这使得前端能够向用户显示实时解析状态。

8. 错误处理与恢复 #

系统包含全面的错误处理机制，确保文档处理的可靠性。

8.1 错误类型 #

系统处理以下类型的错误：

• 解析错误：文档解析失败
• 嵌入错误：向量生成失败
• 存储错误：索引存储失败
• 网络错误：外部服务连接失败

8.2 错误恢复策略 #

• 重试机制：自动重试失败的步骤
• 错误记录：详细记录错误信息
• 状态更新：更新文档状态为失败
• 用户通知：通知用户处理失败

9. 性能优化 #

系统采用多种性能优化策略，提高文档处理效率。

9.1 优化策略 #

• 并行处理：多线程处理多个文档
• 批量操作：批量索引文档块
• 缓存机制：缓存常用数据
• 资源管理：合理分配计算资源

9.2 性能指标 #

系统监控以下性能指标：

• 处理时间：文档处理总时间
• 吞吐量：单位时间处理的文档数
• 资源使用：CPU、内存、GPU 使用率
• 错误率：处理失败的比例

10. 总结 #

文档处理流水线是 Ragflow-Plus 的核心系统，负责将原始文档转换为可搜索的知识库内容。通过集成 MinerU、支持多种文档格式、智能分块和向量化，系统能够高效处理各种类型的文档，为 RAG 检索提供高质量的知识库基础。

关键特性：

• 多格式支持：PDF、Word、Excel、PowerPoint、图像、文本等
• 智能解析：MinerU OCR 和版面分析
• 灵活分块：支持文本、表格、公式、图像等多种分块类型
• 动态索引：支持多种嵌入模型和向量维度
• 实时跟踪：全面的进度跟踪和状态管理
• 错误恢复：完善的错误处理和恢复机制

有关使用处理后的文档进行 RAG 检索的详细信息，请参阅 RAG 引擎与搜索。