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

from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='ch')
result = ocr.ocr(image_np, cls=False)

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

新API (3.3.0) - ⚠️ 未完全理解:

# 方式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 参数不再支持

# 错误: PaddleOCR.predict() got an unexpected keyword argument 'cls'
result = ocr.ocr(image_np, cls=False)  # ❌

错误2: 返回格式改变

# 旧代码解析失败:
text = item[1][0]       # ❌ IndexError
confidence = item[1][1]  # ❌ IndexError

错误3: 模型名称错误

model = create_model("PP-OCRv5_server")  # ❌ Model not supported

---

🎯 研究任务清单

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

• 阅读官方文档

  • PP-OCRv5完整文档
  • PaddleX API文档
  • 迁移指南 (如果有)

• 理解新API

  # 需要搞清楚:
  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: 手写检测功能

• 查找手写检测能力

  # 可能的方式:
  1. result中是否有 text_type 字段?
  2. 是否有专门的 handwriting_detection 模型?
  3. 是否有置信度差异可以利用?
  4. PP-Structure 的 layout 分析?
  

• 对比测试

  • v4 (当前方案) vs v5
  • 准确率、召回率、速度
  • 手写检测能力

Phase 4: 集成决策

• 性能评估

  • 如果v5更好 → 升级
  • 如果改进不明显 → 保持v4

• 文档更新

  • 记录v5使用方法
  • 更新PADDLEOCR_STATUS.md

---

🔍 调试技巧

1. 查看完整返回数据

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

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

2. 查找官方示例

# 在服务器上查找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. 查看可用模型

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)

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

测试连接

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

创建新研究分支

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)

---

💡 提示

如果发现内置手写检测

可能的用法:

# 猜测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 - 技术细节和问题分析

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