zimoyin a7d4ff6454 feat: add enable_detection switch to skip text detection
enable_detection: false 跳过检测模型,直接把整图当一行文本送识别。
实测:单行图可正确识别;多行整图因识别模型固定缩放到高 48px 会返回空结果,已加告警。

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-13 15:59:25 +08:00
2026-10-13 13:16:57 +08:00
2026-10-11 02:26:26 +08:00

OCR Server

基于 FastAPI 和 PaddleOCR PP-OCRv5 的图片文字识别服务,支持 Windows 和 Ubuntu 22.04(CPU;GPU 需要额外安装对应的 PaddlePaddle GPU 版本)。

目录结构

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 耗时

模型位置和下载策略

当前已经预下载并放入项目目录:

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:

model_dir: /opt/ocr-server/models

配置文件中的路径支持绝对路径,也支持相对于项目根目录的路径。服务启动时读取一次配置,修改后需要重启服务。

也可以手动提前下载或补齐模型。推荐使用对应平台的快捷脚本:

Windows(PowerShell / CMD):

scripts\download-models.bat

Ubuntu/Linux:

chmod +x scripts/download-models.sh
./scripts/download-models.sh

脚本会读取项目根目录的 config.yaml,把当前配置所需的检测模型和识别模型下载到 model_dir/official_models/。模型下载需要联网;完整分发包可以直接携带整个 models/ 目录,从而不依赖首次启动联网。下载时不会覆盖已有完整模型目录。

也可以直接调用 Python 脚本:

uv run python scripts/download_models.py

如果配置切换了模型名称,重新执行下载脚本即可补齐新模型。脚本不会删除或修改已有的其它模型目录。

不同速度档位和模型选择

当前项目默认使用 PP-OCRv5 中文服务模型:

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 权重。服务只读加载模型;若要切换模型,必须使用新的模型目录或先制作备份。

当前推荐配置(实测最快且保召回)

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 的含义

cpu_threads: max   # = os.cpu_count(),本机 20 逻辑核 → 20
cpu_threads: 8     # 也可以直接写具体数字

max 是「省心」选项,不保证最快:本机为 20 逻辑核 / 14 物理核,超过物理核心数后超线程会争抢,收益递减,还会挤占同机其它服务。建议用 benchmark_ocr.py 实测 8 / 14 / max 三档再定。

不换模型的加速方式

先尝试以下配置,不会修改模型文件:

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 控制台查看。

识别过程中会输出固定的进度检查点:

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 日志都会被静默过滤,表现为:

进度   5% 任务开始
加载 OCR 引擎: ...
(此后 10% / 20% / 50% / 80% / 100% 全部消失)

而接口其实是正常工作的(progress 字段仍会到 100),只是日志被吞了,非常容易误判为「卡住了」。

因此 logging_setup.py 把 handler 挂在 ocr_server logger 上,显式设置级别并 propagate = False,从而不受 Paddle 改动 root 的影响。tests/test_logging.py 里有对应的回归测试。

调整日志级别:

log_level: DEBUG

已知性能限制

当前环境中 PP-OCRv5 服务模型在 CPU 上关闭 oneDNN 后推理较慢。实测(20 核 CPU、官方 896x528 示例图):

默认线程(10)+ batch 1  : 约 65 秒   34 行
batch 8 + 默认线程       : 约 60 秒   34 行
batch 8 + cpu_threads 4  : 约 114 秒

按阶段拆分(log_level: INFO 的进度日志可直接读出):

20% → 50%  文字检测   约 13 秒
50% → 80%  文字识别   约 50 秒   ← 主要瓶颈

注意:同一配置在不同时间实测波动较大(同一图片分别测到 66 秒和 128 秒),比较参数时请在相同时间段多测几次,不要只看单次结果。

是否使用多核

不是单核推理。PaddleX 默认 cpu_threads = 10(可用 cpu_threads 配置项覆盖),测试机为 20 逻辑核 / 14 物理核,实测 CPU 占用:

检测阶段 CPU 约 94%~105%   (约 1 个核)
识别阶段 CPU 约 534%~686%  (约 5.3~6.9 个核)
平均约 553%,即约 5.5 个核,20 核未跑满

结论:

  • 识别阶段是多线程的,约占 5~7 个核;
  • 检测阶段接近单核,这是关闭 oneDNN 后检测耗时约 13 秒的主要原因;
  • 20 核没有跑满,说明并行效率不高,瓶颈在「未启用 oneDNN 的 CPU 算子」,而不是核心数不够。

线程数对耗时的影响(同图、batch 8):

cpu_threads=4    约 114 秒
cpu_threads=10   约  60 秒

可调整 cpu_threads 实测,建议不超过物理核心数,并用 benchmark_ocr.py 对比。

关闭 oneDNN 是必须的:enable_mkldnn=True 会触发 PaddlePaddle 3.3.1 的缺陷并直接失败:

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 开关,输出逐字节一致:

官方样例图  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.3.1 降到 3.2.2;
  2. 让 enable_mkldnn 可配置——当前 src/ocr_server/ocr.py 里是写死的 False,需要新增配置项。

本次验证在项目外的独立虚拟环境完成(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 个片段,检测模型相同):

v5rec : 登机牌|date|舱位|…|MU 2379|…|票号TKT NO.|…|起飞前1O分钟关闭GATESCLOSE1OMINUTESBEFORE DEPARTURETIME
mobrec: 登机牌|DATE|舱位|…|MU2379|…|票号TKTNO.|…|起飞前10分钟关闭 GATESCLOSE10MINUTESBEFOREDEPARTURETIME

该样本中移动端识别有两处反而更准:date 识别为 DATE、前1O分钟 识别为 前10分钟(v5 把数字 0 错认为字母 O)。主要差异只是空格分词方式。

配置写法(两个模型名可以独立指定、跨版本混用):

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),压低它对总时长几乎没有帮助。

识别耗时与文本框数量成正比

这是本项目的核心性能特征,来自实测:

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 里已预置注释行,去掉注释即可):

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 部署。

如何测速

uv run python scripts/benchmark_ocr.py

修改 config.yaml 后重新执行,比较输出的 elapsed_ms。建议至少使用 10 张代表性图片,不要只根据一张图片决定模型或参数。

Python 版本说明

本项目的 Python 版本约束是 >=3.10,<3.14,当前项目固定为 Python 3.12:

.python-version = 3.12

这次切换没有修改系统全局 Python,也没有卸载 Python 3.15。uv python pin 3.12 只修改了当前项目的 .python-version 文件;项目使用的 Python 3.12 是 uv 管理的独立解释器,位置是:

C:\Users\zimoyin\AppData\Roaming\uv\python\cpython-3.12-windows-x86_64-none\python.exe

机器上原有的 Python 3.15 仍在:

C:\Users\zimoyin\AppData\Local\Python\pythoncore-3.15-64\python.exe

项目虚拟环境位于:

D:\code\work\ocr-server\.venv\Scripts\python.exe

在 Ubuntu 上,建议使用系统 Python 3.10–3.12 或 uv 创建项目虚拟环境,不会影响系统其他 Python 项目。

Windows 安装和启动

源码启动:

cd D:\code\work\ocr-server
uv sync
powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1
# 或双击 scripts\start.bat

Windows 打包为 exe:

powershell -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1 -Clean

发布目录:

dist\ocr-server\
├── ocr-server.exe
├── config.yaml
└── models\

启动 exe:

.\dist\ocr-server\ocr-server.exe

config.yaml 和 models/ 是发布目录外置资源,可以独立修改或替换;不要直接改 exe 内部文件。发布目录约 1 GB(其中 _internal/ 约 665 MB,模型约 166 MB),这是 PaddlePaddle 原生运行库带来的正常体积。

启动前修改项目根目录的 config.yaml:

host: 0.0.0.0
port: 8000
device: cpu
ocr_workers: 1

然后启动:

uv run ocr-server

也可以:

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 架构):

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 命令替换下面示例):

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 源码启动:

cd /opt/ocr-server
uv sync --python 3.12
chmod +x scripts/start.sh
./scripts/start.sh

Ubuntu 22.04 打包为原生 ELF 二进制:

cd /opt/ocr-server
chmod +x scripts/package-ubuntu.sh
./scripts/package-ubuntu.sh

发布目录:

dist/ocr-server/
├── ocr-server
├── config.yaml
└── models/

启动:

./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 版本,然后再安装本项目依赖。

跳过检测:enable_detection

正常 OCR 由两个模型接力完成:

文本检测模型(det)→ 找出所有文本框(位置)
        ↓
文本识别模型(rec)→ 逐个识别框里的文字

enable_detection: true(默认)就是这条链路。⚠️ 检测模型不是画框/可视化,它的作用是定位文字区域;服务里没有任何绘制标注图的步骤(PaddleOCR 的 save_to_img 我们从未调用)。

把它设为 false 可以跳过检测、直接把整张图当作一行文本送识别模型:

enable_detection: false

⚠️ 只适用于图片本身就是单行文本的场景(例如你自己裁好的一行字、一个字段条)。原因是识别模型会把输入统一缩放到高约 48px:

输入 实测结果
裁出的单行(42×640) MU237903DECW035,置信度 0.9765 ✅
整张多行图(896×528) 空结果,置信度 0 ❌(被压成 48×81,文字全糊)

所以多行图片用这个模式会返回空结果,服务会打印告警:

WARNING 跳过检测后没有识别出任何文字。该模式要求图片本身是单行文本;
        如果是多行图片,请把 enable_detection 改回 true。

其他注意事项:

  • 关闭检测后 text_det_limit_side_len、text_det_thresh 等检测参数不再生效;
  • 识别结果只有一条文本片段,polygon 为空(因为没有检测框);
  • 该模式下 return_word_box 也无法给出词级框(缺检测框作为基准);
  • 进度日志仍保留全部关键点,50% 显示为「跳过框识别」,便于和前一条链路对齐。

文本框开关:return_word_box

配置:

return_word_box: false

默认 false:每个 polygon.textN 只返回该文本片段的整体 Location,速度更快、JSON 更小。

开启:

return_word_box: true

识别结果中每个文本片段会增加 words:

{
  "text1": {
    "text": "检查号:26100830064",
    "confidence": 0.99,
    "Location": {
      "xtop": 0,
      "ytop": 0,
      "xbottom": 300,
      "ybottom": 30
    },
    "line": 1,
    "paragraphs": 1,
    "words": [
      [[0, 0], [60, 0], [60, 30], [0, 30]],
      [[60, 0], [120, 0], [120, 30], [60, 30]]
    ]
  }
}

words 是按 PaddleOCR 返回的字/词级四点 polygon 数组,顺序与识别文本对应。开启后会增加识别耗时与响应体积,只有需要逐字定位时才建议打开;整体文本框 Location 无论开关都保留。

API

1. 上传图片

curl -X POST http://127.0.0.1:8000/api/v1/upload \
  -F "file=@./receipt.jpg"

返回示例(所有接口统一使用 code、message、data):

{
  "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:返回错误信息。
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"}'

未完成时返回示例:

{
  "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 对象映射:

{
  "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 里配置预设:

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 的边界语义相反,用途也不同:

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)会漏掉两处,实测:

'二〇二六'  → 只匹配到 '二'   (〇 是 U+3007,不在基本区)
'龦'        → 不匹配           (U+9FA6,Unicode 4.1 之后新增)

推荐写法(覆盖整个基本区并补上「〇」):

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 行):

第 9 行   年龄:43岁性别:女检查号:26100830064姓名:万镭
第 10 行  镜型:CF-HQ290I床号:科室:消化内科门诊门诊号:701785075
第 11 行  临床诊断:大便习惯改变;

注意这份材料里第 3 行还出现了 报告-万镭——正文同样含患者姓名。行为对比:

不限定行   -> 姓名 = 张三    (取第一次出现,可能是页眉副本或正文)
row: 9    -> 姓名 = 万镭    (精确锁定目标行)

注意事项:

  • 行号随版面变化,换模板就要重新确认行号;锁定后如果没取到值会返回空(include_empty: true 时返回空串),不会静默取错;
  • 没有行信息时(例如直接调用库函数不传 rows),row 限定的字段取不到值,不会退回全文,避免误取;
  • row 与 label_linebreak 不要同时用:跨行标签在单行文本里不存在,会取不到值。

其他开关

  • separator_optional: true:标签后不带冒号也抽。代价是误命中率明显上升,只在冒号经常被 OCR 漏识时才打开。
  • label_linebreak: true:允许标签内部跨行(姓 + 名:)。最多允许一个换行,避免把相隔很远的字拼成标签。
  • extract_include_empty: true(全局):未命中的字段返回空串而非不出现,便于调用方用固定 schema 消费。
extract_include_empty: true
# -> {"姓名": "万镭", "床号": "", "镜型": "", ...}

防止取错:机制与建议

已内置的防护:

风险 机制
值粘连到下一个字段 值在下一个已配置标签前截断;再用 pattern 限定形状
值吞掉后面的正文 end_pattern 终止符、max_length 上限、默认换行即结束
短标签嵌在长标签里(号 vs 检查号) 匹配器非重叠扫描 + 长标签优先,同时配置时不会误命中
值里出现别的标签字样(姓名不详) 标签必须紧跟分隔符才算标签,故不会截断值
低置信度噪声被抽成字段 抽取基于 min_confidence 过滤后的文本,调高该参数即可
同名标签重复出现取错 用 occurrence: last 明确取最后一个
配置冲突(标签被两个字段共用、字段名重复) 服务启动时直接报错,不会带病运行
正则写错 启动时校验并报错
不知道该值从哪来 log_level: DEBUG 会输出每个字段的命中明细与未命中列表

使用建议:

  1. 能用 pattern 就用——它是性价比最高的手段,既约束形状又防止粘连:
    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-]+ —— 这是最稳的做法。

对一张真实报告截图的实测结果:

"fields": {
  "检查号": "26100830064",
  "姓名": "万镭",
  "性别": "女",
  "年龄": "43岁",
  "门诊号": "701785075",
  "科室": "消化内科门诊",
  "镜型": "CF-HQ290I",
  "临床诊断": "大便习惯改变"
}

抽取发生在查询时(/api/v1/i2t),基于 min_confidence 过滤后的文本,因此改预设或调 min_confidence 不需要重新识别。extract_fields 留空(或删除该配置)即关闭此功能。

IDEA HTTP Client 测试

已提供:

http/ocr-server.http

在 IDEA 中打开文件,项目已附带 PaddleOCR 官方示例图片:

http/fixtures/general_ocr_002.png

然后按顺序执行:

  1. 健康检查;
  2. 上传图片;
  3. IDEA 自动保存上传响应中的 file_id;
  4. 立即调用图片转文字接口,观察 queued / processing 进度;
  5. 重复调用直到返回 completed 和 JSON 识别结果。

该测试图片来源于 PaddleOCR 官方示例。也可以把自己的图片复制到 http/fixtures/,再修改 .http 文件中的文件路径。

配置

配置统一写在项目根目录的 config.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,见下方说明
enable_detection true 是否先做文本框检测再识别;false 时跳过检测、直接识别(仅适合单行图)
return_word_box false 是否返回文本片段内部的字/词级 polygon(会增加耗时和 JSON 体积)
log_level INFO 日志级别:DEBUG、INFO、WARNING、ERROR

接口文档:启动后访问 http://127.0.0.1:8000/docs。

测试

uv run pytest -q
uv pip check
S
Description
No description provided
Readme 1 MiB
Languages
Python 76.8%
HTML 11.5%
Shell 5.2%
PowerShell 5%
Batchfile 1.5%