# 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)