522 lines
17 KiB
Markdown
522 lines
17 KiB
Markdown
# OCR Server
|
||
|
||
基于 FastAPI 和 PaddleOCR **PP-OCRv5** 的图片文字识别服务,支持 Windows 和 Ubuntu 22.04(CPU;GPU 需要额外安装对应的 PaddlePaddle GPU 版本)。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
ocr-server/
|
||
├── config.yaml # 项目配置文件(启动前修改)
|
||
├── http/ocr-server.http # IDEA / IntelliJ HTTP Client 测试请求
|
||
├── models/ # 可随发布包分发的 PP-OCRv5 模型(约 166 MB)
|
||
│ └── official_models/
|
||
│ ├── PP-OCRv5_server_det/
|
||
│ └── 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 耗时
|
||
```
|
||
|
||
## 模型位置和下载策略
|
||
|
||
当前已经预下载并放入项目目录:
|
||
|
||
```text
|
||
models/official_models/PP-OCRv5_server_det
|
||
models/official_models/PP-OCRv5_server_rec
|
||
```
|
||
|
||
当前分发包内的模型是 PP-OCRv5 中文服务模型,总大小约 166 MB。模型文件只读使用,服务不会修改模型目录中的权重文件。
|
||
|
||
服务启动后不会立即加载模型。上传接口会立即把图片放入等待队列;第一次有工作线程开始识别时:
|
||
|
||
1. 优先检查 `model_dir/official_models/` 下的检测模型和识别模型;
|
||
2. 模型文件完整时,直接使用项目内模型,不访问网络;
|
||
3. 缺少任意模型时,只下载缺少的模型,并保存到同一个 `model_dir`;
|
||
4. 后续请求继续复用同一个进程内的 OCR 实例。
|
||
|
||
默认模型目录是项目根目录下的 `models`,可以直接修改项目根目录的 `config.yaml`:
|
||
|
||
```yaml
|
||
model_dir: /opt/ocr-server/models
|
||
```
|
||
|
||
配置文件中的路径支持绝对路径,也支持相对于项目根目录的路径。服务启动时读取一次配置,修改后需要重启服务。
|
||
|
||
也可以手动提前下载或补齐模型:
|
||
|
||
```powershell
|
||
uv run python scripts/download_models.py
|
||
```
|
||
|
||
脚本会读取 `config.yaml`,把模型下载到 `model_dir` 指定的目录。模型下载需要联网;完整分发包可以直接携带整个 `models/` 目录,从而不依赖首次启动联网。下载时不会覆盖已有完整模型目录。
|
||
|
||
## 不同速度档位和模型选择
|
||
|
||
当前项目默认使用 PP-OCRv5 中文服务模型:
|
||
|
||
```yaml
|
||
det_model_name: PP-OCRv5_server_det
|
||
rec_model_name: PP-OCRv5_server_rec
|
||
```
|
||
|
||
PaddleOCR 还提供更小的移动端模型,但 PP-OCRv5 中文识别模型当前默认映射为 `PP-OCRv5_server_rec`;不要只把检测模型替换成其他版本而保持识别模型不变,模型版本和配套模型应成套切换。
|
||
|
||
| 档位 | 检测模型 | 识别模型 | 特点 |
|
||
| --- | --- | --- | --- |
|
||
| 速度优先 | PP-OCRv4_mobile_det | PP-OCRv4_mobile_rec | 体积和 CPU 推理开销更小,但不是 PP-OCRv5,中文准确率可能下降 |
|
||
| 当前默认 | PP-OCRv5_server_det | PP-OCRv5_server_rec | 中文准确率优先,模型约 166 MB |
|
||
| 新版模型 | PP-OCRv6_medium_det | PP-OCRv6_medium_rec | 需要单独下载并验证,模型版本不是 PP-OCRv5 |
|
||
|
||
切换前建议:
|
||
|
||
1. 先把当前 `models/` 完整复制成独立备份,例如 `models.backup-ppocrv5/`;
|
||
2. 将新模型下载到另一个目录,例如 `models-ppocrv4-mobile/`;
|
||
3. 只修改 `config.yaml` 的 `model_dir` 和两个模型名称;
|
||
4. 用 `scripts/benchmark_ocr.py` 和真实业务图片对比耗时、漏检率和准确率;
|
||
5. 验证不满意时,把 `model_dir` 改回原目录即可,不改动原模型。
|
||
|
||
当前没有自动下载或替换任何小模型,也没有修改现有 PP-OCRv5 权重。服务只读加载模型;若要切换模型,必须使用新的模型目录或先制作备份。
|
||
|
||
### 不换模型的加速方式
|
||
|
||
先尝试以下配置,不会修改模型文件:
|
||
|
||
```yaml
|
||
text_det_limit_side_len: 640
|
||
text_recognition_batch_size: 1
|
||
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
|
||
uv run python scripts/benchmark_ocr.py
|
||
```
|
||
|
||
修改 `config.yaml` 后重新执行,比较输出的 `elapsed_ms`。建议至少使用 10 张代表性图片,不要只根据一张图片决定模型或参数。
|
||
|
||
## Python 版本说明
|
||
|
||
本项目的 Python 版本约束是 `>=3.10,<3.14`,当前项目固定为 Python 3.12:
|
||
|
||
```text
|
||
.python-version = 3.12
|
||
```
|
||
|
||
这次切换**没有修改系统全局 Python,也没有卸载 Python 3.15**。`uv python pin 3.12` 只修改了当前项目的 `.python-version` 文件;项目使用的 Python 3.12 是 uv 管理的独立解释器,位置是:
|
||
|
||
```text
|
||
C:\Users\zimoyin\AppData\Roaming\uv\python\cpython-3.12-windows-x86_64-none\python.exe
|
||
```
|
||
|
||
机器上原有的 Python 3.15 仍在:
|
||
|
||
```text
|
||
C:\Users\zimoyin\AppData\Local\Python\pythoncore-3.15-64\python.exe
|
||
```
|
||
|
||
项目虚拟环境位于:
|
||
|
||
```text
|
||
D:\code\work\ocr-server\.venv\Scripts\python.exe
|
||
```
|
||
|
||
在 Ubuntu 上,建议使用系统 Python 3.10–3.12 或 uv 创建项目虚拟环境,不会影响系统其他 Python 项目。
|
||
|
||
## Windows 安装和启动
|
||
|
||
源码启动:
|
||
|
||
```powershell
|
||
cd D:\code\work\ocr-server
|
||
uv sync
|
||
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
|
||
host: 0.0.0.0
|
||
port: 8000
|
||
device: cpu
|
||
ocr_workers: 1
|
||
```
|
||
|
||
然后启动:
|
||
|
||
```powershell
|
||
uv run ocr-server
|
||
```
|
||
|
||
也可以:
|
||
|
||
```powershell
|
||
uv run python -m uvicorn ocr_server.app:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
## Ubuntu 22.04 安装和启动
|
||
|
||
适用于 Ubuntu 22.04 x86_64 CPU 环境(PaddlePaddle 官方 wheel 通常不覆盖 ARM 架构):
|
||
|
||
```bash
|
||
sudo apt-get update
|
||
sudo apt-get install -y curl libgl1 libglib2.0-0
|
||
|
||
cd /opt/ocr-server
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
# 重新打开 shell,或按安装提示加载 ~/.local/bin
|
||
uv python install 3.12
|
||
uv sync --python 3.12
|
||
# 按需修改项目根目录 config.yaml,然后启动
|
||
uv run ocr-server
|
||
```
|
||
|
||
如果服务器不能访问模型下载源,请在联网机器上执行 `scripts/download_models.py`,将完整项目的 `models/` 目录复制到 Ubuntu 服务器,再启动服务。依赖安装仍需要提前完成;完全离线安装还需要准备本地 Python wheel 缓存。
|
||
|
||
如果 Ubuntu 已经安装了兼容的 Python 3.10–3.12,也可以使用系统 Python(以实际可用的 `python3.10`、`python3.11` 或 `python3.12` 命令替换下面示例):
|
||
|
||
```bash
|
||
python3.10 -m venv .venv
|
||
.venv/bin/python -m pip install -U pip
|
||
.venv/bin/python -m pip install -e .
|
||
.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
|
||
|
||
### 1. 上传图片
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/upload \
|
||
-F "file=@./receipt.jpg"
|
||
```
|
||
|
||
返回示例(所有接口统一使用 `code`、`message`、`data`):
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"file_id": "b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51",
|
||
"filename": "receipt.jpg",
|
||
"size": 123456,
|
||
"width": 1600,
|
||
"height": 1200,
|
||
"status": "queued",
|
||
"progress": 0,
|
||
"queue_position": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 图片转文字
|
||
|
||
上传成功后图片会进入内存等待队列,默认由 1 个 OCR 工作线程按 FIFO 顺序识别。调用 `/api/v1/i2t` 时:
|
||
|
||
- `queued`:任务还在等待,返回 `progress` 和 `queue_position`;
|
||
- `processing`:任务正在识别,返回当前 `progress`;
|
||
- `completed`:返回 JSON 识别结果;
|
||
- `failed`:返回错误信息。
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/i2t \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"file_id":"b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51"}'
|
||
```
|
||
|
||
未完成时返回示例:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"file_id": "b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51",
|
||
"status": "processing",
|
||
"progress": 20,
|
||
"queue_position": null,
|
||
"ocr_started_at": "2026-10-11T10:20:30.123456Z",
|
||
"ocr_finished_at": null,
|
||
"ocr_elapsed_ms": null,
|
||
"result": null,
|
||
"error": null
|
||
}
|
||
}
|
||
```
|
||
|
||
完成时 `result` 使用紧凑的 JSON 对象映射:
|
||
|
||
```json
|
||
{
|
||
"text": "BOARDING PASS",
|
||
"polygon": {
|
||
"text1": {
|
||
"text": "BOARDING",
|
||
"confidence": 0.9841,
|
||
"Location": {
|
||
"xtop": 420,
|
||
"ytop": 20,
|
||
"xbottom": 660,
|
||
"ybottom": 66
|
||
},
|
||
"line": 1,
|
||
"paragraphs": 1
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- 不再返回 `segments` 数组、`lines` 数组和 `paragraphs` 数组;
|
||
- 每个 `textN` 对象包含文字、置信度、矩形坐标、行编号和段编号;
|
||
- 同一行的 `line` 值相同;
|
||
- 同一自然段的 `paragraphs` 值相同;
|
||
- `Location` 包含 `xtop`、`ytop`、`xbottom`、`ybottom`。
|
||
|
||
两个检测框在同一文本行时会分配相同的 `line` 编号;相邻文本行属于同一自然段时会分配相同的 `paragraphs` 编号。可选 `min_confidence`(0–1)过滤低置信度片段,服务会重新计算行编号和段编号。
|
||
|
||
## IDEA HTTP Client 测试
|
||
|
||
已提供:
|
||
|
||
```text
|
||
http/ocr-server.http
|
||
```
|
||
|
||
在 IDEA 中打开文件,项目已附带 PaddleOCR 官方示例图片:
|
||
|
||
```text
|
||
http/fixtures/general_ocr_002.png
|
||
```
|
||
|
||
然后按顺序执行:
|
||
|
||
1. 健康检查;
|
||
2. 上传图片;
|
||
3. IDEA 自动保存上传响应中的 `file_id`;
|
||
4. 立即调用图片转文字接口,观察 `queued` / `processing` 进度;
|
||
5. 重复调用直到返回 `completed` 和 JSON 识别结果。
|
||
|
||
该测试图片来源于 PaddleOCR 官方示例。也可以把自己的图片复制到 `http/fixtures/`,再修改 `.http` 文件中的文件路径。
|
||
|
||
## 配置
|
||
|
||
配置统一写在项目根目录的 `config.yaml`,服务启动时读取一次,修改后重启生效:
|
||
|
||
```yaml
|
||
host: 127.0.0.1
|
||
port: 8000
|
||
upload_dir: data/uploads
|
||
model_dir: models
|
||
det_model_name: PP-OCRv5_server_det
|
||
rec_model_name: PP-OCRv5_server_rec
|
||
ocr_workers: 1
|
||
device: cpu
|
||
lang: ch
|
||
max_upload_mb: 10
|
||
max_image_pixels: 20000000
|
||
text_det_limit_side_len: 960
|
||
text_det_limit_type: max
|
||
text_det_thresh: 0.3
|
||
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
|
||
```
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `host` | `127.0.0.1` | 监听地址 |
|
||
| `port` | `8000` | 监听端口 |
|
||
| `upload_dir` | `data/uploads` | 图片存储目录 |
|
||
| `model_dir` | `models` | PaddleOCR 模型下载和缓存目录 |
|
||
| `det_model_name` | `PP-OCRv5_server_det` | 文本检测模型名称 |
|
||
| `rec_model_name` | `PP-OCRv5_server_rec` | 文本识别模型名称 |
|
||
| `ocr_workers` | `1` | OCR 工作线程数;每个线程独立加载一份模型 |
|
||
| `max_upload_mb` | `10` | 单文件大小上限 |
|
||
| `max_image_pixels` | `20000000` | 图片像素上限 |
|
||
| `device` | `cpu` | `cpu` 或 GPU 设备配置 |
|
||
| `lang` | `ch` | PaddleOCR 语言 |
|
||
| `text_det_limit_side_len` | `960` | 检测图像最长边;调小可加速,可能漏检小字 |
|
||
| `text_det_limit_type` | `max` | 检测缩放限制类型 |
|
||
| `text_det_thresh` | `0.3` | 检测二值化阈值 |
|
||
| `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` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` |
|
||
|
||
接口文档:启动后访问 <http://127.0.0.1:8000/docs>。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
uv run pytest -q
|
||
uv pip check
|
||
```
|