1. 什么是RAGFlow #

1.1 RAGFlow简介 #

RAGFlow 是一个开源的RAG（Retrieval-Augmented Generation，检索增强生成）平台。简单来说，RAGFlow可以帮助你：

• 构建知识库：将文档上传后，系统会自动解析并建立可搜索的知识库
• 智能问答：基于知识库内容回答用户问题，答案更准确、更有依据
• 文档解析：支持PDF、Word、Excel、Markdown等多种格式，解析精度高

1.2 学习目标 #

1. 理解RAGFlow deepdoc的架构：了解文档解析包含哪些模块，它们如何协作
2. 掌握视觉模块的使用：学会使用OCR、布局识别、表格识别等功能
3. 实践文档解析：能够独立编写代码解析各种格式的文档

1.3 前置知识准备 #

在学习本教程之前，建议你了解以下基础知识：

1.3.1 Python基础 #

• 熟悉Python基本语法（变量、函数、类等）
• 了解如何使用pip安装Python包
• 了解如何导入和使用第三方库

1.3.2 深度学习基础 #

• 了解什么是OCR（光学字符识别）
• 了解什么是计算机视觉模型
• 了解ONNX模型格式（简单理解为一种模型存储格式即可）

2. RAGFlow项目结构 #

2.1 项目整体架构 #

在开始使用RAGFlow之前，我们先来了解它的项目结构。这样可以帮助你理解各个模块的作用，以及它们是如何协作的。

RAGFlow项目主要包含以下几个核心模块：

.
├── api              # API接口模块，提供Web服务
├── conf             # 配置文件目录
├── deepdoc          # 文档解析核心模块（重点）
│   ├── parser       # 文档解析器（PDF、Word、Excel等）
│   └── vision       # 视觉处理模块（OCR、布局识别等）
├── rag              # RAG应用模块
│   ├── app          # 针对不同场景的解析应用
│   ├── llm          # 大语言模型相关
│   ├── nlp          # 自然语言处理
│   └── res          # 模型资源文件
└── utils.py         # 工具函数

简单理解：

• deepdoc：负责"看懂"文档（解析文档内容）
• rag/app：负责"理解"文档（针对不同场景做专门处理）
• api：负责"提供服务"（让用户可以通过接口使用功能）

2.2 文档解析的两大模块 #

文档解析功能主要分为两个层次：

2.2.1 底层模块：deepdoc #

deepdoc是文档解析的基础模块，提供最核心的解析能力：

• vision（视觉模块）：专门处理PDF等需要"看"的文档

  • OCR：识别图片中的文字
  • 布局识别：识别文档的布局结构（哪里是标题、哪里是表格等）
  • 表格识别：识别表格的结构和内容

• parser（解析模块）：处理各种格式的文档

  • PDF解析器：利用视觉模型解析PDF
  • Word解析器：解析.docx文件
  • Excel解析器：解析表格文件
  • Markdown解析器：解析Markdown文件
  • 等等

目录结构：

./deepdoc
├── parser
│   ├── docx_parser.py      # Word文档解析
│   ├── excel_parser.py     # Excel表格解析
│   ├── pdf_parser.py       # PDF文档解析（最复杂）
│   ├── markdown_parser.py  # Markdown解析
│   └── ...                 # 其他格式解析器
└── vision
    ├── ocr.py                      # OCR文字识别
    ├── layout_recognizer.py        # 布局识别
    ├── table_structure_recognizer.py  # 表格结构识别
    ├── t_ocr.py                    # OCR测试工具
    └── t_recognizer.py             # 布局/表格识别测试工具

2.2.2 应用模块：rag/app #

rag/app是在deepdoc基础上，针对特定场景做的优化：

• book.py：专门处理书籍类文档
• manual.py：专门处理手册类文档
• paper.py：专门处理论文类文档
• table.py：专门处理表格类文档
• laws.py：专门处理法律文档
• 等等

简单理解：底层模块提供"通用能力"，应用模块提供"专业能力"。

2.3 模型文件位置 #

视觉模型（OCR、布局识别等）的模型文件存放在rag/res/deepdoc目录下：

./rag/res/deepdoc
├── det.onnx              # OCR文字检测模型
├── rec.onnx              # OCR文字识别模型
├── tsr.onnx              # 表格结构识别模型
├── layout.onnx           # 通用布局识别模型
├── layout.paper.onnx     # 论文布局识别模型
├── layout.manual.onnx    # 手册布局识别模型
├── layout.laws.onnx      # 法律文档布局识别模型
└── ocr.res               # OCR字符字典

说明：

• .onnx是ONNX格式的模型文件，这是一种通用的深度学习模型格式
• 不同的布局模型针对不同场景优化，选择合适的效果更好

3. 视觉模块 #

3.1 视觉处理流程 #

当我们处理PDF文档时，系统需要"看懂"文档内容。这个过程就像人类阅读文档一样：

1. 看到文档：将PDF的每一页转换为图片
2. 识别文字：使用OCR识别图片中的文字
3. 理解布局：识别哪些是标题、哪些是正文、哪些是表格
4. 识别表格：对于表格区域，进一步识别表格的结构
5. 整合输出：将所有信息按顺序整理输出

流程图示意：

PDF文件 
  ↓
转换为图片（每页一张）
  ↓
OCR识别文字
  ↓
布局识别（识别标题、正文、表格等区域）
  ↓
表格识别（对表格区域进行详细识别）
  ↓
整合输出（按顺序输出文本、表格、图片信息）

3.2 OCR文字识别 #

3.2.1 什么是OCR #

OCR（Optical Character Recognition，光学字符识别）是指将图片中的文字识别出来，转换为可编辑的文本。

应用场景：

• 扫描件转文字
• 图片中的文字提取

• PDF中的文字识别

• 红楼梦

3.2.2 使用OCR识别PDF #

# 导入os库，进行文件和目录操作
import os
# 导入sys库，操作Python运行环境
import sys

# 将当前文件所在目录添加到Python模块搜索路径
sys.path.insert(0, os.path.abspath('.'))

# 从deepdoc.vision模块导入OCR类
from deepdoc.vision import OCR
# 从Pillow库导入Image模块进行图像处理
from PIL import Image
# 导入pdfplumber库，用于解析PDF文件
import pdfplumber
# 导入numpy库，用于处理数组
import numpy as np

# 定义需要处理的PDF文件路径
pdf_path = "./files/红楼梦.pdf"

# 打印提示信息，告知用户正在加载OCR模型
print("正在加载OCR模型...")
# 初始化OCR模型对象
ocr = OCR()
# 打印提示信息，OCR模型加载完成
print("OCR模型加载完成！")

# 打印提示信息，展示待处理的PDF文件路径
print(f"正在处理PDF文件: {pdf_path}")
# 使用pdfplumber打开PDF文件，进入上下文环境
with pdfplumber.open(pdf_path) as pdf:
    # 遍历PDF文档中的每一页
    for page_num, page in enumerate(pdf.pages):
        # 打印当前正在处理的页码
        print(f"正在处理第 {page_num + 1} 页...")

        # 设定图像缩放倍数
        zoom = 3
        # 将当前页转换为图片对象，指定图片分辨率
        img = page.to_image(resolution=72 * zoom).annotated

        # 将PIL图片对象转换为numpy数组格式，以便OCR处理
        img_array = np.array(img)

        # 执行OCR识别，device_id=0表示使用CPU
        ocr_results = ocr(img_array, device_id=0)

        # 打印当前页识别行数
        print(f"第 {page_num + 1} 页识别完成，共识别 {len(ocr_results)} 行文字")
        # 打印页码标题
        print(f"\n========== 第 {page_num + 1} 页OCR识别结果 ==========")
        # 遍历OCR识别结果，每一行为一个识别框内容，直接打印
        for i, line in enumerate(ocr_results):
            # 获取识别出的文字内容（line[1][0]）
            text = line[1][0]
            # 打印识别文本
            print(f"{i+1}. {text}")
        print()

# 打印提示信息，表示所有页面全部处理完成
print("所有页面处理完成！")

代码说明：

1. 导入模块：导入OCR类和必要的工具库
2. 初始化OCR：创建OCR对象，会自动加载模型
3. 处理PDF：使用pdfplumber打开PDF，逐页处理
4. 转换图片：将PDF页面转为图片
5. OCR识别：调用OCR模型识别文字

注意事项：

• 首次运行会自动下载模型文件（如果还没有的话）
• OCR识别结果中，表格里的文字可能没有按照表格结构组织，只是按顺序列出
• 如果需要表格结构，需要使用布局识别和表格识别功能

3.2.3 to_image #

# 导入pdfplumber库用于处理PDF文件
import pdfplumber
# 打开指定路径的PDF文件
with pdfplumber.open("./files/红楼梦.pdf") as pdf:
    # 获取PDF的第一页
    page = pdf.pages[0]
    # 将页面转换为图片对象，设置分辨率为72*2
    image_obj = page.to_image(resolution=72 * 2)

    # 获取转换后的原始图片
    original = image_obj.original
    # 获取带有标注的图片
    annotated = image_obj.annotated

    # 保存原始图片为original.png
    original.save("original.png")
    # 保存标注图片为annotated.png
    annotated.save("annotated.png")

page.to_image(resolution=72 * zoom)

• 功能：将PDF页面转换为图像
• 参数：
  • resolution：分辨率，单位是DPI（每英寸点数）
  • 72 * zoom：基础分辨率72 DPI乘以缩放因子

为什么是72？

• 72 DPI是标准屏幕分辨率（1英寸=72像素）
• zoom是缩放因子，用于控制图像清晰度
  • zoom=1 → 72 DPI（标准清晰度）
  • zoom=2 → 144 DPI（高清晰度）
  • zoom=0.5 → 36 DPI（低清晰度）

2. .annotated

• 这是 to_image() 返回对象的属性
• 它会生成一个带有PDF元素标注的图像
• 默认标注包括：
  • 文本块（用红色框标注）
  • 线条（用蓝色标注）
  • 矩形（用绿色标注）

3. 赋值给 img

• 最终得到一个PIL Image对象
• 可以进一步保存或显示

3.3 布局识别（Layout Recognition） #

3.3.1 什么是布局识别 #

布局识别是指识别文档中不同区域的类型，比如：

• 哪里是标题
• 哪里是正文
• 哪里是表格
• 哪里是图片
• 等等

为什么需要布局识别？

• 理解文档结构，按正确顺序输出内容
• 区分不同类型的区域，做专门处理
• 例如：左右两栏的文档，需要先输出左栏，再输出右栏

3.3.2 支持的布局类型 #

RAGFlow的布局识别支持10种布局组件：

1. Text：正文文本
2. Title：标题
3. Figure：配图
4. Figure caption：配图标题/说明
5. Table：表格
6. Table caption：表格标题/说明
7. Header：页头
8. Footer：页尾
9. Reference：参考引用
10. Equation：公式

3.3.3 使用布局识别 #

# 导入操作系统相关库
import os
# 导入系统相关库
import sys

# 将当前文件所在目录加入Python模块搜索路径（保证可以找到项目内部包）
sys.path.insert(0, os.path.abspath('.'))

# 从deepdoc.vision模块导入布局识别器
from deepdoc.vision import LayoutRecognizer
# 导入PIL库中的Image模块，用于图像处理
from PIL import Image
# 导入pdfplumber模块，用于PDF解析及页面渲染
import pdfplumber
# 导入numpy库用于数组操作和图片格式转换
import numpy as np

# 设置需要识别的PDF文件路径
pdf_path = "./files/红楼梦.pdf"

# 打印提示信息：加载布局识别模型
print("正在加载布局识别模型...")
# 初始化布局识别模型，这里选择"layout"代表通用模型
layout_recognizer = LayoutRecognizer("layout")
# 打印模型加载完毕的信息
print("布局识别模型加载完成！")

# 打印正在处理的PDF文件路径
print(f"正在处理PDF文件: {pdf_path}")
# 使用pdfplumber打开PDF文件，进入上下文环境管理
with pdfplumber.open(pdf_path) as pdf:
    # 遍历PDF中的每一页，page_num为页码，page为页面对象
    for page_num, page in enumerate(pdf.pages):
        # 打印当前处理的页码
        print(f"正在处理第 {page_num + 1} 页...")

        # 设置页面渲染的缩放系数（提升分辨率，增强识别效果）
        zoom = 3
        # 将PDF页对象渲染为高分辨率图片
        img = page.to_image(resolution=72 * zoom).annotated
        # 将PIL图片格式转换为numpy数组（便于后续模型处理）
        img_array = np.array(img)

        # 设置布局检测的置信度阈值
        threshold = 0.2
        # 使用布局识别模型，对本页图像进行推理，返回每个区域预测结果
        # forward()：模型推理方法 thr=0.2：只保留置信度≥0.2的检测结果，过滤低质量识别
        layouts = layout_recognizer.forward([img_array], thr=threshold)

        # 取出当前页的预测结果（只有一个图片，所以取第0个）
        page_layouts = layouts[0]

        # 打印本页检测到的区域数量
        print(f"第 {page_num + 1} 页识别到 {len(page_layouts)} 个区域：")
        # 遍历当前页所有检测出的区域
        for i, layout in enumerate(page_layouts):
            # 获取当前区域的类型（text/table/picture等），默认"Unknown"
            layout_type = layout.get("type", "Unknown")
            # 获取当前区域的边界框坐标（左上和右下） bbox：边界框坐标[x1, y1, x2, y2],默认值为[0, 0, 0, 0]
            bbox = layout.get("bbox", [0, 0, 0, 0])
            # 获取当前区域的置信度分数
            score = layout.get("score", 0.0)

            # 打印区域的类型、位置及置信度信息
            print(f"  区域 {i+1}: 类型={layout_type}, "
                  f"位置=({bbox[0]}, {bbox[1]})到({bbox[2]}, {bbox[3]}), "
                  f"置信度={score:.2f}")

结果解读：

• bbox（边界框）：用四个数字表示区域位置
  • [x0, y0, x1, y1] 表示左上角坐标(x0, y0)和右下角坐标(x1, y1)
• score（置信度）：模型对识别结果的信心程度，0-1之间，越高越可靠
• threshold（阈值）：过滤低置信度结果，建议0.2-0.5

3.4 表格识别（Table Structure Recognition） #

3.4.1 什么是表格识别 #

表格识别是在布局识别的基础上，进一步识别表格的内部结构：

• 哪些是行
• 哪些是列
• 哪些是表头
• 哪些单元格是合并的

TSR（Table Structure Recognition）的五个标签：

1. 列（column）：表格的列
2. 行（row）：表格的行
3. 列标题（column header）：列的表头
4. 行标题（row header）：行的表头
5. 合并单元格（spanning cell）：跨行或跨列的单元格

3.4.2 使用表格识别 #

重要提示：表格识别需要先通过布局识别找到表格区域，然后对表格区域图片进行识别。

# 导入os库，用于文件及路径操作
import os
# 导入sys库，用于操作Python运行环境
import sys

# 将当前项目根目录加入Python模块搜索路径，便于导入项目内部模块
sys.path.insert(0, os.path.abspath('.'))

# 从deepdoc.vision模块导入表格结构识别、布局识别和OCR类
# LayoutRecognizer：文档布局分析  识别文本块、表格、图片等区域 参数"layout"指定模型类型
# TableStructureRecognizer表格结构识别 识别表格的行、列、单元格 输出表格的逻辑结构
from deepdoc.vision import TableStructureRecognizer, LayoutRecognizer
# 导入PIL库的Image模块，用于图像处理
from PIL import Image
# 导入pdfplumber用于PDF解析及页面图像渲染
import pdfplumber
# 导入numpy用于数组处理
import numpy as np

# 定义需要处理的PDF文件路径
pdf_path = "./files/红楼梦.pdf"

# 打印提示信息，告知用户正在加载模型
print("正在加载模型...")
# 初始化布局识别模型
layout_recognizer = LayoutRecognizer("layout")
# 初始化表格结构识别模型
table_recognizer = TableStructureRecognizer()
# 打印提示，模型加载完成
print("模型加载完成！")

# 打印正在处理的PDF文件路径
print(f"正在处理PDF文件: {pdf_path}")
# 使用pdfplumber打开PDF文件
with pdfplumber.open(pdf_path) as pdf:
    # 遍历PDF每一页，page_num为页码，page为页面对象
    for page_num, page in enumerate(pdf.pages):
        # 打印当前处理的页码
        print(f"正在处理第 {page_num + 1} 页...")

        # 设置缩放倍数，提高图片分辨率
        zoom = 3
        # 将PDF页渲染为高分辨率图片，annotated获取标注版PIL图片对象
        img = page.to_image(resolution=72 * zoom).annotated
        # 将PIL图片对象转换为numpy数组 多数深度学习框架（如PyTorch, TensorFlow）使用numpy数组作为输入
        img_array = np.array(img)

        # 打印提示，开始页面布局识别
        print("  步骤1: 识别页面布局...")
        # 使用布局识别模型对页面图像进行推理，返回所有区域
        # [img_array]：输入图像列表（支持批量）
        # thr=0.2：置信度阈值（20%以上认为是有效区域）
        layouts = layout_recognizer.forward([img_array], thr=0.2)
        # 获取当前页的预测结果
        page_layouts = layouts[0]

        # 过滤出所有类型为"table"的区域（即表格区域）
        table_regions = [layout for layout in page_layouts 
                        if layout.get("type", "").lower() == "table"]

        # 打印找到的表格区域数量
        print(f"  找到 {len(table_regions)} 个表格区域")

        # 对每一个表格区域进行结构识别
        for table_idx, table_region in enumerate(table_regions):
            # 打印当前正在处理的表格编号
            print(f"  步骤2: 识别表格 {table_idx + 1} 的结构...")

            # 获取表格区域的边界框坐标（左上x0,y0，右下x1,y1）
            # PIL坐标：(左, 上, 右, 下)
            bbox = table_region.get("bbox", [0, 0, 0, 0])
            # x0 = 左边界, y0 = 上边界, x1 = 右边界, y1 = 下边界
            x0, y0, x1, y1 = bbox

            # 从原页面图片中裁剪出该表格区域
            # 注意PIL的crop坐标为(左,上,右,下)
            table_img = img.crop((x0, y0, x1, y1))
            # 转换为numpy数组格式
            table_img_array = np.array(table_img)

            # 使用表格结构识别模型识别裁剪出的表格图片
            table_structure = table_recognizer([table_img_array], thr=0.2)

            # table_structure为列表，每个元素是一个表格的结构信息字典
            if table_structure:
                # 取出第一个（因为这里只裁剪了一个表格区域）
                table_info = table_structure[0]
                # 打印识别到的表格组件数量
                print(f"    识别到 {len(table_info)} 个表格组件")

                # 打印表格编号说明
                print(f"\n表格 {table_idx + 1} 结构信息：\n")
                # 遍历并打印每个表格组件信息
                for i, component in enumerate(table_info):
                    # 组件类型（如cell/row/column等），若无默认Unknown
                    label = component.get("label", "Unknown")
                    # 左上角x坐标
                    x0_comp = component.get("x0", 0)
                    # 上边界y坐标
                    y0_comp = component.get("top", 0)
                    # 右下角x坐标
                    x1_comp = component.get("x1", 0)
                    # 下边界y坐标
                    y1_comp = component.get("bottom", 0)
                    # 置信度分数
                    score = component.get("score", 0.0)

                    # 打印当前表格组件的详细信息
                    print(f"组件 {i+1}:")
                    print(f"  类型: {label}")
                    print(f"  位置: ({x0_comp}, {y0_comp}) 到 ({x1_comp}, {y1_comp})")
                    print(f"  置信度: {score:.2f}\n")

代码说明：

1. 加载模型：需要三个模型（布局识别、表格识别、OCR）
2. 布局识别：先找到表格区域
3. 裁剪表格：从原图中提取表格区域
4. 表格识别：识别表格的内部结构
5. 保存结果：保存表格结构信息

注意事项：

• 表格识别需要先进行布局识别，找到表格区域
• 表格识别是对表格区域图片进行的，不是对整个页面
• 如果需要表格的文字内容，还需要结合OCR识别

(0,0) ┌─────────────────────────┐
      │                         │
      │     [表格区域]           │
      │     x0,y0┌──────┐       │
      │          │      │       │
      │          │      │       │
      │          └──────┘x1,y1  │
      │                         │
      └─────────────────────────┘ (width,height)


开始
  ↓
加载PDF文件（pdfplumber.open）
  ↓
遍历每一页
  ↓
渲染为高分辨率图像（page.to_image）
  ↓
布局识别（LayoutRecognizer）
  ↓
筛选表格区域（type == "table"）
  ↓
对每个表格区域：
  ├─ 裁剪表格图像
  ├─ 表格结构识别（TableStructureRecognizer）
  └─ 保存结构信息到文本文件
  ↓
处理下一页...
  ↓
完成所有页面
  ↓
输出总结信息

4. 识别表格文字 #

在进行视觉表格识别后，如果我们希望获取表格中的文字内容，就需要结合OCR（光学字符识别）技术。下面简要说明整体流程：

1. 定位表格区域（布局识别）
   利用布局分析模型，识别页面中各个区域（如正文、表格、图片等），并提取出 type == "table" 的区域，得到其边界框（bbox坐标）。

2. 图像裁剪
   使用提取到的坐标，在原始页面图片上裁剪出表格对应的图片区域。

3. 表格OCR识别
   将裁剪得到的表格区域图片输入OCR模型进行文字识别。OCR会返回该区域内检测到的所有文字及其位置信息。

4. 结果输出
   可以按表格编号分组，输出每个表格的文字内容。高级用法甚至可以进一步结合结构识别还原为带行列结构的表格（详见下节进阶用法）。

典型代码结构如下：

• 初始化所需模型（OCR及布局识别）。
• 循环遍历PDF页面，对每一页：
  • 渲染为图像，布局识别定位表格区域；
  • 对每个表格区域，裁剪区域图片并做OCR识别；
  • 保存或打印所有结果。

这样就可以实现文档级表格文字内容的自动提取。

# 导入os模块，进行文件和路径操作
import os
# 导入sys模块，进行Python解释器相关操作
import sys

# 将当前目录（项目根目录）加入到模块搜索路径
sys.path.insert(0, os.path.abspath('.'))

# 从deepdoc.vision模块导入OCR和布局识别器
from deepdoc.vision import OCR, LayoutRecognizer
# 导入pdfplumber库，用于PDF页面渲染和解析
import pdfplumber
# 导入numpy库，用于数组和图像的转换操作
import numpy as np

# 指定待处理的PDF文件路径
pdf_path = "./files/红楼梦.pdf"

# 打印提示：正在加载模型，首次启动可能用时较长
print("正在加载模型（这可能需要一些时间）...")
# 初始化OCR识别器
ocr = OCR()
# 初始化通用布局识别器（用于定位表格区域）
layout_recognizer = LayoutRecognizer("layout")
# 打印提示：所有模型加载完成
print("所有模型加载完成！")

# 打印当前处理的PDF文件路径
print(f"正在处理PDF文件: {pdf_path}")
# 使用pdfplumber打开PDF文件，进入上下文
with pdfplumber.open(pdf_path) as pdf:
    # 遍历PDF中的每一页，获取页码和页面对象
    for page_num, page in enumerate(pdf.pages):
        # 打印正在处理的页码
        print(f"\n========== 处理第 {page_num + 1} 页 ==========")

        # 设置渲染缩放倍数提升分辨率
        zoom = 3
        # 渲染当前页为高分辨率图片（PIL对象）
        img = page.to_image(resolution=72 * zoom).annotated
        # 将PIL图片转换为numpy数组，便于模型处理
        img_array = np.array(img)

        # 步骤1: 布局识别，用于定位表格区域
        print("步骤1: 布局识别（定位表格区域）...")
        # 调用布局识别模型进行推理，获得所有区域信息
        layouts = layout_recognizer.forward([img_array], thr=0.2)
        # 取出当前页的布局区域列表
        page_layouts = layouts[0]

        # 提取所有类型为table的区域
        table_regions = [layout for layout in page_layouts 
                       if layout.get("type", "").lower() == "table"]

        # 存储所有表格的OCR结果
        table_ocr_results = []

        # 如果存在表格，则进行OCR识别
        if table_regions:
            print(f"  找到 {len(table_regions)} 个表格区域")
            print("步骤2: 对表格进行OCR文字识别...")

            # 遍历每个表格区域，进行OCR识别
            for table_idx, table_region in enumerate(table_regions):
                # 获取表格的边界框，格式为[x0, y0, x1, y1]
                bbox = table_region.get("bbox", [0, 0, 0, 0])
                x0, y0, x1, y1 = bbox
                # 从整页图片中裁剪出表格对应区域
                table_img = img.crop((x0, y0, x1, y1))
                # 将裁剪得到的表格图片转为numpy数组
                table_img_array = np.array(table_img)

                # 对表格区域进行OCR识别
                table_ocr = ocr(table_img_array, device_id=0)
                # 存储表格OCR结果
                table_ocr_results.append({
                    "table_idx": table_idx + 1,
                    "ocr_results": table_ocr
                })
                print(f"  表格 {table_idx + 1}: OCR识别到 {len(table_ocr)} 行文字")
        else:
            print("  未找到表格区域")

        # 输出表格OCR识别结果
        if table_ocr_results:
            print(f"\n========== 第 {page_num + 1} 页表格文字 ==========")
            for table_info in table_ocr_results:
                print(f"\n表格 {table_info['table_idx']}:")
                # 遍历表格OCR识别条目，按序号打印文本内容
                for i, line in enumerate(table_info['ocr_results']):
                    text = line[1][0]
                    print(f"  {i+1}. {text}")
            print()

5. 视觉解决方案的局限性 #

5.1 模型性能的局限性 #

视觉模型是通过大量图片训练出来的，它的性能取决于训练数据的多样性。因此：

可能遇到的问题：

• 特殊表格样式：如果遇到训练时没见过的表格样式，识别效果可能不好
• 复杂布局：非常规的文档布局可能识别不准确
• 低质量图片：模糊、倾斜的图片会影响识别效果

解决方案：

1. 调整阈值：降低置信度阈值，保留更多结果
2. 使用专用模型：针对特定场景使用专用模型（如论文用layout.paper.onnx）
3. 后处理优化：对识别结果进行人工校验或规则修正

5.2 性能优化建议 #

1. 选择合适的模型：

   • 通用文档：使用layout.onnx
   • 论文：使用layout.paper.onnx
   • 手册：使用layout.manual.onnx
   • 法律文档：使用layout.laws.onnx

2. 调整参数：

   • threshold：置信度阈值，根据实际情况调整
   • zoom：PDF转图片的放大倍数，影响识别精度和速度

3. 批量处理优化：

   • 对于大量文档，可以考虑使用GPU加速
   • 使用多进程或多线程并行处理

6. 环境配置与依赖安装 #

6.1 必需的Python包 #

在使用RAGFlow的视觉模块之前，需要安装以下依赖：

# 基础依赖
pip install pypdf==5.0.0 beartype trio

# 如果有GPU，安装GPU版本的onnxruntime（速度更快）
pip install onnxruntime-gpu

# 如果没有GPU，安装CPU版本
pip install onnxruntime

# 图像处理
pip install Pillow pdfplumber

# 其他依赖
pip install numpy opencv-python

6.2 模型文件 #

模型文件会自动从HuggingFace下载到rag/res/deepdoc目录。如果下载速度慢，可以：

Linux系统：

export HF_ENDPOINT=https://hf-mirror.com

Windows系统： 在代码中设置环境变量，或使用代理。

6.3 验证安装 #

运行以下代码验证安装是否成功：

# 测试代码：验证RAGFlow视觉模块是否可以正常导入和使用
import sys
import os

# 添加项目路径
sys.path.insert(0, os.path.abspath('.'))

try:
    # 尝试导入模块
    from deepdoc.vision import OCR, LayoutRecognizer
    print("✓ 模块导入成功")

    # 尝试初始化OCR（会加载模型，可能需要一些时间）
    print("正在初始化OCR模型（首次运行会下载模型）...")
    ocr = OCR()
    print("✓ OCR模型初始化成功")

    # 尝试初始化布局识别模型
    print("正在初始化布局识别模型...")
    layout = LayoutRecognizer("layout")
    print("✓ 布局识别模型初始化成功")

    print("\n========== 所有测试通过！环境配置正确 ==========")

except Exception as e:
    print(f"✗ 错误: {e}")
    print("请检查：")
    print("1. 是否安装了所有必需的Python包")
    print("2. 项目路径是否正确")
    print("3. 模型文件是否完整")