This commit is contained in:
zimoyin
2026-10-12 11:00:09 +08:00
parent 150ad63f24
commit 5ddda545f5
20 changed files with 659 additions and 19 deletions
+163 -1
View File
@@ -14,6 +14,12 @@ ocr-server/
│ └── PP-OCRv5_server_rec/
├── data/uploads/ # 上传图片运行时目录
├── src/ocr_server/
├── scripts/start.ps1 # Windows 源码/发布包启动
├── scripts/start.bat # Windows 启动快捷方式
├── scripts/start.sh # Ubuntu 源码/发布包启动
├── scripts/package-windows.ps1 # Windows exe 打包
├── scripts/packaged_entry.py # PyInstaller 入口
├── scripts/package-ubuntu.sh # Ubuntu ELF 打包
├── scripts/download_models.py # 下载或补齐缺少的模型
└── scripts/benchmark_ocr.py # 测量当前配置的 OCR 耗时
```
@@ -91,6 +97,97 @@ ocr_workers: 1
`text_det_limit_side_len` 从 `960` 调到 `640` 通常可以降低检测耗时,但小字可能漏检。`text_recognition_batch_size` 主要影响单张图片包含很多文本框时的吞吐;增大到 `2` 或 `4` 会增加内存,单张简单图片不一定更快。
## 日志与推理进度
服务使用普通换行日志,不使用 `\r` 覆盖式进度条,便于复制到文件或在 IDEA 控制台查看。
识别过程中会输出固定的进度检查点:
```text
2026-10-12 10:00:00 INFO [ocr_server.task] file_id=xxx 已加入 OCR 队列 image=1.png
2026-10-12 10:00:01 INFO [ocr_server.task] file_id=xxx 开始处理 image=1.png
2026-10-12 10:00:01 INFO [ocr_server.task] file_id=xxx 进度 5% 任务开始,准备推理
2026-10-12 10:00:02 INFO [ocr_server.ocr] OCR 引擎加载完成
2026-10-12 10:00:02 INFO [ocr_server.task] file_id=xxx 进度 10% 模型已就绪
2026-10-12 10:00:02 INFO [ocr_server.task] file_id=xxx 进度 20% 图片已解码,开始文字检测
2026-10-12 10:00:40 INFO [ocr_server.task] file_id=xxx 进度 50% 文字检测完成
2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 进度 80% 文字识别完成
2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 进度 100% 识别完成
2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 处理结束 status=completed elapsed=94000.00ms
```
进度含义:
| 进度 | 含义 |
| --- | --- |
| 5% | 工作线程取到任务,准备推理 |
| 10% | OCR 引擎就绪(首次包含模型加载时间) |
| 20% | 图片已解码,开始文字检测 |
| 50% | 文字检测完成 |
| 80% | 文字识别完成 |
| 100% | 结果组装完成,任务结束 |
其中 50% 和 80% 来自真实的检测模型和识别模型调用完成,不是估算值。`/api/v1/i2t` 返回的 `progress` 字段与日志中的进度一致。
调整日志级别:
```yaml
log_level: DEBUG
```
## 已知性能限制
当前环境中 PP-OCRv5 服务模型在 CPU 上关闭 oneDNN 后推理较慢。实测(20 核 CPU、官方 896x528 示例图):
```text
默认线程(10)+ batch 1 : 约 65 秒 34 行
batch 8 + 默认线程 : 约 60 秒 34 行
batch 8 + cpu_threads 4 : 约 114 秒
```
按阶段拆分(`log_level: INFO` 的进度日志可直接读出):
```text
20% → 50% 文字检测 约 13 秒
50% → 80% 文字识别 约 50 秒 ← 主要瓶颈
```
关闭 oneDNN 是必须的:`enable_mkldnn=True` 会触发 PaddlePaddle 3.3.1 的缺陷并直接失败:
```text
NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support
(at onednn_instruction.cc:118)
```
因此该配置下慢的根因是「CPU 推理未启用 oneDNN」,不是队列或接口阻塞。
### 换成移动端模型(实测约 3.4 倍提速)
同一张图片、同样 `text_det_limit_side_len: 960` 与 `text_recognition_batch_size: 8`:
| 模型组合 | 模型体积 | 识别耗时 | 识别行数 |
| --- | --- | --- | --- |
| `PP-OCRv5_server_det` + `PP-OCRv5_server_rec` | 约 167 MB | 约 60 秒 | 34 |
| `PP-OCRv4_mobile_det` + `PP-OCRv4_mobile_rec` | 约 16 MB | 约 18 秒 | 39 |
切换方式:
```yaml
det_model_name: PP-OCRv4_mobile_det
rec_model_name: PP-OCRv4_mobile_rec
```
模型文件需要存在于 `model_dir/official_models/` 下;不存在时首次识别会自动下载。
切换前建议先用 `benchmark_ocr.py` 和真实业务图片对比准确率:移动端模型体积小、速度快,但中文识别精度通常低于 PP-OCRv5 服务模型,且这两个模型属于 PP-OCRv4,不是 PP-OCRv5。不同业务对精度敏感度不同,请以实际样本为准。
其他提速方向:
1. 降低 `text_det_limit_side_len`(例如 `640`),可减少检测耗时;
2. 升级到 oneDNN 与 PIR 兼容的 PaddlePaddle 版本后再开启 `enable_mkldnn`;
3. GPU 部署。
### 如何测速
```powershell
@@ -129,12 +226,38 @@ D:\code\work\ocr-server\.venv\Scripts\python.exe
## Windows 安装和启动
源码启动:
```powershell
cd D:\code\work\ocr-server
uv sync
uv run ocr-server
powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1
# 或双击 scripts\start.bat
```
Windows 打包为 exe:
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1 -Clean
```
发布目录:
```text
dist\ocr-server\
├── ocr-server.exe
├── config.yaml
└── models\
```
启动 exe:
```powershell
.\dist\ocr-server\ocr-server.exe
```
`config.yaml` 和 `models/` 是发布目录外置资源,可以独立修改或替换;不要直接改 exe 内部文件。发布目录约 1 GB(其中 `_internal/` 约 665 MB,模型约 166 MB),这是 PaddlePaddle 原生运行库带来的正常体积。
启动前修改项目根目录的 `config.yaml`:
```yaml
@@ -184,6 +307,43 @@ python3.10 -m venv .venv
.venv/bin/ocr-server
```
Ubuntu 源码启动:
```bash
cd /opt/ocr-server
uv sync --python 3.12
chmod +x scripts/start.sh
./scripts/start.sh
```
Ubuntu 22.04 打包为原生 ELF 二进制:
```bash
cd /opt/ocr-server
chmod +x scripts/package-ubuntu.sh
./scripts/package-ubuntu.sh
```
发布目录:
```text
dist/ocr-server/
├── ocr-server
├── config.yaml
└── models/
```
启动:
```bash
./dist/ocr-server/ocr-server
# 或:./scripts/start.sh
```
Windows 不能直接生成 Ubuntu ELF 二进制。`package-ubuntu.sh` 必须在 Ubuntu/Linux 构建机执行;Windows 使用 `package-windows.ps1` 生成 exe。两个平台的发布包不能混用,建议分别构建、分别测试。
打包脚本使用 PyInstaller 的 `--onedir` 模式,而不是单文件模式:PaddlePaddle、PaddleOCR 和模型都作为外置目录分发,启动更稳定,也方便替换 `config.yaml` 或模型目录。构建机需要联网安装依赖;如果发布包中已有完整模型,运行时不需要重新下载模型。
GPU 部署不使用当前 CPU 依赖作为判断依据,请按照 PaddlePaddle 官方文档安装与 CUDA、cuDNN、驱动匹配的 GPU 版本,然后再安装本项目依赖。
## API
@@ -326,6 +486,7 @@ text_det_box_thresh: 0.6
text_det_unclip_ratio: 1.5
text_rec_score_thresh: 0.0
text_recognition_batch_size: 1
log_level: INFO
```
| 配置项 | 默认值 | 说明 |
@@ -348,6 +509,7 @@ text_recognition_batch_size: 1
| `text_det_unclip_ratio` | `1.5` | 检测框扩张比例 |
| `text_rec_score_thresh` | `0.0` | 识别结果阈值 |
| `text_recognition_batch_size` | `1` | 识别批量大小;内存足够时可提高 |
| `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` |
接口文档:启动后访问 <http://127.0.0.1:8000/docs>。