Files
ocr-server/README.md
T
zimoyin cf7088a13d revert: remove enable_detection and return_word_box options
按需求移除两个开关:
- enable_detection:跳过检测直接识别,实测只对单行图有效,多行文档会返回空结果
- return_word_box:字/词级坐标,默认即关闭且开销在噪声内,无实际收益
恢复正常的两段式链路:文本检测 → 文本识别。

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-13 19:16:21 +08:00

949 lines
38 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.bat # Windows 下载/补齐模型
├── scripts/download-models.sh # Ubuntu/Linux 下载/补齐模型
├── scripts/download_models.py # Python 下载入口
└── 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
```
配置文件中的路径支持绝对路径,也支持相对于项目根目录的路径。服务启动时读取一次配置,修改后需要重启服务。
也可以手动提前下载或补齐模型。推荐使用对应平台的快捷脚本:
Windows(PowerShell / CMD):
```powershell
scripts\download-models.bat
```
Ubuntu/Linux:
```bash
chmod +x scripts/download-models.sh
./scripts/download-models.sh
```
脚本会读取项目根目录的 `config.yaml`,把当前配置所需的检测模型和识别模型下载到 `model_dir/official_models/`。模型下载需要联网;完整分发包可以直接携带整个 `models/` 目录,从而不依赖首次启动联网。下载时不会覆盖已有完整模型目录。
也可以直接调用 Python 脚本:
```powershell
uv run python scripts/download_models.py
```
如果配置切换了模型名称,重新执行下载脚本即可补齐新模型。脚本不会删除或修改已有的其它模型目录。
## 不同速度档位和模型选择
当前项目默认使用 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
det_model_name: PP-OCRv5_server_det # 检测保持 v5,保证召回
rec_model_name: PP-OCRv4_mobile_rec # 识别换移动端,快约 8 倍
cpu_threads: max # 吃满逻辑核心
enable_mkldnn: true # 依赖 paddlepaddle 3.2.x
text_recognition_batch_size: 8
text_det_limit_side_len: 512
```
叠加效果(1.png,1920x1080,339 个文本框;经服务完整路径实测):
| 配置 | 耗时 | 框数 | 字符数 |
| --- | --- | --- | --- |
| 初始状态(v5rec,3.3.1,无 oneDNN) | 729.39s | 339 | 1747 |
| + 移动端识别(3.3.1,无 oneDNN) | 91.25s | 339 | 1746 |
| + oneDNN(paddlepaddle 3.2.2) | **26.17s(约 27.9 倍)** | 339 | 1746 |
**提速约 28 倍,而框数与字符数与精度优先档基本一致**,召回没有损失。
同一配置下另外两张图(完整服务路径):
| 图片 | 耗时 | 框数 | 字符数 |
| --- | --- | --- | --- |
| 2.png (1920x1080) | 7.49s(原 213.52s) | 73 | 430 |
| general_ocr_002.png (896x528) | 8.01s(原 70.45s) | 35 | 245 |
### cpu_threads 取 max 的含义
```yaml
cpu_threads: max # = os.cpu_count(),本机 20 逻辑核 → 20
cpu_threads: 8 # 也可以直接写具体数字
```
`max` 是「省心」选项,**不保证最快**:本机为 20 逻辑核 / 14 物理核,超过物理核心数后超线程会争抢,收益递减,还会挤占同机其它服务。建议用 `benchmark_ocr.py` 实测 8 / 14 / max 三档再定。
### 不换模型的加速方式
先尝试以下配置,不会修改模型文件:
```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` 字段与日志中的进度一致。
### 为什么日志 handler 挂在 `ocr_server` logger 而不是 root
⚠️ 这是一个容易复现的坑,修改日志配置时请注意。
Paddle 在初始化推理引擎时会把 **root logger 的级别改成 `WARNING`**(实测:初始化前 `INFO`,初始化后变 `WARNING`)。如果日志 handler 挂在 root 上、依赖 root 的级别,那么从「加载引擎」开始的所有 `INFO` 日志都会被静默过滤,表现为:
```text
进度 5% 任务开始
加载 OCR 引擎: ...
(此后 10% / 20% / 50% / 80% / 100% 全部消失)
```
而接口其实是正常工作的(`progress` 字段仍会到 100),只是**日志被吞了**,非常容易误判为「卡住了」。
因此 `logging_setup.py` 把 handler 挂在 `ocr_server` logger 上,显式设置级别并 `propagate = False`,从而不受 Paddle 改动 root 的影响。`tests/test_logging.py` 里有对应的回归测试。
调整日志级别:
```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 秒 ← 主要瓶颈
```
注意:同一配置在不同时间实测波动较大(同一图片分别测到 66 秒和 128 秒),比较参数时请在相同时间段多测几次,不要只看单次结果。
### 是否使用多核
不是单核推理。PaddleX 默认 `cpu_threads = 10`(可用 `cpu_threads` 配置项覆盖),测试机为 20 逻辑核 / 14 物理核,实测 CPU 占用:
```text
检测阶段 CPU 约 94%~105% (约 1 个核)
识别阶段 CPU 约 534%~686% (约 5.3~6.9 个核)
平均约 553%,即约 5.5 个核,20 核未跑满
```
结论:
- 识别阶段是多线程的,约占 5~7 个核;
- 检测阶段接近单核,这是关闭 oneDNN 后检测耗时约 13 秒的主要原因;
- 20 核没有跑满,说明并行效率不高,瓶颈在「未启用 oneDNN 的 CPU 算子」,而不是核心数不够。
线程数对耗时的影响(同图、`batch 8`):
```text
cpu_threads=4 约 114 秒
cpu_threads=10 约 60 秒
```
可调整 `cpu_threads` 实测,建议不超过物理核心数,并用 `benchmark_ocr.py` 对比。
关闭 oneDNN 是必须的:`enable_mkldnn=True` 会触发 PaddlePaddle 3.3.1 的缺陷并直接失败:
```text
NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support
(at onednn_instruction.cc:118)
```
因此该配置下慢的根因是「CPU 推理未启用 oneDNN」,不是队列或接口阻塞。
### 让 oneDNN 可用:换 PaddlePaddle 版本(实测快 1.64 倍)
`paddlepaddle 3.3.1` 是 PyPI 上当前最新版,它的 PIR + oneDNN 组合有缺陷,无法启用 oneDNN(`enable_new_ir=False` 也绕不过,因为新执行器是强制启用的)。
降级到 `paddlepaddle 3.2.2` 后 oneDNN 可正常启用。同一台机器、同一模型、同一张图、`cpu_threads=20`、`batch=8`,顺序执行无干扰:
| PaddlePaddle | oneDNN | 识别耗时 | 行数 |
| --- | --- | --- | --- |
| 3.3.1 | 关闭(当前默认) | 84.01s | 34 |
| 3.2.2 | 关闭 | 86.84s | 34 |
| 3.2.2 | **开启** | **51.23s** | 34 |
结论:
- **单纯降级不变快**(84.01s vs 86.84s,属于噪声),提速完全来自 oneDNN;
- **3.2.2 + oneDNN 快 1.64 倍**;
- 换 PaddlePaddle 版本**不换模型**,权重文件一个字节都不动。
#### oneDNN 是纯提速,不改变输出
同一环境下只切换 `enable_mkldnn` 开关,输出逐字节一致:
```text
官方样例图 paddle=3.3.1 mkldnn=False n=34 chars=252 md5=ecb944dadcdb
官方样例图 paddle=3.2.2 mkldnn=True n=34 chars=252 md5=ecb944dadcdb
1.png paddle=3.2.2 mkldnn=False predict=148.12s segments=452 chars=2374 md5=0ca69ecd7aaf
1.png paddle=3.2.2 mkldnn=True predict= 30.95s segments=452 chars=2374 md5=0ca69ecd7aaf
```
1.png 上开启 oneDNN 后 **148.12s → 30.95s(快 4.8 倍)**,而 md5 完全相同。所以 oneDNN 只影响速度,不影响识别结果。
#### 降级版本本身不改变输出
项目环境内实测(同一模型、同一参数、同一张 1.png、`side=640`):
| PaddlePaddle | oneDNN | 检测框数 | 字符数 |
| --- | --- | --- | --- |
| 3.3.1 | 关闭 | 339 | 1746 |
| 3.2.2 | 开启 | 339 | 1746 |
同一配置连续跑 3 次,结果稳定为 339 框 / 1746 字符,说明**输出是确定性的,且 PaddlePaddle 版本不影响检测结果**,提速完全来自 oneDNN。
一次遗留说明:在项目外的独立虚拟环境里,同样的参数曾测到 452 框 / 2374 字符,与项目环境不一致。两个环境的依赖版本经比对完全相同(paddlepaddle 3.2.2 / paddleocr 3.7.0 / paddlex 3.7.2 / opencv 4.10.0.84 / numpy 2.3.5),模型目录也是同一个,**该差异原因未定位**。由于两个环境各自内部都重复稳定,且 oneDNN 的中性结论在两个环境分别验证过(各自开启/关闭输出 md5 一致),这不影响上述结论,但仍建议以项目环境(即实际服务环境)的实测为准。
#### 启用所需的改动(均已完成)
1. 依赖固定为 `paddlepaddle>=3.2,<3.3`(见 `pyproject.toml`,请勿手动升到 3.3.x);
2. `enable_mkldnn` 已作为配置项暴露,在 `config.yaml` 中设置即可(默认 `true`)。
本次验证在项目外的独立虚拟环境完成(`paddleocr 3.7.0` + `paddlex 3.7.2` + `paddlepaddle 3.2.2` 可正常推理),未改动你的项目环境和模型。
该提速与「v5 检测 + 移动端识别」的提速**相互独立、可以叠加**:1.png 从 729s 降到 30.95s(约 23.5 倍)。
### 换成移动端模型:速度提升极大,但密集文本会严重丢字
⚠️ 这一档**不适合文本密集的图片**,务必先用自己的图验证。
统一参数:`text_det_limit_side_len: 640`、`cpu_threads: 20`、`text_recognition_batch_size: 8`。
**稀疏图片(官方示例 896x528,文本少)**
| 模型组合 | 体积 | 耗时 | 片段数 | 字符数 |
| --- | --- | --- | --- | --- |
| `PP-OCRv5_server_det` + `PP-OCRv5_server_rec` | 约 167 MB | 70.45s | 34 | 253 |
| `PP-OCRv4_mobile_det` + `PP-OCRv4_mobile_rec` | 约 16 MB | 10.34s | 36 | — |
稀疏图上两者识别内容大体一致,移动端仅漏掉一行小字水印,看起来差异不大。
**密集图片(1920x1080,文本多)—— 差距是数量级的**
| 图片 | 模型组合 | 耗时 | 片段数 | 字符数 |
| --- | --- | --- | --- | --- |
| 1.png | v5 server | 747.96s | 339 | 1747 |
| 1.png | v4 mobile | **7.82s** | **46** | **166(仅剩 10%)** |
| 2.png | v5 server | 213.52s | 73 | 428 |
| 2.png | v4 mobile | **6.03s** | **27** | **243(剩 57%)** |
1.png 上移动端快了约 95 倍,但**丢掉了约 90% 的文字**。主要瓶颈在 `PP-OCRv4_mobile_det`:它只检出 46 个框,而 v5 server 检出 339 个,密集小字基本没检测出来。
结论:
- 图片文本稀疏(票据、证件、少数字段)→ 移动端可用,收益巨大;
- 图片文本密集(表格、文档、截图)→ **不要整体换成移动端**,检测器会大面积丢字;
- 判断标准不是分辨率,而是**文本密度**,必须用自己的真实图片实测。
### 推荐搭配:v5 检测 + 移动端识别
丢字的元凶是 `PP-OCRv4_mobile_det`(检测器),不是移动端识别模型。把检测保留 v5、只换识别,可以同时保住召回和速度。
1.png(1920x1080,339 个文本框),`text_det_limit_side_len: 640`、`cpu_threads: 20`、`batch: 8`:
| 检测模型 | 识别模型 | 耗时 | 片段数 | 字符数 |
| --- | --- | --- | --- | --- |
| `PP-OCRv5_server_det` | `PP-OCRv5_server_rec` | 729.39s | 339 | 1747 |
| `PP-OCRv5_server_det` | `PP-OCRv4_mobile_rec` | **91.25s** | 339 | **1746** |
| `PP-OCRv4_mobile_det` | `PP-OCRv4_mobile_rec` | 7.82s | **46** | **166** |
**快 8 倍,框数一致,字符数只差 1 个。** 识别阶段从 721s 降到 83.7s,说明瓶颈在识别模型,而移动端识别模型在密集文本上没有明显损失。
文本级对比(官方样例图,两者都是 35 个片段,检测模型相同):
```text
v5rec : 登机牌|date|舱位|…|MU 2379|…|票号TKT NO.|…|起飞前1O分钟关闭GATESCLOSE1OMINUTESBEFORE DEPARTURETIME
mobrec: 登机牌|DATE|舱位|…|MU2379|…|票号TKTNO.|…|起飞前10分钟关闭 GATESCLOSE10MINUTESBEFOREDEPARTURETIME
```
该样本中移动端识别有两处反而更准:`date` 识别为 `DATE`、`前1O分钟` 识别为 `前10分钟`(v5 把数字 0 错认为字母 O)。主要差异只是空格分词方式。
配置写法(两个模型名可以独立指定、跨版本混用):
```yaml
det_model_name: PP-OCRv5_server_det
rec_model_name: PP-OCRv4_mobile_rec
```
注意:混用不同代际的检测/识别模型属于非官方推荐组合,本项目实测可用且字符数一致,但仍请用你自己的图片验证后再上线。
### text_det_limit_side_len 与文本密度强相关
对 1920x1080 的密集图片实测:
| 边长 | 1.png | 2.png |
| --- | --- | --- |
| 640 | 339 框 / 1747 字符 | 73 框 / 428 字符 |
| 320 | **0 框 / 0 字符** | 8 框 / 59 字符 |
1.png 在 320 下**完全检不出任何文字**:1920px 按 6 倍下采样后,约 10px 高的文字只剩约 1.7px。这不是平滑降精度,而是断崖式失效。
因此:
- 大图请保持 `640` 或更高,**不要低于 640**;
- `480` 以下只适合小尺寸、大字号的图片;
- 检测耗时本身只占 1%~10%(上面两图分别是 7.9s 和 9.0s),压低它对总时长几乎没有帮助。
### 识别耗时与文本框数量成正比
这是本项目的核心性能特征,来自实测:
```text
1.png 339 框 → 识别 740s (约 2.2 秒/框)
2.png 73 框 → 识别 204s (约 2.8 秒/框)
官方样例 34 框 → 识别 62s (约 1.8 秒/框)
```
所以决定单张图耗时的是**框数**,而不是图片像素数。降低耗时的手段按有效性排序:
1. 减少框数(代价是丢字,例如提高 `text_det_box_thresh`);
2. 换更快的识别模型(注意上面的丢字风险);
3. 提高 `cpu_threads`、`text_recognition_batch_size`;
4. 让 oneDNN 可用(换 PaddlePaddle 版本)或使用 GPU。
切换方式(`config.yaml` 里已预置注释行,去掉注释即可):
```yaml
det_model_name: PP-OCRv4_mobile_det
rec_model_name: PP-OCRv4_mobile_rec
```
模型文件需要存在于 `model_dir/official_models/` 下;不存在时首次识别会自动下载。当前仓库的 `models/official_models/` 已包含这两套移动端模型,改完配置重启即可离线切换。
切换前必须用 `benchmark_ocr.py` 和真实业务图片对比**字符数**:移动端体积小、速度快,但在文本密集的图片上会大面积丢字(实测 1.png 字符数只剩约 10%),详见上文「换成移动端模型」。这两个模型属于 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)过滤低置信度片段,服务会重新计算行编号和段编号。
### 3. 字段抽取(预设标签)
识别完成后可以按键值对抽取结构化字段,结果放在响应的 `data.fields` 里。
在 `config.yaml` 里配置预设:
```yaml
extract_fields:
- name: 姓名
aliases: [患者姓名, 病人姓名]
pattern: '[一-鿿〇·]{1,12}' # 中文汉字 + 〇 + 间隔号,最多 12 字
max_length: 12
- name: 检查号
pattern: '[A-Za-z0-9-]{1,24}'
max_length: 24
- name: 年龄
pattern: '\d{1,3}\s*岁' # 边界含匹配内容,结果会带「岁」
compact: true
- name: 临床诊断
end_pattern: '[;;,,。]' # 终止符语义,不返回该标点
max_length: 50
extract_separators: [":", ":"]
```
每个字段可用的配置项:
| 配置项 | 说明 | 边界 |
| --- | --- | --- |
| `name` | 输出字段名,同时作为默认标签 | — |
| `aliases` | 其他标签写法,可选 | — |
| `compact` | `true` 时删除值内部所有空白(`43 岁` → `43岁`) | — |
| `pattern` | **值内容正则**。从值起始处匹配,只取匹配到的部分;不匹配则该字段不返回 | **含**匹配内容 |
| `end_pattern` | **结束正则**。值在此处截断 | **不含**匹配内容 |
| `max_length` | 值最大字符数,超出则截断 | — |
| `multiline` | 值是否允许跨行,默认 `false`(换行即结束) | — |
| `occurrence` | 同名标签出现多次时取哪个,`first`(默认)或 `last` | — |
| `separator_optional` | `true` 时标签后不带冒号也能抽(默认 `false`) | — |
| `label_linebreak` | `true` 时允许标签内部跨行,如 `姓` + `名:`(默认 `false`) | — |
| `row` | 只从第 N 行取值;`-1`(默认)不限定 | — |
`pattern` 与 `end_pattern` 的边界语义相反,用途也不同:
```text
pattern: '\d{1,3}\s*岁' → "43岁" (含,用来精确取形状)
end_pattern: '[;;,,]' → "大便习惯改变" (不含,用来切掉终止符)
```
正则写在**单引号**里即可,反斜杠不用转义(如 `'\d{1,3}'`)。正则写错会在**服务启动时**就报错,不会等到请求时才失败。
匹配与清洗规则:
- **标签内部允许空白**:配置「姓名」也能匹配 OCR 识别出的「姓 名」「床 号」「镜 型」;
- **同一行多个字段自动切分**:`检查号:26100830064姓名:万镭` 可同时抽出两个字段;
- **值的结束位置**:下一个**已配置**标签 / `end_pattern` / 换行(除非 `multiline`)/ `max_length` / 文本结尾;
- **自动清洗**:去掉零宽字符,任意空白(含换行)归一成单空格,去掉首尾空白、开头残留分隔符和结尾孤立标点(如 `;`);
- **空值不返回**:`床号:` 后面没有内容时,该字段不会出现在结果里;
- **同一字段取第一次出现的值**;
- **必须带分隔符**:`姓名 万镭`(无冒号)不会被抽取。
### 关于汉字字符类 `[一-鿿]`
写中文 pattern 时常用「字面范围」写法,比如 `[一-龥]`、`[一-鿿]`,含义是「某个 Unicode 范围内任意一个汉字」:
| 写法 | 含义 |
| --- | --- |
| `一` | 汉字「一」,即范围内的第一个字 |
| `-` | 表示范围 |
| `龥` | U+9FA5,旧版 Unicode 里 CJK 基本区的最后一个字 |
| `鿿` | U+9FFF,CJK 基本区(U+4E00–U+9FFF)真正的末位 |
⚠️ `[一-龥]`(到 U+9FA5)会漏掉两处,实测:
```text
'二〇二六' → 只匹配到 '二' (〇 是 U+3007,不在基本区)
'龦' → 不匹配 (U+9FA6,Unicode 4.1 之后新增)
```
推荐写法(覆盖整个基本区并补上「〇」):
```yaml
pattern: '[一-鿿〇]{1,12}'
# 等价写法(用码位转义表示,结果相同):
pattern: '[\u4e00-\u9fff〇]{1,12}'
```
写法说明:
- 单引号里的 `一` 不需要额外转义,Python 正则能直接识别;用码位写法更明确,不依赖「鿿」这种生僻字;
- `〇`(U+3007)单独加上,用于「二〇二六」这类写法;
- 少数民族姓名的间隔号 `·`(U+00B7)也要单独加,如 `[一-鿿〇·]`;
- **CJK 扩展区(生僻姓氏,如 U+20000 以上)不在任何基本区范围内**。需要完整覆盖汉字时,Python 内置 `re` 做不到,只能用第三方 `regex` 模块的 `\p{Han}`;本项目未引入该依赖。
### row:按行锁定字段位置
`row: N` 让字段只从**第 N 行**取值。行是由识别结果的**坐标**算出来的(bbox 纵向重叠的文本框归为同一行),所以「行」是真实的视觉行。
典型用途:报告的表头字段集中在固定几行,而正文或界面噪声里也会出现同样的字样,此时用 `row` 可以把它们排除掉。
一张真实报告截图的实测行结构(23 行):
```text
第 9 行 年龄:43岁性别:女检查号:26100830064姓名:万镭
第 10 行 镜型:CF-HQ290I床号:科室:消化内科门诊门诊号:701785075
第 11 行 临床诊断:大便习惯改变;
```
注意这份材料里第 3 行还出现了 `报告-万镭`——正文同样含患者姓名。行为对比:
```text
不限定行 -> 姓名 = 张三 (取第一次出现,可能是页眉副本或正文)
row: 9 -> 姓名 = 万镭 (精确锁定目标行)
```
注意事项:
- 行号随版面变化,**换模板就要重新确认行号**;锁定后如果没取到值会返回空(`include_empty: true` 时返回空串),不会静默取错;
- 没有行信息时(例如直接调用库函数不传 `rows`),`row` 限定的字段取不到值,**不会退回全文**,避免误取;
- `row` 与 `label_linebreak` 不要同时用:跨行标签在单行文本里不存在,会取不到值。
### 其他开关
- **`separator_optional: true`**:标签后不带冒号也抽。代价是误命中率明显上升,只在冒号经常被 OCR 漏识时才打开。
- **`label_linebreak: true`**:允许标签内部跨行(`姓` + `名:`)。最多允许一个换行,避免把相隔很远的字拼成标签。
- **`extract_include_empty: true`**(全局):未命中的字段返回空串而非不出现,便于调用方用固定 schema 消费。
```yaml
extract_include_empty: true
# -> {"姓名": "万镭", "床号": "", "镜型": "", ...}
```
### 防止取错:机制与建议
已内置的防护:
| 风险 | 机制 |
| --- | --- |
| 值粘连到下一个字段 | 值在**下一个已配置标签**前截断;再用 `pattern` 限定形状 |
| 值吞掉后面的正文 | `end_pattern` 终止符、`max_length` 上限、默认换行即结束 |
| 短标签嵌在长标签里(`号` vs `检查号`) | 匹配器**非重叠扫描 + 长标签优先**,同时配置时不会误命中 |
| 值里出现别的标签字样(`姓名不详`) | 标签**必须紧跟分隔符**才算标签,故不会截断值 |
| 低置信度噪声被抽成字段 | 抽取基于 `min_confidence` 过滤后的文本,调高该参数即可 |
| 同名标签重复出现取错 | 用 `occurrence: last` 明确取最后一个 |
| 配置冲突(标签被两个字段共用、字段名重复) | **服务启动时直接报错**,不会带病运行 |
| 正则写错 | 启动时校验并报错 |
| 不知道该值从哪来 | `log_level: DEBUG` 会输出每个字段的命中明细与未命中列表 |
使用建议:
1. **能用 `pattern` 就用**——它是性价比最高的手段,既约束形状又防止粘连:
```yaml
pattern: '[A-Za-z0-9-]{1,24}' # 编号类
pattern: '\d{1,3}\s*岁' # 带单位的数值
pattern: '[一-鿿〇·]{1,12}' # 中文姓名
```
2. **把相邻字段都配上**,边界才生效(`姓名检查号` 这类粘连靠标签互相切分)。
3. **不要用过于宽泛的标签**,例如只配一个「号」,会把「检查号」「门诊号」都当成它。
4. **`compact: true` 要慎用**:它会删掉值里所有空格,地址类字段会被压成一串。
5. **`max_length` 只截断不报错**:需要「超长即视为未命中」时,用 `pattern` 的限定量词(如 `[一-鿿]{1,12}`)。
6. 上线前用**自己的真实样本**跑一遍,尤其注意同名标签重复、正副本这类场景。
⚠️ **边界只对「已配置」的标签生效**。例如只配置了 `姓名` 时,`姓名:万镭性别:女` 中的 `性别:` 不是边界,值可能被吞成 `万镭性别`。两种解决办法:
1. 把相邻字段也配置上(推荐,`性别` 本身通常也要抽);
2. 用 `pattern` 限定形状,例如 `[一-龥·]{1,2}`、`\d+`、`[A-Za-z0-9-]+` —— 这是最稳的做法。
对一张真实报告截图的实测结果:
```json
"fields": {
"检查号": "26100830064",
"姓名": "万镭",
"性别": "女",
"年龄": "43岁",
"门诊号": "701785075",
"科室": "消化内科门诊",
"镜型": "CF-HQ290I",
"临床诊断": "大便习惯改变"
}
```
抽取发生在查询时(`/api/v1/i2t`),基于 `min_confidence` 过滤后的文本,因此改预设或调 `min_confidence` 不需要重新识别。`extract_fields` 留空(或删除该配置)即关闭此功能。
## 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` | 识别批量大小;内存足够时可提高 |
| `cpu_threads` | `max` | CPU 推理线程数;正整数或 `max`(`max` = 吃满所有逻辑核心) |
| `enable_mkldnn` | `true` | 是否启用 oneDNN 加速;**需要 `paddlepaddle` 3.2.x**,见下方说明 |
| `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` |
接口文档:启动后访问 <http://127.0.0.1:8000/docs>。
## 测试
```bash
uv run pytest -q
uv pip check
```