金融文档处理统一框架

参考 MinerU 实现的模型统一框架，针对金融场景设计。

支持场景

场景类型	特点	表格形式
银行交易流水	单栏列表形式，无合并单元格	有线表格 / 无线表格
财务报表	多栏列表形式，有合并单元格，表头复杂	有线表格 / 无线表格

模型选择

模型类型	推荐模型	说明
方向分类	PP-LCNet_x1_0_doc_ori	paddle onnx格式的模型
版式检测	Docling Layout / DocLayout-YOLO	Docling 或 MinerU 模型
文字识别	PaddleOCR (PyTorch)	效果好，支持角度校正
表格结构识别	MinerU VLM / PaddleOCR-VL / UNET 有线表格	VLM 返回 HTML 结构
公式识别	MinerU VLM	返回 LaTeX
单元格坐标匹配	TableCellMatcher	OCR 检测框与 VLM 结构匹配

处理流程

主流程图

graph TB
    A[输入 PDF/图片] --> B[加载文档并分类]
    
    B --> C{文档类型?}
    C -->|PDF| D[PDF分类: 扫描件/数字原生]
    C -->|图片目录| E[加载所有图片]
    
    D --> F[处理每一页]
    E --> F
    
    F --> G[页面方向识别<br/>仅扫描件]
    G --> H[Layout 检测]
    
    H --> I[去重重叠框]
    I --> J{大文本块转表格?}
    J -->|启用| K[后处理转换]
    J -->|否| L
    K --> L[整页 OCR<br/>获取所有 text spans]
    
    L --> M[Span 去重与排序]
    M --> N[Span-Block 匹配<br/>SpanMatcher]
    
    N --> O[元素分类]
    O --> P[处理各类元素]
    
    P --> Q[按阅读顺序排序]
    Q --> R[坐标转换回原图]
    
    R --> S{所有页处理完?}
    S -->|否| F
    S -->|是| T[跨页表格合并]
    
    T --> U[输出结果]
    
    style L fill:#e1f5ff
    style N fill:#e1f5ff
    style P fill:#fff4e1

单页处理详细流程

graph TB
    A[输入：页面图像] --> B{PDF类型?}
    
    B -->|扫描件| C[页面方向识别<br/>PP-LCNet]
    B -->|数字PDF| D
    C --> D[Layout 检测<br/>Docling/MinerU/DiT]
    
    D --> E[去重重叠框<br/>IoU过滤]
    E --> F{大文本块转表格?}
    
    F -->|是| G[面积占比判断<br/>转换为table类型]
    F -->|否| H
    G --> H[整页 OCR<br/>获取所有 text spans]
    
    H --> I[Span 去重<br/>IoU过滤]
    I --> J[Span 排序<br/>从上到下、从左到右]
    J --> K[Span-Block 匹配<br/>overlap_threshold=0.5]
    
    K --> L[元素分类]
    
    L --> L1[文本类]
    L --> L2[表格类]
    L --> L3[图片类]
    L --> L4[公式类]
    L --> L5[代码类]
    L --> L6[丢弃类]
    
    L1 --> M[处理文本元素]
    L2 --> N[处理表格元素]
    L3 --> O[处理图片元素]
    L4 --> P[处理公式元素]
    L5 --> Q[处理代码元素]
    L6 --> R[处理丢弃元素]
    
    M --> S[合并所有结果]
    N --> S
    O --> S
    P --> S
    Q --> S
    R --> S
    
    S --> T[按阅读顺序排序]
    T --> U[坐标转换回原图]
    
    style H fill:#e1f5ff
    style K fill:#e1f5ff
    style L fill:#fff4e1
    style L1 fill:#fff4e1
    style L2 fill:#fff4e1
    style L3 fill:#fff4e1
    style L4 fill:#fff4e1
    style L5 fill:#fff4e1
    style L6 fill:#fff4e1

关键改进：整页 OCR + Span 匹配

参考 MinerU 的处理方式，新流程采用 整页 OCR → Span-Block 匹配 策略：

整页 OCR：先对整个页面进行 OCR，获取所有 text spans（包含坐标和文本）
Span 去重：移除高 IoU 重叠的 spans，保留置信度高的
Span 排序：按坐标排序（从上到下，从左到右），方便人工检查缺失字符
Span-Block 匹配：将 OCR spans 按重叠比例（默认0.5）匹配到对应的 layout blocks
文本合并：将匹配到同一 block 的 spans 按阅读顺序合并

优势：

✅ 避免裁剪小图 OCR 失败的问题
✅ OCR 可以利用更多上下文信息
✅ 坐标更精确（整页坐标系）
✅ 减少重复 OCR 调用，提高效率
✅ 与 MinerU 处理方式一致

代码实现：

# 1. 整页 OCR
all_ocr_spans = self.ocr_recognizer.recognize_text(detection_image)

# 2. 去除重复 spans
all_ocr_spans = SpanMatcher.remove_duplicate_spans(all_ocr_spans)

# 3. 按坐标排序
all_ocr_spans = self._sort_spans_by_position(all_ocr_spans)

# 4. 将 OCR spans 匹配到 layout blocks
matched_spans = SpanMatcher.match_spans_to_blocks(
    all_ocr_spans, layout_results, overlap_threshold=0.5
)

# 5. 在元素处理时使用预匹配的 spans
element = self.element_processors.process_text_element(
    detection_image, item, pdf_type, pdf_doc, page_idx, scale,
    pre_matched_spans=matched_spans.get(block_idx, [])
)

表格处理流程

表格处理支持两种路径：有线表格（UNET） 和 无线表格（VLM）

graph TB
    A[表格区域] --> B[表格 OCR 预处理]
    
    subgraph OCR预处理
        B --> B1[裁剪表格区域<br/>padding=10px]
        B1 --> B2[表格方向检测<br/>PP-LCNet]
        B2 --> B3{有整页OCR spans?}
        B3 -->|是| B4[提取重叠spans<br/>转换坐标到裁剪区域]
        B3 -->|否| B5[裁剪区域单独OCR<br/>兜底方案]
        B4 --> B6[OCR框列表]
        B5 --> B6
    end
    
    B6 --> C{使用有线表格?}
    
    C -->|是| D[UNet 有线表格路径]
    C -->|否| E[VLM 无线表格路径]
    
    subgraph 有线表格路径
        D --> D1[UNet 检测表格线<br/>横线 + 竖线]
        D1 --> D2{启用倾斜矫正?}
        D2 -->|是| D3[Hough变换检测角度<br/>矫正图片和OCR坐标]
        D2 -->|否| D4
        D3 --> D4[网格恢复<br/>grid_recovery.py]
        D4 --> D5[边缘过滤<br/>edge_margin=padding×upscale×1.2]
        D5 --> D6[文本填充<br/>text_filling.py]
        D6 --> D7[生成HTML<br/>data-bbox属性]
        D7 --> D8{识别成功?}
        D8 -->|否| E[自动Fallback到VLM]
        D8 -->|是| F
    end
    
    subgraph 无线表格路径
        E --> E1[VLM识别表格结构<br/>返回HTML]
        E1 --> E2[TableCellMatcher匹配<br/>OCR框 + HTML结构]
        E2 --> E3[生成增强HTML<br/>data-bbox属性]
        E3 --> F
    end
    
    F[坐标逆转换] --> G[回到原图坐标系]
    G --> H[返回表格元素]
    
    style D fill:#e1f5ff
    style D3 fill:#e1f5ff
    style D5 fill:#ffe1e1
    style E1 fill:#fff4e1

表格OCR预处理（共享逻辑）

无论使用哪种表格识别方法，都需要先进行OCR预处理：

裁剪表格区域：添加 padding=10px 保护边缘内容
表格方向检测：使用 PP-LCNet 检测并矫正表格方向
收集OCR框：
- 优先：使用整页OCR结果中与表格区域重叠的spans
- 兜底：对裁剪后的表格区域单独OCR
坐标转换：将坐标从原图转换到裁剪后的表格图像坐标系

关键点：

padding=10px 在原图坐标系中
表格图像的 (0,0) 对应原图的 (bbox[0]-padding, bbox[1]-padding)
UNet处理时会放大 upscale_ratio≈3.333 倍

有线表格识别流程（UNET）

配置项：table_recognition_wired.use_wired_unet: true

处理步骤：

UNet表格线检测：
- 检测横线（rows）和竖线（cols）坐标
- 坐标在放大后的图像坐标系（upscale≈3.333倍）
倾斜检测与矫正（可选，enable_deskew: true）：
- 使用 Hough 变换检测表格线倾斜角度
- 坐标系：Y轴向下，逆时针旋转为正角度
- 矫正逻辑：correction_angle = -detected_angle（反向旋转）
- 同步更新表格图像和OCR框坐标
网格恢复（grid_recovery.py）：
- 提取唯一的行线和列线坐标
- 边缘过滤：过滤padding区域的噪声线条
```
edge_margin = int(crop_padding × upscale × 1.2)  # 例如：10 × 3.333 × 1.2 = 40px
```
- 合并距离过近的线条（row_threshold, col_threshold）
- 生成单元格网格
文本填充（text_filling.py）：
- 计算OCR框与单元格的IoU
- 匹配OCR文本到对应单元格
- 支持置信度过滤（ocr_conf_threshold）
HTML生成：
- 生成标准表格HTML
- 添加 data-bbox 属性记录单元格坐标
坐标逆转换：
- 将所有坐标从裁剪+放大坐标系转换回原图坐标系
自动Fallback：
- 如果有线识别失败（返回空HTML），自动切换到VLM识别
- 无需手动干预，确保识别鲁棒性

关键配置：

table_recognition_wired:
  use_wired_unet: true          # 启用有线表格
  upscale_ratio: 3.333          # 固定放大比例
  enable_deskew: true           # 启用倾斜矫正
  row_threshold: 10             # 行合并阈值（像素）
  col_threshold: 15             # 列合并阈值（像素）
  ocr_conf_threshold: 0.8       # OCR置信度阈值

无线表格识别流程（VLM）

配置项：vl_recognition.module: "paddle" 或 "mineru"

处理步骤：

VLM结构识别：
- 输入：表格图像
- 输出：表格HTML结构（无坐标信息）
TableCellMatcher匹配：
- 解析VLM返回的HTML结构
- 使用动态规划算法匹配OCR框到表格单元格
- 考虑合并单元格（rowspan/colspan）
生成增强HTML：
- 在原HTML基础上添加 data-bbox 属性
- 记录每个单元格的精确坐标
坐标逆转换：
- 将坐标从裁剪坐标系转换回原图坐标系

文本处理流程

graph TB
    A[文本区域] --> B{有预匹配spans?}
    
    B -->|是| C[使用整页OCR spans]
    C --> D[SpanMatcher合并文本]
    D --> E{文本非空?}
    
    B -->|否| F
    E -->|是| M[返回文本结果]
    E -->|否| F
    
    F{PDF类型?} -->|数字PDF| G[尝试PDF字符提取]
    F -->|扫描件| H
    
    G --> I{提取成功?}
    I -->|是| M
    I -->|否| H
    
    H[裁剪区域OCR<br/>兜底方案] --> M
    
    style C fill:#e1f5ff
    style D fill:#e1f5ff

处理优先级：

优先级1：使用预匹配的 spans（整页 OCR 结果）
- 效率最高，避免重复OCR
- 坐标精确（整页坐标系）
优先级2：数字PDF字符提取
- 仅适用于 pdf_type='txt'
- 提取PDF内嵌的文本和坐标
优先级3：裁剪区域OCR（兜底方案）
- 适用于spans匹配失败或扫描件
- 单独OCR该区域，坐标需转换

代码实现：

def process_text_element(
    self,
    image: np.ndarray,
    layout_item: Dict[str, Any],
    pdf_type: str,
    pdf_doc: Optional[Any],
    page_idx: int,
    scale: float,
    pre_matched_spans: Optional[List[Dict[str, Any]]] = None
) -> Dict[str, Any]:
    bbox = layout_item.get('bbox', [0, 0, 0, 0])
    
    # 优先级1：使用预匹配的 spans
    if pre_matched_spans and len(pre_matched_spans) > 0:
        text_content, sorted_spans = SpanMatcher.merge_spans_to_text(
            pre_matched_spans, bbox
        )
        if text_content.strip():
            return {..., 'extraction_method': 'whole_page_ocr_spans'}
    
    # 优先级2：PDF字符提取
    if pdf_type == 'txt' and pdf_doc is not None:
        extracted_text = PDFUtils.extract_text_from_region(...)
        if extracted_text.strip():
            return {..., 'extraction_method': 'pdf_extraction'}
    
    # 优先级3：裁剪区域OCR
    cropped_region = CoordinateUtils.crop_region(image, bbox)
    ocr_result = self.ocr_recognizer.recognize_text(cropped_region)
    return {..., 'extraction_method': 'cropped_region_ocr'}

元素分类说明

元素类别	包含类型	处理方式	是否使用pre_matched_spans
文本类	text, title, header, footer, ref_text, table_caption, image_caption 等	优先spans → PDF提取 → 裁剪OCR	✅
表格类	table, table_body	OCR预处理 + (UNET/VLM)	✅（仅OCR预处理）
图片类	image, image_body, figure	裁剪保存	❌
公式类	interline_equation, equation	VLM识别 → LaTeX	❌
代码类	code, code_body, code_caption, algorithm	优先spans → PDF提取 → 裁剪OCR	✅
丢弃类	abandon, discarded	优先spans → 裁剪OCR（保留备用）	✅

坐标转换说明

处理过程中涉及多个坐标系的转换：

原图坐标系：PDF/图片的原始坐标
检测图像坐标系：可能经过旋转（方向矫正）
裁剪区域坐标系：表格/文本区域裁剪后的坐标（可能有padding）
放大坐标系：UNet处理时的放大坐标（upscale≈3.333）

坐标转换流程：

原图坐标 → 检测图像坐标 → 裁剪区域坐标 → 放大坐标（UNET）
          ↓                  ↓                 ↓
       方向矫正           添加padding         upscale放大
          ↓                  ↓                 ↓
      逆向转换           逆向转换           逆向转换

所有处理完成后，坐标统一转换回原图坐标系，确保输出一致性。

元素分类说明

元素类别	包含类型	处理方式
文本类	text, title, header, footer, ref_text, table_caption, image_caption 等	优先使用匹配的 spans，否则 PDF 提取或裁剪 OCR
表格类	table, table_body	OCR 坐标 + VLM 结构
图片类	image, image_body, figure	裁剪保存
公式类	interline_equation, equation	VLM 识别
丢弃类	abandon, discarded	优先使用匹配的 spans，否则裁剪 OCR

方向识别策略

处理阶段	方向识别	建议
页面级	PP-LCNet	可配置，扫描件开启，数字PDF关闭
表格区域	-	可选，VLM 有一定容忍度，OCR 自带角度校正
文本区域	-	不需要，OCR 自带校正

Layout 后处理

大面积文本块转表格

当Layout检测将大面积的表格区域误识别为文本框时，可以通过后处理自动转换：

判断规则：

面积占比：占页面面积超过阈值（默认25%）
尺寸比例：宽度和高度都超过一定比例（避免细长条）
表格冲突：如果页面已有表格，不进行转换（避免误判）

配置示例：

layout:
  convert_large_text_to_table: true  # 是否启用
  min_text_area_ratio: 0.25          # 最小面积占比（25%）
  min_text_width_ratio: 0.4          # 最小宽度占比（40%）
  min_text_height_ratio: 0.3         # 最小高度占比（30%）

详细说明请参考：Layout后处理-文本转表格.md

OCR 使用策略

PDF 类型	文字块处理	表格处理
扫描件/图片	整页 OCR → Span 匹配	OCR 检测（坐标） + VLM（结构）
数字原生 PDF	整页 OCR → Span 匹配 / PDF 字符提取	OCR 检测（坐标） + VLM（结构）

关键点：

整页 OCR 优先：先对整页进行 OCR，再将结果匹配到 layout blocks
数字原生 PDF 在 spans 匹配失败时，会尝试 PDF 字符提取
表格处理无论 PDF 类型都需要 OCR 检测，用于获取单元格内文本的精确坐标
VLM 只返回表格结构（HTML），不返回单元格坐标，需要与 OCR 检测结果匹配
当前实现仅使用 VLM（MinerU VLM 或 PaddleOCR-VL）进行表格结构识别

OCR 参数配置

默认参数（已优化，参考PPStructureV3）：

det_threshold: 0.6（检测框置信度阈值，提高可减少噪声框）
unclip_ratio: 1.5（检测框扩展比例，降低可提高框精确度）
enable_merge_det_boxes: False（是否合并检测框，表格场景建议False）

配置示例：

ocr:
  det_threshold: 0.6              # 检测阈值（0.3-0.7，越高越严格）
  unclip_ratio: 1.5               # 扩展比例（1.3-1.8，越低越精确）
  enable_merge_det_boxes: false   # 合并框（表格场景建议false）
  language: ch                     # 语言（ch/ch_lite/en等）

OCR 参数实际使用对比

不同配置文件针对不同场景优化了OCR参数，选择合适的配置可以显著提升识别效果：

配置文件	det_threshold	unclip_ratio	enable_merge	适用场景	说明
bank_statement_yusys_v2.yaml	0.6	1.5	false	银行流水（标准质量）	推荐配置，减少噪声框
bank_statement_mineru_v2.yaml	0.6	1.5	false	财务报表（标准质量）	推荐配置，高精度
bank_statement_paddle_vl.yaml	0.3	1.8	false	扫描质量差	宽松配置，增强召回
bank_statement_wired_unet.yaml	0.5	1.8	false	有线表格	平衡配置，兼顾精度与召回

参数选择建议：

det_threshold（检测阈值）：
- 0.6：严格模式，适合高质量扫描件/数字PDF，减少噪声框和误检
- 0.5：平衡模式，适合有线表格场景，兼顾精度和召回
- 0.3：宽松模式，适合低质量扫描件，捕获更多文本但可能产生噪声
unclip_ratio（扩展比例）：
- 1.5：精确模式，检测框更贴近文本边界，减少相邻单元格干扰
- 1.8：宽松模式，检测框扩大，避免文本截断但可能重叠
enable_merge_det_boxes（合并框）：
- false：表格场景推荐，保持单元格独立性
- true：长文本场景，自动合并相邻文本框

快速选择：

✅ 银行流水/财务报表（高质量）→ 0.6 / 1.5 / false
✅ 有线表格（需要精确坐标）→ 0.5 / 1.8 / false
✅ 扫描质量差（老旧文档）→ 0.3 / 1.8 / false

详细分析请参考：OCR识别差异分析与改进方案.md

目录结构

universal_doc_parser/
├── config/ # 配置文件
│ ├── bank_statement_yusys_v2.yaml # 银行流水配置（Docling + PaddleOCR-VL）
│ ├── bank_statement_mineru_v2.yaml # 银行流水配置（MinerU layout + MinerU VLM）
│ ├── bank_statement_mineru_vl.yaml # 银行流水配置（MinerU VLM）
│ ├── bank_statement_paddle_vl.yaml # 银行流水配置（PaddleOCR-VL）
│ └── bank_statement_wired_unet.yaml # 有线表格配置（Docling + UNET）⭐ 新增
│
├── core/ # 核心处理模块
│ ├── pipeline_manager_v2.py # 主流水线管理器 ⭐
│ ├── pipeline_manager_v2_streaming.py # 流式处理流水线 ⭐ 新增
│ ├── element_processors.py # 元素处理器（文本、表格、图片等）
│ ├── coordinate_utils.py # 坐标转换工具
│ ├── layout_utils.py # 布局处理工具（排序、去重、SpanMatcher）⭐
│ ├── pdf_utils.py # PDF 处理工具
│ ├── config_manager.py # 配置管理
│ └── model_factory.py # 模型工厂
│
├── models/ # 模型适配器
│ └── adapters/
│   ├── base.py # 适配器基类
│   ├── mineru_adapter.py # MinerU 适配器
│   ├── paddle_vl_adapter.py # PaddleOCR-VL 适配器
│   ├── paddle_layout_detector.py # PaddleX RT-DETR 布局检测器
│   ├── docling_layout_adapter.py # Docling 布局检测器 ⭐
│   ├── dit_layout_adapter.py # DiT 布局检测器 ⭐ 新增
│   ├── mineru_wired_table.py # MinerU 有线表格识别器 ⭐ 新增
│   └── wired_table/ # 有线表格子模块 ⭐ 新增
│     ├── init.py
│     ├── debug_utils.py # 调试工具
│     ├── ocr_formatter.py # OCR 格式转换
│     ├── skew_detection.py # 倾斜检测与矫正
│     ├── grid_recovery.py # 网格恢复
│     ├── text_filling.py # 文本填充
│     ├── html_generator.py # HTML 生成
│     └── visualization.py # 可视化
│  
├── utils/ # 输出工具模块（已迁移到 ocr_utils）⚠️
│ └── init.py # 仅作重新导出接口
│  
├── tests/ # 测试模块
│ ├── test_skew_correction.py # 倾斜矫正测试
│ └── ...
│  
├── main_v2.py # 命令行入口 ⭐
└── 模型统一框架.md # 本文档

使用方法

命令行

# 处理单个 PDF 文件
python main_v2.py -i document.pdf -c config/bank_statement_yusys_v2.yaml

# 处理图片目录
python main_v2.py -i ./images/ -c config/bank_statement_yusys_v2.yaml

# 开启 debug 模式（输出可视化图片）
python main_v2.py -i doc.pdf -c config/bank_statement_yusys_v2.yaml --debug

# 指定输出目录
python main_v2.py -i doc.pdf -c config/bank_statement_yusys_v2.yaml -o ./my_output/

Python API

from core.pipeline_manager_v2 import EnhancedDocPipeline
from utils import OutputFormatterV2

# 初始化流水线
with EnhancedDocPipeline("config/bank_statement_yusys_v2.yaml") as pipeline:
    # 处理文档
    results = pipeline.process_document("document.pdf")
    
    # 保存结果
    formatter = OutputFormatterV2("./output")
    output_paths = formatter.save_results(results, {
        'save_json': True,
        'save_markdown': True,
        'save_html': True,
        'save_layout_image': True,  # debug
        'save_ocr_image': True,     # debug
        'normalize_numbers': True,   # 金额标准化
    })

流式处理模式

对于大文档或内存受限场景，使用流式处理模式：

# 命令行添加 --streaming 参数
python main_v2.py -i large_document.pdf -c config.yaml --streaming -o ./output

流式处理特点：

✅ 按页处理：每处理完一页立即保存结果，不累积在内存中 ✅ 内存占用低：适合处理数百页的大文档 ✅ 容错性好：某页处理失败不影响已保存的页面 ✅ 输出一致：与批量模式输出格式完全一致适用场景：

处理超过50页的大型PDF文档服务器内存受限（如4GB以下）需要实时查看处理进度

输出文件说明

输出文件	说明
`{doc}_middle.json`	MinerU 标准格式 JSON
`{doc}_enhanced.json`	增强版 JSON（包含更多元数据）⭐ 新增
`{doc}_page_001.json`	每页独立 JSON（包含单元格坐标）
`{doc}_pdf_page_001.png`	PDF转换的页面图片 ⭐ 新增
`{doc}.md`	完整文档 Markdown
`{doc}_page_001.md`	每页独立 Markdown（带坐标注释）
`tables/*.html`	表格 HTML 文件（带 data-bbox 坐标）
`images/`	提取的图片元素
`{doc}_page_001_layout.png`	Layout 可视化图片（debug 模式）
`{doc}_page_001_ocr.png`	OCR 可视化图片（debug 模式）
`{doc}_page_001_table_001_lines.png`	有线表格线可视化 ⭐ 新增（wired debug）
`{doc}_page_001_table_001_grid.png`	有线表格网格结构 ⭐ 新增（wired debug）
`{doc}_page_001_table_001_text.png`	有线表格文本覆盖 ⭐ 新增（wired debug）
`{doc}_page_001_table_001_components.png`	有线表格连通域 ⭐ 新增（wired debug）
`_original.`	标准化前的原始文件（如有修改）

有线表格调试输出说明：

当配置 table_recognition_wired.debug_options.enabled: true 时，会生成详细的可视化图片
这些图片帮助理解表格识别的各个处理阶段（表格线提取、网格恢复、文本填充等）
详细说明请参考：有线表格识别技术文档.md

配置说明

配置文件采用 YAML 格式，主要配置项：

# 场景名称
scene_name: "bank_statement"

# 输入配置
input:
  supported_formats: [".pdf", ".png", ".jpg", ".jpeg"]
  dpi: 200  # PDF 转图片的 DPI

# 预处理（方向识别）
preprocessor:
  module: "mineru"
  orientation_classifier:
    enabled: true  # 扫描件自动开启

# 版式检测
layout_detection:
  module: "docling"  # 可选: "mineru", "paddle", "docling"
  model_name: "docling-layout-old"
  model_dir: "ds4sd/docling-layout-old"  # HuggingFace 模型仓库
  device: "cpu"
  conf: 0.3

# VL 识别（表格、公式）
vl_recognition:
  module: "paddle"  # 可选: "mineru", "paddle"
  backend: "http-client"
  server_url: "http://xxx:8110"
  table_recognition:
    return_cells_coordinate: true

# OCR 识别
ocr_recognition:
  module: "mineru"
  language: "ch"

# 输出配置
output:
  create_subdir: false        # 是否创建子目录
  save_json: true
  save_markdown: true
  save_html: true
  save_layout_image: false    # debug 模式开启
  save_ocr_image: false       # debug 模式开启
  normalize_numbers: true     # 金额数字标准化

支持的布局检测器

1. Docling Layout (推荐)

基于 HuggingFace transformers 的 RT-DETR 模型。

layout_detection:
  module: "docling"
  model_name: "docling-layout-old"
  model_dir: "ds4sd/docling-layout-old"

支持的模型：

ds4sd/docling-layout-old
ds4sd/docling-layout-heron
ds4sd/docling-layout-egret-medium
ds4sd/docling-layout-egret-large

2. PaddleX RT-DETR (ONNX)

基于 ONNX Runtime 的 PaddleX 布局检测器。

layout_detection:
  module: "paddle"
  model_name: "RT-DETR-H_layout_17cls"
  model_dir: "/path/to/RT-DETR-H_layout_17cls.onnx"

3. MinerU DocLayout-YOLO

MinerU 内置的布局检测模型。

layout_detection:
  module: "mineru"
  model_name: "layout"

4. DiT Layout (Document Image Transformer)

基于 Detectron2 的 DiT 模型，在 PubLayNet 数据集上训练。

layout_detection:
  module: "dit"
  config_file: "dit_support/configs/cascade/cascade_dit_large.yaml"
  model_weights: "path/to/model.pth"
  device: "cpu"
  conf: 0.3

支持类别：

text：正文文本 title：标题 list：列表 table：表格 figure：图片/图表特点：

基于 Vision Transformer 架构适合学术文档和出版物需要 Detectron2 框架支持

类别映射

所有布局检测器的输出都会统一映射到 MinerU/EnhancedDocPipeline 类别体系：

类别分类	包含类别
文本类 (TEXT)	text, title, header, footer, page_number, ref_text, page_footnote, aside_text, ocr_text
表格类 (TABLE)	table, table_body, table_caption, table_footnote
图片类 (IMAGE)	image, image_body, figure, image_caption, image_footnote
公式类 (EQUATION)	interline_equation, inline_equation, equation
代码类 (CODE)	code, code_body, code_caption, algorithm
丢弃类 (DISCARD)	abandon, discarded

核心组件

1. EnhancedDocPipeline (`pipeline_manager_v2.py`)

主流水线管理器，实现完整处理流程：

PDF 分类（扫描件/数字原生）
页面方向识别
Layout 检测与去重
整页 OCR + Span-Block 匹配 ⭐
元素分类处理
阅读顺序排序
坐标转换

2. SpanMatcher (`layout_utils.py`)

OCR Span 与 Layout Block 匹配器，参考 MinerU 实现：

match_spans_to_blocks() - 将 spans 匹配到对应的 blocks
merge_spans_to_text() - 将多个 spans 合并为文本
remove_duplicate_spans() - 去除重复 spans
poly_to_bbox() - 多边形坐标转 bbox

3. ElementProcessors (`element_processors.py`)

元素处理器，处理不同类型的元素：

process_text_element() - 文本处理（支持 pre_matched_spans）
process_table_element() - 表格处理（VLM + OCR 坐标匹配）
process_image_element() - 图片处理
process_equation_element() - 公式处理
process_code_element() - 代码处理
process_discard_element() - 丢弃元素处理（支持 pre_matched_spans）

3. OutputFormatterV2 (`output_formatter_v2.py`)

统一输出格式化器：

MinerU 标准 middle.json 格式
每页独立 JSON（含单元格坐标）
Markdown 输出（完整版 + 按页）
表格 HTML（带 data-bbox 属性）
可视化图片（Layout/OCR）
金额数字标准化

4. TableCellMatcher (来自 `merger`)

表格单元格坐标匹配器：

使用动态规划进行行内单元格匹配
将 OCR 检测框与 VLM 表格结构匹配
输出带坐标的增强 HTML

依赖说明

MinerU 组件

mineru.utils.pdf_image_tools - PDF 图像处理
mineru.utils.pdf_text_tool - PDF 文本提取
mineru.utils.boxbase - 边界框计算
mineru.model.ocr - OCR 模型
mineru.model.ori_cls - 方向分类模型

OCR Tools 组件（来自 ocr_tools.ocr_merger）⚠️

实际导入路径（注意：不是 ocr_verify）：

# 实际使用的导入路径
from ocr_tools.ocr_merger import TableCellMatcher, TextMatcher

# 模块位置：ocr_tools/ocr_merger/
├── table_cell_matcher.py  # 单元格坐标匹配
├── text_matcher.py        # 文本匹配
└── merger_core.py         # 核心匹配算法
````
功能说明：

TableCellMatcher：将 OCR 检测框与 VLM 表格结构匹配，使用动态规划算法
TextMatcher：文本相似度匹配工具

o工具模块（已迁移到 ocr_utils）⚠️
输出工具已统一迁移到 ocr_utils 包，

python

从 ocr_utils 重新导出

from ocr_utils import (

OutputFormatterV2,       # 统一输出格式化器
JSONFormatters,          # JSON格式化
MarkdownGenerator,       # Markdown生成
HTMLGenerator,           # HTML生成
VisualizationUtils,      # 可视化工具
normalize_financial_numbers,  # 金额标准化

)

优势：
  . 统一管理所有输出工具
  . 跨项目复用代码
  . 更好的版本控制

其他依赖
  . transformers - Docling 模型加载
  . huggingface_hub - 模型下载
  . detectron2 - DiT 模型推理 ⭐ 新增
  . onnxruntime - ONNX 模型推理
  . Pillow - 图像处理
  . NumPy - 数值计算
  . OpenCV (cv2) - 图像处理和表格线检测 ⭐
  . BeautifulSoup4 - HTML 解析
  . PyYAML - 配置文件解析
  . loguru - 日志

---

### 安装依赖

bash

基础依赖

pip install transformers huggingface_hub onnxruntime pillow numpy opencv-python beautifulsoup4 pyyaml loguru

MinerU（必需）

pip install magic-pdf[full]

OCR Merger（必需）

cd /path/to/ocr_tools && pip install -e .

DiT支持（可选，如果使用DiT布局检测器）

pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cpu/torch2.0/index.html ```

模型统一框架.md 30 KB History Raw

金融文档处理统一框架

支持场景

模型选择

处理流程

主流程图

单页处理详细流程

关键改进：整页 OCR + Span 匹配

表格处理流程

表格OCR预处理（共享逻辑）

有线表格识别流程（UNET）

无线表格识别流程（VLM）

文本处理流程

元素分类说明

坐标转换说明

元素分类说明

方向识别策略

Layout 后处理

大面积文本块转表格

OCR 使用策略

OCR 参数配置

OCR 参数实际使用对比

目录结构

使用方法

命令行

Python API

流式处理模式

输出文件说明

配置说明

支持的布局检测器

1. Docling Layout (推荐)

2. PaddleX RT-DETR (ONNX)

3. MinerU DocLayout-YOLO

4. DiT Layout (Document Image Transformer)

类别映射

核心组件

1. EnhancedDocPipeline (pipeline_manager_v2.py)

2. SpanMatcher (layout_utils.py)

3. ElementProcessors (element_processors.py)

3. OutputFormatterV2 (output_formatter_v2.py)

4. TableCellMatcher (来自 merger)

依赖说明

MinerU 组件

OCR Tools 组件（来自 ocr_tools.ocr_merger）⚠️

从 ocr_utils 重新导出

基础依赖

MinerU（必需）

OCR Merger（必需）

DiT支持（可选，如果使用DiT布局检测器）

模型统一框架.md 30 KB

History Raw

1. EnhancedDocPipeline (`pipeline_manager_v2.py`)

2. SpanMatcher (`layout_utils.py`)

3. ElementProcessors (`element_processors.py`)

3. OutputFormatterV2 (`output_formatter_v2.py`)

4. TableCellMatcher (来自 `merger`)