pdf_signature_extraction/NEW_SESSION_HANDOFF.md

# 新对话交接文档 - PP-OCRv5研究

**日期**: 2025-10-29
**前序对话**: PaddleOCR-Cover分支开发
**当前分支**: `paddleocr-improvements` (稳定)
**新分支**: `pp-ocrv5-research` (待创建)

---

## 🎯 任务目标

研究和实现 **PP-OCRv5** 的手写签名检测功能

---

## 📋 背景信息

### 当前状况

✅ **已有稳定方案** (`paddleocr-improvements` 分支):
- PaddleOCR 2.7.3 + OpenCV Method 3
- 86.5%手写保留率
- 区域合并算法工作良好
- 测试: 1个PDF成功检测2个签名

⚠️ **PP-OCRv5升级遇到问题**:
- PaddleOCR 3.3.0 API完全改变
- 旧服务器代码不兼容
- 需要深入研究新API

### 为什么要研究PP-OCRv5？

**文档显示**: https://www.paddleocr.ai/main/en/version3.x/algorithm/PP-OCRv5/PP-OCRv5.html

PP-OCRv5性能提升:
- 手写中文检测: **0.706 → 0.803** (+13.7%)
- 手写英文检测: **0.249 → 0.841** (+237%)
- 可能支持直接输出手写区域坐标

**潜在优势**:
1. 更好的手写识别能力
2. 可能内置手写/印刷分类
3. 更准确的坐标输出
4. 减少复杂的后处理

---

## 🔧 技术栈

### 服务器环境

```
Host: 192.168.30.36 (Linux GPU服务器)
SSH: ssh gblinux
目录: ~/Project/paddleocr-server/
```

**当前稳定版本**:
- PaddleOCR: 2.7.3
- numpy: 1.26.4
- opencv-contrib-python: 4.6.0.66
- 服务器文件: `paddleocr_server.py`

**已安装但未使用**:
- PaddleOCR 3.3.0 (PP-OCRv5)
- 临时服务器: `paddleocr_server_v5.py` (未完成)

### 本地环境

```
macOS
Python: 3.14
虚拟环境: venv/
客户端: paddleocr_client.py
```

---

## 📝 核心问题

### 1. API变更

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

# 返回格式:
# [[[box], (text, confidence)], ...]
```

**新API (3.3.0)** - ⚠️ 未完全理解:
```python
# 方式1: 传统方式 (Deprecated)
result = ocr.ocr(image_np)  # 警告: Please use predict instead

# 方式2: 新方式
from paddlex import create_model
model = create_model("???")  # 模型名未知
result = model.predict(image_np)

# 返回格式: ???
```

### 2. 遇到的错误

**错误1**: `cls` 参数不再支持
```python
# 错误: PaddleOCR.predict() got an unexpected keyword argument 'cls'
result = ocr.ocr(image_np, cls=False)  # ❌
```

**错误2**: 返回格式改变
```python
# 旧代码解析失败:
text = item[1][0]       # ❌ IndexError
confidence = item[1][1]  # ❌ IndexError
```

**错误3**: 模型名称错误
```python
model = create_model("PP-OCRv5_server")  # ❌ Model not supported
```

---

## 🎯 研究任务清单

### Phase 1: API研究 (优先级高)

- [ ] **阅读官方文档**
  - PP-OCRv5完整文档
  - PaddleX API文档
  - 迁移指南 (如果有)

- [ ] **理解新API**
  ```python
  # 需要搞清楚:
  1. 正确的导入方式
  2. 模型初始化方法
  3. predict()参数和返回格式
  4. 如何区分手写/印刷
  5. 是否有手写检测专用功能
  ```

- [ ] **编写测试脚本**
  - `test_pp_ocrv5_api.py` - 测试基础API调用
  - 打印完整的result数据结构
  - 对比v4和v5的返回差异

### Phase 2: 服务器适配

- [ ] **重写服务器代码**
  - 适配新API
  - 正确解析返回数据
  - 保持REST接口兼容

- [ ] **测试稳定性**
  - 测试10个PDF样本
  - 检查GPU利用率
  - 对比v4性能

### Phase 3: 手写检测功能

- [ ] **查找手写检测能力**
  ```python
  # 可能的方式:
  1. result中是否有 text_type 字段?
  2. 是否有专门的 handwriting_detection 模型?
  3. 是否有置信度差异可以利用?
  4. PP-Structure 的 layout 分析?
  ```

- [ ] **对比测试**
  - v4 (当前方案) vs v5
  - 准确率、召回率、速度
  - 手写检测能力

### Phase 4: 集成决策

- [ ] **性能评估**
  - 如果v5更好 → 升级
  - 如果改进不明显 → 保持v4

- [ ] **文档更新**
  - 记录v5使用方法
  - 更新PADDLEOCR_STATUS.md

---

## 🔍 调试技巧

### 1. 查看完整返回数据

```python
import pprint
result = model.predict(image)
pprint.pprint(result)  # 完整输出所有字段

# 或者
import json
print(json.dumps(result, indent=2, ensure_ascii=False))
```

### 2. 查找官方示例

```bash
# 在服务器上查找PaddleOCR安装示例
find ~/Project/paddleocr-server/venv/lib/python3.12/site-packages/paddleocr -name "*.py" | grep example

# 查看源码
less ~/Project/paddleocr-server/venv/lib/python3.12/site-packages/paddleocr/paddleocr.py
```

### 3. 查看可用模型

```python
from paddlex.inference.models import OFFICIAL_MODELS
print(OFFICIAL_MODELS)  # 列出所有支持的模型名
```

### 4. Web文档搜索

重点查看:
- https://github.com/PaddlePaddle/PaddleOCR
- https://www.paddleocr.ai
- https://github.com/PaddlePaddle/PaddleX

---

## 📂 文件结构

```
/Volumes/NV2/pdf_recognize/
├── CURRENT_STATUS.md          # 当前状态文档 ✅
├── NEW_SESSION_HANDOFF.md     # 本文件 ✅
├── PADDLEOCR_STATUS.md        # 详细技术文档 ✅
├── SESSION_INIT.md            # 初始会话信息
│
├── paddleocr_client.py        # 稳定客户端 (v2.7.3) ✅
├── paddleocr_server_v5.py     # v5服务器 (未完成) ⚠️
│
├── test_paddleocr_client.py           # 基础测试
├── test_mask_and_detect.py            # 遮罩+检测
├── test_opencv_separation.py          # Method 1+2
├── test_opencv_advanced.py            # Method 3 (最佳) ✅
├── extract_signatures_paddleocr_improved.py  # 完整Pipeline
│
└── check_rejected_for_missing.py      # 诊断脚本
```

**服务器端** (`ssh gblinux`):
```
~/Project/paddleocr-server/
├── paddleocr_server.py        # v2.7.3稳定版 ✅
├── paddleocr_server_v5.py     # v5版本 (待完成) ⚠️
├── paddleocr_server_backup.py # 备份
├── server_stable.log          # 当前运行日志
└── venv/                      # 虚拟环境
```

---

## ⚡ 快速启动

### 启动稳定服务器 (v2.7.3)

```bash
ssh gblinux
cd ~/Project/paddleocr-server
source venv/bin/activate
python paddleocr_server.py
```

### 测试连接

```bash
# 本地Mac
cd /Volumes/NV2/pdf_recognize
source venv/bin/activate
python test_paddleocr_client.py
```

### 创建新研究分支

```bash
cd /Volumes/NV2/pdf_recognize
git checkout -b pp-ocrv5-research
```

---

## 🚨 注意事项

### 1. 不要破坏稳定版本

- `paddleocr-improvements` 分支保持稳定
- 所有v5实验在新分支 `pp-ocrv5-research`
- 服务器保留 `paddleocr_server.py` (v2.7.3)
- 新代码命名: `paddleocr_server_v5.py`

### 2. 环境隔离

- 服务器虚拟环境可能需要重建
- 或者用Docker隔离v4和v5
- 避免版本冲突

### 3. 性能测试

- 记录v4和v5的具体指标
- 至少测试10个样本
- 包括速度、准确率、召回率

### 4. 文档驱动

- 每个发现记录到文档
- API用法写清楚
- 便于未来维护

---

## 📊 成功标准

### 最低目标

- [ ] 成功运行PP-OCRv5基础OCR
- [ ] 理解新API调用方式
- [ ] 服务器稳定运行
- [ ] 记录完整文档

### 理想目标

- [ ] 发现手写检测功能
- [ ] 性能超过v4方案
- [ ] 简化Pipeline复杂度
- [ ] 提升准确率 > 90%

### 决策点

**如果v5明显更好** → 升级到v5，废弃v4
**如果v5改进不明显** → 保持v4，v5仅作研究记录
**如果v5有bug** → 等待官方修复，暂用v4

---

## 📞 问题排查

### 遇到问题时

1. **先查日志**: `tail -f ~/Project/paddleocr-server/server_stable.log`
2. **查看源码**: 在venv里找PaddleOCR代码
3. **搜索Issues**: https://github.com/PaddlePaddle/PaddleOCR/issues
4. **降级测试**: 确认v2.7.3是否还能用

### 常见问题

**Q: 服务器启动失败?**
A: 检查numpy版本 (需要 < 2.0)

**Q: 找不到模型?**
A: 模型名可能变化，查看OFFICIAL_MODELS

**Q: API调用失败?**
A: 对比官方文档，可能参数格式变化

---

## 🎓 学习资源

### 官方文档

1. **PP-OCRv5**: https://www.paddleocr.ai/main/en/version3.x/algorithm/PP-OCRv5/PP-OCRv5.html
2. **PaddleOCR GitHub**: https://github.com/PaddlePaddle/PaddleOCR
3. **PaddleX**: https://github.com/PaddlePaddle/PaddleX

### 相关技术

- PaddlePaddle深度学习框架
- PP-Structure文档结构分析
- 手写识别 (Handwriting Recognition)
- 版面分析 (Layout Analysis)

---

## 💡 提示

### 如果发现内置手写检测

可能的用法:
```python
# 猜测1: 返回结果包含类型
for item in result:
    text_type = item.get('type')  # 'printed' or 'handwritten'?

# 猜测2: 专门的layout模型
from paddlex import create_model
layout_model = create_model("PP-Structure")
layout_result = layout_model.predict(image)
# 可能返回: text, handwriting, figure, table...

# 猜测3: 置信度差异
# 手写文字置信度可能更低
```

### 如果没有内置手写检测

那么当前OpenCV Method 3仍然是最佳方案，v5仅提供更好的OCR准确度。

---

## ✅ 完成检查清单

研究完成后，确保:

- [ ] 新API用法完全理解并文档化
- [ ] 服务器代码重写并测试通过
- [ ] 性能对比数据记录
- [ ] 决策文档 (升级 vs 保持v4)
- [ ] 代码提交到 `pp-ocrv5-research` 分支
- [ ] 更新 `CURRENT_STATUS.md`
- [ ] 如果升级: 合并到main分支

---

**祝研究顺利！** 🚀

有问题随时查阅:
- `CURRENT_STATUS.md` - 当前方案详情
- `PADDLEOCR_STATUS.md` - 技术细节和问题分析

**最重要**: 记录所有发现，无论成功或失败，都是宝贵经验！