OCR/openspec/changes/archive/2025-11-27-upgrade-ppstructure-models/proposal.md

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
• SLANeXt_wired on HuggingFace
• SLANeXt_wireless on HuggingFace
• PP-StructureV3 Technical Report
• PaddleOCR Model Cache Issue