Files
douyin_guaji-main/docs/ocr_engine_decision.md
T
Codex 0131be7869 切换 OCR 默认引擎到 PaddleOCR v4-mobile 并简化预处理
- 默认引擎改为 PaddleOCR PP-OCRv4_mobile(实测 369ms/张,比 EasyOCR 629ms 更快且精度大幅提升,coupon 等关键图错字一片 -> 全对)
- EasyOCR 仅作回退,移除"小图自动放大+锐化+对比度增强"预处理(实测对 Paddle 是负优化,会引入伪影/重复字)
- analyse_pic_word 加 LRU 内容哈希缓存(256 条),重复读图直接命中
- analyse_pic_digits 从 200 行重复实现精简成 30 行委托 + 数字过滤
- 统一两处 OCR 初始化为 _build_paddle / _build_easyocr 工厂,消除重复
- 设置 FLAGS_use_mkldnn=false 绕开 Win + Paddle 3.x 的 oneDNN+PIR 不兼容 bug(实测 FLAGS_enable_pir_in_executor=0 也修不掉,关 oneDNN 是当前唯一可行解)
- 决策依据/速度数据/已知问题归档到 docs/ocr_engine_decision.md
- 业务接口完全向后兼容
2026-05-21 10:50:30 +08:00

85 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# OCR 引擎选型决策记录
> 2026-05 决策依据。基于 ~30 张项目截图实测对比,决定换掉 EasyOCR,统一用 **PaddleOCR PP-OCRv4_mobile**。
---
## 结论
| 引擎 | 平均/张 | 关键图精度 | 选用 |
|---|---|---|---|
| **PaddleOCR v4-mobile** | **369ms** | ✅ 12 段全对 | **首选** |
| PaddleOCR v5-mobile | 407ms | ⚠️ 偶尔合并段落 | 略差 |
| RapidOCR-ONNX | 1494ms | ✅ 12 段全对 | 兜底 |
| PaddleOCR v5-server | 2395ms | ⚠️ 多噪声字符 | 不用(重型) |
| EasyOCR | 629ms | ❌ "官方保障"→"膏方保腰" | **回退** |
| PaddleOCR v4-server | 2721ms | ⚠️ 切分错误 | 不用(重型) |
业务图都是裁切后的小区域(300×120 倒计时框、600×260 内容框),mobile 模型完胜 server 模型。
## 关键修复:Win + Paddle 3.x oneDNN+PIR bug
`ConvertPirAttribute2RuntimeAttribute not support pir::ArrayAttribute<pir::DoubleAttribute>` 在 paddle 3.3 + paddleocr 3.5 + Win 必现。
实测结论:
- ❌ `FLAGS_enable_pir_in_executor=0` 修不掉(PIR 已强制默认)
- ❌ paddleocr 3.x 强制要 paddle 3.x,不能降级
- ✅ **`enable_mkldnn=False`** 是当前唯一可行解,代价是 CPU 推理慢 20-30%
代码里在 `operations/ocr_operations.py` 模块顶层设置 `FLAGS_use_mkldnn=false` + `enable_mkldnn=False`。等 paddle 上游补全 `onednn_instruction.cc:118` 的属性转换分支后可以删掉这行。
## 已知次优配置
- PaddleOCR `predict()` 是 3.x 推荐 API,`ocr()` 仍兼容(代码做了运行时检测)
- 自定义"放大+锐化+对比度增强"预处理对 PaddleOCR 是负优化(实测 `coupon_full_title` 输出 `全全场通用` 重复字、`coupon_limit` 多出 `工品` 噪声),已删除。PaddleOCR 内部的 resize/normalize 已经够用
## 速度数据(19 张 + 11 张混合裁切框,CPU 模式)
### 速度横向对比(按场景分组的代表数据)
| 图片类型 | v4-mobile | v5-mobile | EasyOCR |
|---|---|---|---|
| 复杂多文字(coupon.png 整图)| 2293ms | 2148ms | 2168ms |
| 长文字行(banner_long.png)| 898ms | 910ms | 451ms |
| 短文字(coupon_title.png)| 163ms | 162ms | 279ms |
| 数字小框(coupon_30.png)| 18ms | 106ms | 147ms |
| 福袋裁切区域(fudai_*)| ~150-1700ms | ~150-2200ms | ~470-5500ms |
| 空白图标 | ~10-100ms | ~10-150ms | ~30-100ms |
EasyOCR 在彩色背景大图上特别慢(fudai 1280×1280 跑 5 秒+),且关键内容图错字率极高。
### v4-mobile vs v5-mobile 精度差
- coupon.png:v4-mobile `一单回本 | 全场通用` 正确切分,v5-mobile `一单回本全场通用` 合并
- banner_long.png:v4-mobile `上一个 | 下一个` 正确,v5-mobile `E— | 下-` 错误
v4-mobile 综合最优。
## 生效的优化
`operations/ocr_operations.py`:
1. 切到 PaddleOCR v4-mobile 优先(之前 EasyOCR 优先)
2. 加 LRU 结果缓存(256 条),重复图直接命中(业务里 cut_pic 短时间常重读相同区域)
3. 抽出 `PADDLE_KWARGS` / `_build_paddle()` / `_build_easyocr()` 工厂消除重复
`Underlying_Operations.py`:
1. `__init__` / `_ensure_ocr` 都对齐到 Paddle 优先
2. `analyse_pic_word` 加缓存层(基于 blake2b 内容哈希 + change_color)
3. 删掉小图自动放大+锐化+对比度增强(实测负优化)
4. PaddleOCR 切到 `predict()` 新 API
5. `analyse_pic_digits` 从 200 行精简到 30 行委托 + 数字过滤
业务接口完全向后兼容,调用方零改动。
## 测试用图
`assets/`:项目自带 9 张图
裁切扩展:从 coupon.png/fudai.png 裁出多种难度的小区域(~22 张)测试模型对小裁切框的表现
## 维护提示
- 缓存大小:环境变量 `OCR_CACHE_MAX`(默认 256,设 0 禁用)
- 缓存统计:`from operations.ocr_operations import cache_stats; print(cache_stats())`
- 调试图保存:环境变量 `SAVE_OCR_DEBUG_IMAGES=1`
- 跳过初始化(仅做点击不需要 OCR 的流程):环境变量 `SKIP_OCR_INIT=1`