# PP-OCRv5 研究發現

**日期**: 2025-01-27
**分支**: pp-ocrv5-research
**狀態**: 研究完成

---

## 📋 研究摘要

我們成功升級並測試了 PP-OCRv5，以下是關鍵發現：

### ✅ 成功完成
1. PaddleOCR 升級：2.7.3 → 3.3.2
2. 新 API 理解和驗證
3. 手寫檢測能力測試
4. 數據結構分析

### ❌ 關鍵限制
**PP-OCRv5 沒有內建的手寫 vs 印刷文字分類功能**

---

## 🔧 技術細節

### API 變更

**舊 API (2.7.3)**:
```python
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='ch', show_log=False)
result = ocr.ocr(image_np, cls=False)
```

**新 API (3.3.2)**:
```python
from paddleocr import PaddleOCR

ocr = PaddleOCR(
    text_detection_model_name="PP-OCRv5_server_det",
    text_recognition_model_name="PP-OCRv5_server_rec",
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False
    # ❌ 不再支持: show_log, cls
)

result = ocr.predict(image_path)  # ✅ 使用 predict() 而不是 ocr()
```

### 主要 API 差異

| 特性 | v2.7.3 | v3.3.2 |
|------|--------|--------|
| 初始化 | `PaddleOCR(lang='ch')` | `PaddleOCR(text_detection_model_name=...)` |
| 預測方法 | `ocr.ocr()` | `ocr.predict()` |
| `cls` 參數 | ✅ 支持 | ❌ 已移除 |
| `show_log` 參數 | ✅ 支持 | ❌ 已移除 |
| 返回格式 | `[[[box], (text, conf)], ...]` | `OCRResult` 對象 with `.json` 屬性 |
| 依賴 | 獨立 | 需要 PaddleX >=3.3.0 |

---

## 📊 返回數據結構

### v3.3.2 返回格式

```python
result = ocr.predict(image_path)
json_data = result[0].json['res']

# 可用字段：
json_data = {
    'input_path': str,                    # 輸入圖片路徑
    'page_index': None,                   # PDF 頁碼（圖片為 None）
    'model_settings': dict,               # 模型配置
    'dt_polys': list,                     # 檢測多邊形框 (N, 4, 2)
    'dt_scores': list,                    # 檢測置信度
    'rec_texts': list,                    # 識別文字
    'rec_scores': list,                   # 識別置信度
    'rec_boxes': list,                    # 矩形框 [x_min, y_min, x_max, y_max]
    'rec_polys': list,                    # 識別多邊形框
    'text_det_params': dict,              # 檢測參數
    'text_rec_score_thresh': float,       # 識別閾值
    'text_type': str,                     # ⚠️ 'general' (語言類型，不是手寫分類)
    'textline_orientation_angles': list,  # 文字方向角度
    'return_word_box': bool               # 是否返回詞級框
}
```

---

## 🔍 手寫檢測功能測試

### 測試問題
**PP-OCRv5 是否能區分手寫和印刷文字？**

### 測試結果：❌ 不能

#### 測試過程
1. ✅ 發現 `text_type` 字段
2. ❌ 但 `text_type = 'general'` 是**語言類型**，不是書寫風格
3. ✅ 查閱官方文檔確認
4. ❌ 沒有任何字段標註手寫 vs 印刷

#### 官方文檔說明
- `text_type` 可能的值：'general', 'ch', 'en', 'japan', 'pinyin'
- 這些值指的是**語言/腳本類型**
- **不是**手寫 (handwritten) vs 印刷 (printed) 的分類

### 結論
PP-OCRv5 雖然能**識別**手寫文字，但**不會標註**某個文字區域是手寫還是印刷。

---

## 📈 性能提升（根據官方文檔）

### 手寫文字識別準確率

| 類型 | PP-OCRv4 | PP-OCRv5 | 提升 |
|------|----------|----------|------|
| 手寫中文 | 0.706 | 0.803 | **+13.7%** |
| 手寫英文 | 0.249 | 0.841 | **+237%** |

### 實測結果（full_page_original.png）

**v3.3.2 (PP-OCRv5)**:
- 檢測到 **50** 個文字區域
- 平均置信度：~0.98
- 示例：
  - "依本會計師核閱結果..." (0.9936)
  - "在所有重大方面有違反..." (0.9976)

**待測試**: v2.7.3 的對比結果（需要回退測試）

---

## 💡 升級影響分析

### 優勢
1. ✅ **更好的手寫識別能力**（+13.7%）
2. ✅ **可能檢測到更多手寫區域**
3. ✅ **更高的識別置信度**
4. ✅ **統一的 Pipeline 架構**

### 劣勢
1. ❌ **無法區分手寫和印刷**（仍需 OpenCV Method 3）
2. ⚠️ **API 完全不兼容**（需重寫服務器代碼）
3. ⚠️ **依賴 PaddleX**（額外的依賴）
4. ⚠️ **OpenCV 版本升級**（4.6 → 4.10）

---

## 🎯 對我們項目的影響

### 當前方案（v2.7.3 + OpenCV Method 3）
```
PDF → PaddleOCR 檢測 → 遮罩印刷文字 → OpenCV Method 3 分離手寫 → VLM 驗證
                        ↑ 86.5% 手寫保留率
```

### PP-OCRv5 方案
```
PDF → PP-OCRv5 檢測 → 遮罩印刷文字 → OpenCV Method 3 分離手寫 → VLM 驗證
      ↑ 可能檢測更多手寫   ↑ 仍然需要！
```

### 關鍵發現
**PP-OCRv5 不能替代 OpenCV Method 3！**

---

## 🤔 升級建議

### 升級的理由
1. 更好地檢測手寫簽名（+13.7% 準確率）
2. 可能減少漏檢
3. 更高的識別置信度可以幫助後續分析

### 不升級的理由
1. 當前方案已經穩定（86.5% 保留率）
2. 仍然需要 OpenCV Method 3
3. API 重寫成本高
4. 額外的依賴和複雜度

### 推薦決策

**階段性升級策略**：

1. **短期（當前）**：
   - ✅ 保持 v2.7.3 穩定方案
   - ✅ 繼續使用 OpenCV Method 3
   - ✅ 在更多樣本上測試當前方案

2. **中期（如果需要優化）**：
   - 對比測試 v2.7.3 vs v3.3.2 在真實簽名樣本上的性能
   - 如果 v5 明顯減少漏檢 → 升級
   - 如果差異不大 → 保持 v2.7.3

3. **長期**：
   - 關注 PaddleOCR 是否會添加手寫分類功能
   - 如果有 → 重新評估升級價值

---

## 📝 技術債務記錄

### 如果決定升級到 v3.3.2

需要完成的工作：

1. **服務器端**：
   - [ ] 重寫 `paddleocr_server.py` 適配新 API
   - [ ] 測試 GPU 利用率和速度
   - [ ] 處理 OpenCV 4.10 兼容性
   - [ ] 更新依賴文檔

2. **客戶端**：
   - [ ] 更新 `paddleocr_client.py`（如果 REST 接口改變）
   - [ ] 適配新的返回格式

3. **測試**：
   - [ ] 10+ 樣本對比測試
   - [ ] 性能基準測試
   - [ ] 穩定性測試

4. **文檔**：
   - [ ] 更新 CURRENT_STATUS.md
   - [ ] 記錄 API 遷移指南
   - [ ] 更新部署文檔

---

## ✅ 完成的工作

1. ✅ 升級 PaddleOCR: 2.7.3 → 3.3.2
2. ✅ 理解新 API 結構
3. ✅ 測試基礎功能
4. ✅ 分析返回數據結構
5. ✅ 測試手寫分類功能（結論：無）
6. ✅ 查閱官方文檔驗證
7. ✅ 記錄完整研究過程

---

## 🎓 學到的經驗

1. **API 版本升級風險**：主版本升級通常有破壞性變更
2. **功能驗證的重要性**：文檔提到的「手寫支持」不等於「手寫分類」
3. **現有方案的價值**：OpenCV Method 3 仍然是必需的
4. **性能 vs 複雜度權衡**：不是所有性能提升都值得立即升級

---

## 🔗 相關文檔

- [CURRENT_STATUS.md](./CURRENT_STATUS.md) - 當前穩定方案
- [NEW_SESSION_HANDOFF.md](./NEW_SESSION_HANDOFF.md) - 研究任務清單
- [PADDLEOCR_STATUS.md](./PADDLEOCR_STATUS.md) - 詳細技術分析

---

## 📌 下一步

建議用戶：

1. **立即行動**：
   - 在更多 PDF 樣本上測試當前方案
   - 記錄成功率和失敗案例

2. **評估升級**：
   - 如果當前方案滿意 → 保持 v2.7.3
   - 如果遇到大量漏檢 → 考慮 v3.3.2

3. **長期監控**：
   - 關注 PaddleOCR GitHub Issues
   - 追蹤是否有手寫分類功能的更新

---

**結論**: PP-OCRv5 提升了手寫識別能力，但不能替代 OpenCV Method 3 來分離手寫和印刷文字。當前方案（v2.7.3 + OpenCV Method 3）已經足夠好，除非遇到性能瓶頸，否則不建議立即升級。