Browse Source

feat: enhance document processing framework with updated model references, detailed layout detection strategies, and improved output formats including visualizations and coordinate information

zhch158_admin 4 days ago
parent
commit
7a2edafbeb
1 changed files with 282 additions and 4 deletions
  1. 282 4
      zhch/universal_doc_parser/模型统一框架.md

+ 282 - 4
zhch/universal_doc_parser/模型统一框架.md

@@ -1,17 +1,295 @@
-参考minerU实现的模型统一框架, 
+参考minerU实现的模型统一框架,
 对于我们设计的金融场景,
 一种是银行交易流水,特点是单栏列表形式,没有合并单元格,分无线表格和有线表格两种形式;
 另一种是财务报表形式,特点是多栏列表形式,有合并单元格,且表头复杂。且分有线,无线表格两种形式。
 minerU pipeline使用paddle的ocr模型,对于文字识别效果较好,但表格结构识别效果一般
 对于表格识别minerU vlm和PaddleOCR-VL的效果都很好
-对于我们的应用场景,版式识别使用paddle的转寒微onnx的RT-DETR-H_layout_17cls模型效果较好
+对于我们的应用场景,版式识别使用MinerU的doclayout_yolo_docstructbench_imgsz1280_2501.pt模型效果较好
 同时要求为了方便交叉核对,需要返回每个单元格的坐标信息。
 
 对于银行交易流水, 构想的处理流程如下:
+
 1. 方向旋转, PP-LCNet_x1_0_doc_ori.onnx沿用现有minerU实现
-2. layout检测, RT-DETR-H_layout_17cls.onnx仿制minerU实现
+2. layout检测, doclayout_yolo_docstructbench_imgsz1280_2501.pt
 3. 文本调用PaddleOCR进行检测和识别,pytorch模型
 4. 其他如:表格,数学公式等调用minerU vlm或PaddleOCR-VL进行检测和识别
 5. 调用minerU后处理模块进行表格结构恢复和HTML生成,同时返回单元格坐标信息
 
-这里用到的模型都可以通过配置文件进行配置和替换,方便后续进行模型升级和替换,调用模型的代码都应可以采用adpter的方式尽量复用minerU的实现。
+这里用到的模型都可以通过配置文件进行配置和替换,方便后续进行模型升级和替换,调用模型的代码都应可以采用adpter的方式尽量复用minerU的实现。
+
+```mermaid
+graph TB
+    A[输入 PDF/图片] --> B{PDF 分类}
+    
+    B -->|扫描件/图片| C1[页面方向识别<br/>PP-LCNet]
+    B -->|数字原生PDF| C2[Layout 检测]
+    C1 --> D1[Layout 检测]
+    
+    subgraph OCR模式
+        D1 --> E1[文本区域]
+        D1 --> F1[表格区域]
+        E1 --> G1[OCR 检测+识别<br/>自带角度校正]
+        F1 --> H1[表格方向检测]
+        H1 --> I1[OCR 检测<br/>获取文本框坐标]
+        H1 --> J1{使用VLM?}
+        J1 -->|是| K1[VLM 结构识别]
+        J1 -->|否| L1[表格模型识别<br/>SLANet/UNet]
+        I1 --> M1[匹配坐标与结构]
+        K1 --> M1
+        L1 --> M1
+    end
+    
+    subgraph 文本提取模式
+        C2 --> E2[文本区域]
+        C2 --> F2[表格区域]
+        E2 --> G2[PDF 字符提取<br/>pdftext]
+        G2 --> G2a{提取成功?}
+        G2a -->|否| G2b[OCR 补充识别]
+        F2 --> H2[表格方向检测]
+        H2 --> I2[OCR 检测<br/>获取文本框坐标]
+        H2 --> J2{使用VLM?}
+        J2 -->|是| K2[VLM 结构识别]
+        J2 -->|否| L2[表格模型识别<br/>SLANet/UNet]
+        I2 --> M2[匹配坐标与结构]
+        K2 --> M2
+        L2 --> M2
+    end
+    
+    G1 --> N[合并所有结果]
+    M1 --> N
+    G2a -->|是| N
+    G2b --> N
+    M2 --> N
+    
+    N --> O[合并跨页表格]
+```
+
+---
+
+## 方向识别策略
+
+| 处理阶段                 | 方向识别          | 建议                                 |
+| ------------------------ | ----------------- | ------------------------------------ |
+| **页面级**               | PP-LCNet          | 可配置,扫描件开启,数字PDF关闭      |
+| **表格区域 + VLM**       | ImgOrientationCls | 可选,VLM 有一定容忍度               |
+| **表格区域 + OCR坐标**   | ImgOrientationCls | **必须**,OCR 坐标依赖正确方向       |
+| **文本区域**             | -                 | 不需要,OCR 自带校正                 |
+
+---
+
+## OCR 使用策略
+
+| PDF 类型         | 文字块处理                     | 表格处理                           |
+| ---------------- | ------------------------------ | ---------------------------------- |
+| **扫描件/图片**  | OCR 检测 + 识别                | OCR 检测(坐标) + VLM/表格模型(结构) |
+| **数字原生 PDF** | PDF 字符提取(失败时 OCR 补充)| OCR 检测(坐标) + VLM/表格模型(结构) |
+
+**关键点**:
+- 数字原生 PDF 的文字块可直接提取,坐标更精确
+- **表格处理无论 PDF 类型都需要 OCR 检测**,用于获取单元格内文本的精确坐标
+- VLM 只返回表格结构(HTML),不返回单元格坐标,需要与 OCR 检测结果匹配
+
+---
+
+## 实现说明
+
+### 目录结构
+
+```
+universal_doc_parser/
+├── config/
+│   ├── bank_statement_v2.yaml      # 银行流水配置
+│   ├── financial_report_v2.yaml    # 财务报表配置
+│   ├── bank_statement_mineru_vl.yaml
+│   └── bank_statement_paddle_vl.yaml
+├── core/
+│   ├── config_manager.py           # 配置管理
+│   ├── model_factory.py            # 模型工厂
+│   ├── pipeline_manager.py         # 原版流水线
+│   └── pipeline_manager_v2.py      # 增强版流水线 ⭐
+├── models/
+│   └── adapters/
+│       ├── base.py                 # 适配器基类
+│       ├── mineru_adapter.py       # MinerU 适配器
+│       ├── paddle_vl_adapter.py    # PaddleOCR-VL 适配器
+│       └── paddle_layout_detector.py
+├── utils/
+│   ├── output_formatter.py         # 原版输出格式化
+│   └── output_formatter_v2.py      # 增强版输出格式化 ⭐
+├── main_enhanced.py                # 原版入口
+├── main_v2.py                      # 增强版入口 ⭐
+└── 模型统一框架.md
+```
+
+### 使用方法
+
+```bash
+# 处理单个PDF文件
+python main_v2.py -i document.pdf -c config/bank_statement_v2.yaml
+
+# 处理图片目录
+python main_v2.py -i ./images/ -c config/bank_statement_v2.yaml
+
+# 开启debug模式(输出可视化图片)
+python main_v2.py -i doc.pdf -c config/bank_statement_v2.yaml --debug
+
+# 指定输出目录
+python main_v2.py -i doc.pdf -c config/bank_statement_v2.yaml -o ./my_output/
+```
+
+### 输出说明
+
+| 输出文件 | 说明 |
+|---------|------|
+| `{doc}_middle.json` | MinerU 标准格式 JSON |
+| `{doc}_enhanced.json` | 增强版 JSON(包含单元格坐标) |
+| `{doc}.md` | Markdown 文件(带坐标注释) |
+| `tables/*.html` | 表格 HTML 文件(带坐标信息) |
+| `{doc}_page_*_layout.png` | Layout 可视化图片(debug模式) |
+| `{doc}_page_*_ocr.png` | OCR 可视化图片(debug模式) |
+
+### 核心组件
+
+1. **EnhancedDocPipeline** (`pipeline_manager_v2.py`)
+   - 实现完整的处理流程
+   - 支持 PDF 分类(扫描件/数字原生)
+   - 集成 merger 的 TableCellMatcher 进行坐标匹配
+
+2. **OutputFormatterV2** (`output_formatter_v2.py`)
+   - 输出 MinerU 标准格式
+   - 支持 debug 模式可视化
+   - 表格 HTML 包含单元格坐标
+
+3. **TableCellMatcher** (来自 `ocr_verify/merger`)
+   - 使用动态规划进行行内单元格匹配
+   - 将 OCR 检测框与 VLM 表格结构匹配
+   - 输出带坐标的增强 HTML
+
+### 配置说明
+
+配置文件采用 YAML 格式,主要配置项:
+
+```yaml
+# 预处理(方向识别)
+preprocessor:
+  module: "mineru"
+  orientation_classifier:
+    enabled: true  # 扫描件自动开启
+
+# 版式检测
+layout_detection:
+  module: "mineru"
+  model_name: "layout"
+
+# VL识别(表格、公式)
+vl_recognition:
+  module: "mineru"  # 或 "paddle"
+  backend: "http-client"
+  server_url: "http://xxx:8121"
+
+# OCR识别
+ocr_recognition:
+  module: "mineru"
+  language: "ch"
+
+# 输出
+output:
+  save_json: true
+  save_markdown: true
+  save_html: true
+  save_layout_image: false  # debug模式开启
+  save_ocr_image: false     # debug模式开启
+```
+
+---
+
+## 依赖说明
+
+### MinerU 组件
+- `mineru.backend.pipeline.model_init` - 模型初始化
+- `mineru.backend.vlm.vlm_analyze` - VLM 分析
+- `mineru.utils.pdf_classify` - PDF 分类
+- `mineru.utils.pdf_image_tools` - PDF 图像处理
+
+### Merger 组件(来自 ocr_verify)
+- `merger.table_cell_matcher.TableCellMatcher` - 单元格坐标匹配
+- `merger.text_matcher.TextMatcher` - 文本匹配
+- `merger.bbox_extractor.BBoxExtractor` - 坐标提取
+
+### 其他依赖
+- PyMuPDF (fitz) - PDF 处理
+- Pillow - 图像处理
+- NumPy - 数值计算
+- BeautifulSoup4 - HTML 解析
+- PyYAML - 配置文件解析
+- loguru - 日志
+
+---
+# 如何将 merger 模块导入到 MinerU 项目
+
+## 快速开始 🚀
+
+### 推荐方案:可编辑安装
+
+```bash
+# 1. 进入 ocr_verify 目录
+cd /Users/zhch158/workspace/repository.git/ocr_verify
+
+# 2. 安装 merger 模块(可编辑模式)
+python3 -m pip install -e merger/
+
+# 3. 验证安装
+python3 -c "from merger.table_cell_matcher import TableCellMatcher; print('✅ 安装成功')"
+```
+
+完成后,在任何 Python 文件中都可以直接导入:
+
+```python
+from merger.table_cell_matcher import TableCellMatcher
+from merger.text_matcher import TextMatcher
+from merger.bbox_extractor import BBoxExtractor
+```
+
+---
+
+## 为什么需要导入 merger?
+
+`pipeline_manager_v2.py` 需要使用 `merger` 模块的以下功能:
+
+1. **TableCellMatcher**: 匹配表格单元格坐标与 OCR 结果
+2. **TextMatcher**: 文本匹配和对齐
+3. **BBoxExtractor**: 提取和转换边界框坐标
+
+这些组件用于实现表格识别流程中的**坐标匹配**步骤:
+
+```
+OCR检测(获取文本框坐标) + VLM识别(获取表格结构HTML)
+                ↓
+        TableCellMatcher 匹配
+                ↓
+    带精确坐标的表格单元格
+```
+
+---
+
+## 项目结构
+
+```
+/Users/zhch158/workspace/repository.git/
+├── ocr_verify/                          # 源项目
+│   ├── setup.py                         # 安装配置
+│   └── merger/                          # 要导入的模块
+│       ├── __init__.py
+│       ├── table_cell_matcher.py        # 表格单元格匹配
+│       ├── text_matcher.py              # 文本匹配
+│       ├── bbox_extractor.py            # 边界框提取
+│       └── ...
+│
+└── MinerU/                              # 目标项目
+    └── zhch/
+        └── universal_doc_parser/
+            └── core/
+                └── pipeline_manager_v2.py  # 需要导入 merger
+```
+
+---