5448a047ff
Archived as 2025-11-27-upgrade-ppstructure-models Spec updated: ocr-processing (added PP-StructureV3 Configuration) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
135 lines
5.1 KiB
Markdown
135 lines
5.1 KiB
Markdown
# Upgrade PP-StructureV3 Models
|
||
|
||
## Why
|
||
|
||
目前專案使用的 PP-StructureV3 模型配置存在以下問題：
|
||
|
||
1. **版面偵測模型精度不足**：PP-DocLayout-S (70.9% mAP) 無法正確處理複雜表格和版面
|
||
2. **表格識別準確率低**：SLANet (59.52%) 產出錯誤的 HTML 結構
|
||
3. **預處理模組未啟用**：文檔方向校正和彎曲校正功能關閉
|
||
4. **模型佔用空間過大**：下載了不使用的模型，浪費儲存空間
|
||
|
||
## What Changes
|
||
|
||
### Stage 1: 預處理模組 - 全部開啟
|
||
|
||
| 功能 | 當前 | 變更後 |
|
||
|-----|-----|-------|
|
||
| `use_doc_orientation_classify` | False | **True** |
|
||
| `use_doc_unwarping` | False | **True** |
|
||
| `use_textline_orientation` | False | **True** |
|
||
|
||
### Stage 2: OCR 模組 - 維持現狀
|
||
|
||
- 繼續使用 PP-OCRv5 (預設配置)
|
||
- 不需要更改
|
||
|
||
### Stage 3: 版面分析模組 - 升級模型選項
|
||
|
||
| 選項名稱 | 當前模型 | 變更後模型 | mAP |
|
||
|---------|---------|-----------|-----|
|
||
| `chinese` | PP-DocLayout-S (移除) | **PP-DocLayout_plus-L** | 83.2% |
|
||
| `default` | PubLayNet | PubLayNet (維持) | ~94% |
|
||
| `cdla` | CDLA | CDLA (維持) | ~86% |
|
||
|
||
**重點變更**：
|
||
- 移除 PP-DocLayout-S (70.9% mAP)
|
||
- 新增 PP-DocLayout_plus-L (83.2% mAP, 20類別)
|
||
- 前端「中文文檔」選項改用 PP-DocLayout_plus-L
|
||
|
||
### Stage 4: 元素識別模組 - 升級表格識別
|
||
|
||
| 模組 | 當前模型 | 變更後模型 | 準確率變化 |
|
||
|-----|---------|-----------|-----------|
|
||
| 表格識別 | SLANet (預設) | **SLANeXt_wired + SLANeXt_wireless** | 59.52% → 69.65% |
|
||
| 公式識別 | PP-FormulaNet (預設) | **PP-FormulaNet_plus-L** | 45.78% → 90.64% (中文) |
|
||
| 圖表解析 | PP-Chart2Table | PP-Chart2Table (維持) | - |
|
||
| 印章識別 | PP-OCRv4_seal | PP-OCRv4_seal (維持) | - |
|
||
|
||
**表格識別策略**：
|
||
- SLANeXt_wired 和 SLANeXt_wireless 搭配使用
|
||
- 先用分類器判斷有線/無線表格類型
|
||
- 根據類型選擇對應的 SLANeXt 模型
|
||
- 聯合測試準確率達 69.65%
|
||
|
||
### 儲存空間優化 - 刪除未使用模型
|
||
|
||
PaddleOCR 3.x 模型緩存位置：`~/.paddlex/official_models/`
|
||
|
||
可刪除的模型目錄：
|
||
- PP-DocLayout-S (被 PP-DocLayout_plus-L 取代)
|
||
- SLANet (被 SLANeXt 取代)
|
||
- 其他未使用的舊版模型
|
||
|
||
**注意**：刪除後首次使用新模型會觸發下載
|
||
|
||
## Requirements
|
||
|
||
### REQ-1: 預處理模組開啟
|
||
系統 **SHALL** 在 PP-StructureV3 初始化時啟用所有預處理功能：
|
||
- 文檔方向分類 (use_doc_orientation_classify=True)
|
||
- 文檔彎曲校正 (use_doc_unwarping=True)
|
||
- 文字行方向偵測 (use_textline_orientation=True)
|
||
|
||
**Scenario: 處理旋轉的掃描文檔**
|
||
- Given 一個旋轉 90 度的 PDF 文檔
|
||
- When 使用 OCR track 處理
|
||
- Then 系統應自動校正方向後再進行 OCR
|
||
|
||
### REQ-2: 版面模型升級
|
||
系統 **SHALL** 將「chinese」選項對應的模型從 PP-DocLayout-S 更改為 PP-DocLayout_plus-L
|
||
|
||
**Scenario: 處理中文複雜文檔**
|
||
- Given 包含表格、圖片、公式的中文文檔
|
||
- When 選擇「chinese」版面模型處理
|
||
- Then 應使用 PP-DocLayout_plus-L (83.2% mAP) 進行版面分析
|
||
|
||
### REQ-3: 表格識別升級
|
||
系統 **SHALL** 使用 SLANeXt_wired 和 SLANeXt_wireless 搭配進行表格識別
|
||
|
||
**Scenario: 處理有線表格**
|
||
- Given 包含有線表格的文檔
|
||
- When 進行表格結構識別
|
||
- Then 應使用 SLANeXt_wired 模型
|
||
- And 輸出正確的 HTML 表格結構
|
||
|
||
**Scenario: 處理無線表格**
|
||
- Given 包含無線表格的文檔
|
||
- When 進行表格結構識別
|
||
- Then 應使用 SLANeXt_wireless 模型
|
||
|
||
### REQ-4: 公式識別升級
|
||
系統 **SHALL** 使用 PP-FormulaNet_plus-L 進行公式識別以支援中文公式
|
||
|
||
### REQ-5: 模型緩存清理
|
||
系統 **SHOULD** 提供工具或文檔說明如何清理未使用的模型緩存以節省儲存空間
|
||
|
||
## Model Comparison Data
|
||
|
||
### 表格識別模型對比
|
||
|
||
| 模型 | 準確率 | 推理時間 | 模型大小 | 適用場景 |
|
||
|-----|-------|---------|---------|---------|
|
||
| SLANet | 59.52% | 24ms | 6.9 MB | ❌ 準確率不足 |
|
||
| SLANet_plus | 63.69% | 23ms | 6.9 MB | ❌ 仍不足 |
|
||
| **SLANeXt_wired** | 69.65% | 86ms | 351 MB | ✅ 有線表格 |
|
||
| **SLANeXt_wireless** | 69.65% | - | 351 MB | ✅ 無線表格 |
|
||
|
||
**結論**：SLANeXt 系列比 SLANet/SLANet_plus 準確率高約 10%，但模型大小增加約 50 倍。考慮到表格識別是核心功能，建議升級。
|
||
|
||
### 版面偵測模型對比
|
||
|
||
| 模型 | 類別數 | mAP | 推理時間 | 適用場景 |
|
||
|-----|-------|-----|---------|---------|
|
||
| PP-DocLayout-S | 23 | 70.9% | 12ms | ❌ 精度不足 |
|
||
| PP-DocLayout-L | 23 | 90.4% | 34ms | ✅ 通用高精度 |
|
||
| **PP-DocLayout_plus-L** | 20 | 83.2% | 53ms | ✅ 複雜文檔推薦 |
|
||
|
||
## References
|
||
|
||
- [PaddleOCR Table Structure Recognition](http://www.paddleocr.ai/main/en/version3.x/module_usage/table_structure_recognition.html)
|
||
- [SLANeXt_wired on HuggingFace](https://huggingface.co/PaddlePaddle/SLANeXt_wired)
|
||
- [SLANeXt_wireless on HuggingFace](https://huggingface.co/PaddlePaddle/SLANeXt_wireless)
|
||
- [PP-StructureV3 Technical Report](https://arxiv.org/html/2507.05595v1)
|
||
- [PaddleOCR Model Cache Issue](https://github.com/PaddlePaddle/PaddleOCR/issues/10234)
|