OCR/CHART_RECOGNITION.md

Chart Recognition Feature Status

當前狀態

圖表識別功能目前禁用，因為它需要 paddle.incubate.nn.functional.fused_rms_norm_ext API。

限制來源

• 記錄時間: 基於 PaddlePaddle 3.0.0 (2025年3月發布)
• 問題: PaddlePaddle 3.0.0 只提供 fused_rms_norm，缺少 fused_rms_norm_ext
• 影響: PP-StructureV3 的圖表內容理解功能無法使用

---

✅ 什麼功能正常運作

即使圖表識別被禁用，以下功能完全正常：

功能	狀態	說明
圖表檢測	✅ 正常	布局分析可以識別圖表位置
圖表提取	✅ 正常	圖表區域保存為圖像文件
表格識別	✅ 正常	包括嵌套公式和圖片的表格
公式識別	✅ 正常	LaTeX 公式提取
文字識別	✅ 正常	OCR 核心功能

❌ 什麼功能被禁用

功能	狀態	說明
圖表類型識別	❌ 禁用	無法識別柱狀圖、折線圖等類型
數據提取	❌ 禁用	無法從圖表提取數值數據
軸/圖例解析	❌ 禁用	無法解析坐標軸標籤和圖例
圖表轉結構化	❌ 禁用	無法將圖表轉為 JSON/表格

---

🔍 驗證新版本是否支持

PaddlePaddle 版本歷史

版本	發布日期	fused_rms_norm_ext 狀態
3.0.0	2025-03-26	❌ 不支持 (記錄限制時的版本)
3.1.0	2025-06-29	❓ 未驗證
3.1.1	2025-08-20	❓ 未驗證
3.2.0	2025-09-08	❓ 未驗證
3.2.1	2025-10-30	❓ 未驗證
3.2.2	2025-11-14	❓ 未驗證 (最新穩定版)

驗證步驟

1. 運行驗證腳本:

   cd backend
   conda activate tool_ocr
   python verify_chart_recognition.py
   

2. 查看結果:

   • ✅ 如果顯示 "Chart recognition CAN be enabled"，表示可以啟用
   • ❌ 如果顯示 "Chart recognition CANNOT be enabled"，需要等待或升級

---

🚀 如何啟用圖表識別

前提條件

確認 fused_rms_norm_ext API 可用（運行上述驗證腳本）

啟用步驟

1. 編輯 OCR 服務配置:

   nano backend/app/services/ocr_service.py
   

2. 修改第 217 行:

   # 修改前:
   use_chart_recognition=False,  # Disable chart recognition...
   
   # 修改後:
   use_chart_recognition=True,   # Enable chart recognition
   

3. 重啟後端服務:

   # 停止當前服務
   pkill -f "python.*app.main"
   
   # 啟動服務
   conda activate tool_ocr
   cd backend
   python -m app.main
   

4. 驗證功能:

   • 上傳包含圖表的文檔
   • 檢查輸出結果中是否包含圖表數據解析

---

⚠️ 性能考量

啟用圖表識別後：

• 處理時間: 每頁增加 2-5 秒（取決於圖表複雜度）
• 記憶體使用: 增加約 500MB-1GB
• 準確率: 對簡單圖表準確率 >80%，複雜圖表可能需要人工檢查

---

🔄 更新 PaddlePaddle

檢查當前版本

conda activate tool_ocr
pip show paddlepaddle

升級到最新版本

conda activate tool_ocr

# CPU 版本
pip install --upgrade paddlepaddle>=3.2.0

# GPU 版本 (CUDA 11.8)
pip install --upgrade paddlepaddle-gpu>=3.2.0

驗證升級

python verify_chart_recognition.py

---

📊 技術細節

為什麼需要 fused_rms_norm_ext?

RMSNorm (Root Mean Square Layer Normalization):

• 一種用於深度學習的層歸一化技術
• PaddleOCR-VL 的圖表識別模型使用此技術
• fused_rms_norm_ext 是融合優化版本，性能更好

API 差異:

# 基礎版本 (3.0.0 提供)
paddle.incubate.nn.functional.fused_rms_norm(x, norm_weight, ...)

# 擴展版本 (圖表識別需要)
paddle.incubate.nn.functional.fused_rms_norm_ext(x, norm_weight, ...)
# 提供額外的參數和優化

代碼位置

• 限制代碼: backend/app/services/ocr_service.py:217
• PP-StructureV3 初始化: backend/app/services/ocr_service.py:211

---

📝 更新 OpenSpec

如果驗證後發現新版本已支持，請更新以下文件：

1. openspec/changes/add-gpu-acceleration-support/tasks.md

   • 標記任務 5.4 為完成
   • 更新版本限制說明

2. openspec/changes/add-gpu-acceleration-support/proposal.md

   • 更新 "Known Issues" 部分
   • 記錄解決的 PaddlePaddle 版本

3. README.md

   • 移除或更新 "Known Limitations" 部分
   • 添加圖表識別功能說明

---

🆘 故障排除

問題: 升級後仍然不可用

1. 確認 PaddlePaddle 版本:

   python -c "import paddle; print(paddle.__version__)"
   

2. 檢查 API 可用性:

   python -c "import paddle.incubate.nn.functional as F; print(hasattr(F, 'fused_rms_norm_ext'))"
   

3. 完全重新安裝:

   pip uninstall paddlepaddle paddlepaddle-gpu -y
   pip install paddlepaddle>=3.2.0 --force-reinstall
   

問題: 啟用後出現錯誤

如果啟用圖表識別後出現錯誤:

AttributeError: module 'paddle.incubate.nn.functional' has no attribute 'fused_rms_norm_ext'

解決方案:

1. 確認 PaddlePaddle 版本 >= 支持的最低版本
2. 回退到 use_chart_recognition=False
3. 等待 PaddlePaddle 官方更新

---

📚 相關資源

• PaddlePaddle 官方文檔
• PaddleOCR GitHub
• PP-StructureV3 文檔
• PaddlePaddle PyPI

---

最後更新: 2025-11-16 創建者: Development Team 驗證腳本: backend/verify_chart_recognition.py