结构化 PDF 解析器

使用 StructuredPDFParser 的综合指南。

概述

StructuredPDFParser 是 Doctra 中的基础解析器，设计用于通用 PDF 文档处理。它结合了布局检测、OCR 和可选的 VLM 集成，从 PDF 文档中提取所有内容。

主要特性

• 布局检测：基于 PaddleOCR 的文档结构分析
• OCR 处理：从所有文档元素中提取文本
• 视觉元素提取：自动裁剪图形、图表和表格
• VLM 集成：可选的结构化数据提取
• 分割表格合并：自动检测和合并跨页分割的表格
• 多种输出格式：Markdown、HTML、Excel、JSON

基本用法

from doctra import StructuredPDFParser

# 使用默认值初始化解析器
parser = StructuredPDFParser()

# 解析文档
parser.parse("document.pdf")

配置

有关详细参数文档，请参阅 API 参考。

分割表格合并

StructuredPDFParser 包含一个高级功能，可以自动检测和合并跨多个页面分割的表格。这对于处理财务报告、数据表格和其他大型表格跨页面边界的文档特别有用。

工作原理

分割表格检测使用两阶段方法，结合空间启发式方法和结构分析：

阶段 1：邻近检测

系统首先使用基于位置的启发式方法识别候选表格对：

1. 位置检查：
2. 第一个表格段必须接近其页面底部（默认在 20% 以内）

3. 第二个表格段必须接近下一页的顶部（默认在 15% 以内）

4. 水平对齐：

5. 表格必须具有显著的水平重叠（至少 50%）

6. 这确保它们在页面上垂直对齐

7. 间隙分析：

8. 测量第一个表格结束和第二个表格开始之间的间隙
9. 间隙考虑分页、页眉和页脚

10. 默认最大允许间隙为页面高度的 25%

11. 宽度相似性：

12. 两个表格段必须具有相似的宽度（差异在 20% 以内）
13. 这确保它们属于同一个表格结构

阶段 2：结构验证

一旦邻近检查通过，系统使用 OpenCV 的 **LSD（线段检测器）**执行更深层的结构分析：

1. 列检测：
2. LSD 检测两个表格段中的垂直线
3. 这些线代表列边界

4. 算法是自适应的，适用于不同的表格结构，无需参数调整

5. 列数匹配：

6. 系统比较两个段中检测到的列数

7. 容差基于表格大小自适应：

   • 小表格（≤5 列）：允许 1 列差异
   • 中等表格（6-10 列）：允许 2 列差异
   • 大型表格（11-20 列）：允许 15% 差异或最少 3 列

8. 列对齐：

9. 比较段之间列的相对位置
10. 至少 60% 的列必须在容差内对齐（默认 10 像素）

11. 这确保结构连续性

12. 置信度评分：

13. 基于以下因素计算置信度分数（0-1）：
    • 列数匹配
    • 列对齐质量
    • 宽度相似性
    • 重叠比率
14. 只有置信度 ≥ 0.65（默认）的匹配才会被合并

回退机制

系统包含针对边缘情况的智能回退：

• 检测到太多列：如果 LSD 检测到 >20 列，可能表示噪声（水平线、文本边界）。系统回退到基于邻近的匹配，置信度较低。

• 未检测到列：对于无边框表格或图像质量差的情况，如果在任一段中未检测到列，系统使用基于邻近的匹配。

• 噪声过滤：系统过滤掉太靠近图像边缘的列（可能是伪影）。

启用分割表格合并

from doctra import StructuredPDFParser

# 使用默认设置启用分割表格合并
parser = StructuredPDFParser(
    merge_split_tables=True
)

# 解析文档 - 分割表格将自动合并
parser.parse("document.pdf")

配置选项

parser = StructuredPDFParser(
    merge_split_tables=True,

    # 位置阈值
    bottom_threshold_ratio=0.20,  # 距离页面底部 20%
    top_threshold_ratio=0.15,     # 距离页面顶部 15%

    # 间隙容差
    max_gap_ratio=0.25,            # 页面高度的 25% 最大间隙

    # 结构验证
    column_alignment_tolerance=10.0,  # 列对齐的像素容差
    min_merge_confidence=0.65,       # 合并的最小置信度（0-1）
)

参数详情

参数	默认值	描述
merge_split_tables	False	启用/禁用分割表格检测
bottom_threshold_ratio	0.20	检测页面底部附近表格的比率（0-1）
top_threshold_ratio	0.15	检测页面顶部附近表格的比率（0-1）
max_gap_ratio	0.25	表格之间的最大允许间隙（考虑页眉/页脚）
column_alignment_tolerance	10.0	列对齐验证的像素容差
min_merge_confidence	0.65	合并表格所需的最小置信度分数（0-1）

输出

当检测到并合并分割表格时：

• 合并图像：创建单个合成图像，组合两个表格段
• Markdown 输出：合并的表格在 markdown 中出现一次，并带有指示它跨多个页面的注释
• HTML 输出：与 markdown 类似，合并的表格作为单个元素出现
• 文件位置：合并的表格保存为 tables/ 目录中的 merged_table_{page1}_{page2}.png

示例输出注释：

📊 Table (merged from pages 1-2, confidence: 0.75)

何时使用

在以下情况下启用分割表格合并：

• 处理包含跨多个页面的大型表格的文档
• 处理财务报告、数据表格或结构化文档
• 您希望在单个视图中获得完整的表格上下文
• 表格经常跨页面边界分割

在以下情况下考虑禁用：

• 表格在页面之间是故意分开的
• 处理速度至关重要（会增加少量开销）
• 文档结构不一致

技术详情

算法：检测使用 OpenCV 的 LSD（线段检测器），它是： - 自适应的：适用于不同的表格结构，无需参数调整 - 鲁棒的：处理各种线条样式（实线、虚线、部分断开） - 高效的：快速处理，适合批量操作

预处理：在列检测之前，图像经过： - 灰度转换 - 对比度增强（CLAHE） - 二进制阈值化（OTSU） - 形态学操作以连接断开的线

聚类：检测到的线段使用基于图像宽度的自适应阈值进行聚类，确保同一列边界的多次检测合并为单个列标记。

有关完整的详细说明（包括可视化架构和示例），请参阅分割表格合并指南。

输出结构

outputs/
└── document/
    └── full_parse/
        ├── result.md
        ├── result.html
        └── images/

何时使用

在以下情况下使用 StructuredPDFParser：

• 通用 PDF 处理
• 高质量文档
• 不需要图像恢复时
• 提取所有内容类型

另请参阅

• 分割表格合并 - 自动表格合并的详细指南
• 增强解析器 - 带图像恢复
• 图表和表格提取器 - 专注提取
• API 参考 - 完整 API 文档