Files
ocr-server/README.md
T
zimoyin 5ddda545f5 init2
2026-10-12 11:00:09 +08:00

522 lines
17 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 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
```