Co-Authored-By: Claude Code <noreply@anthropic.com>
39 KiB
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。模型文件只读使用,服务不会修改模型目录中的权重文件。
服务启动后不会立即加载模型。上传接口会立即把图片放入等待队列;第一次有工作线程开始识别时:
- 优先检查
model_dir/official_models/下的检测模型和识别模型; - 模型文件完整时,直接使用项目内模型,不访问网络;
- 缺少任意模型时,只下载缺少的模型,并保存到同一个
model_dir; - 后续请求继续复用同一个进程内的 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 |
切换前建议:
- 先把当前
models/完整复制成独立备份,例如models.backup-ppocrv5/; - 将新模型下载到另一个目录,例如
models-ppocrv4-mobile/; - 只修改
config.yaml的model_dir和两个模型名称; - 用
scripts/benchmark_ocr.py和真实业务图片对比耗时、漏检率和准确率; - 验证不满意时,把
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 一致),这不影响上述结论,但仍建议以项目环境(即实际服务环境)的实测为准。
启用所需的改动
两项都要做,缺一不可:
- 把依赖从
paddlepaddle 3.3.1降到3.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 秒/框)
所以决定单张图耗时的是框数,而不是图片像素数。降低耗时的手段按有效性排序:
- 减少框数(代价是丢字,例如提高
text_det_box_thresh); - 换更快的识别模型(注意上面的丢字风险);
- 提高
cpu_threads、text_recognition_batch_size; - 让 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。
其他提速方向:
- 降低
text_det_limit_side_len(例如640),可减少检测耗时; - 升级到 oneDNN 与 PIR 兼容的 PaddlePaddle 版本后再开启
enable_mkldnn; - 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 版本,然后再安装本项目依赖。
文本框开关: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 会输出每个字段的命中明细与未命中列表 |
使用建议:
- 能用
pattern就用——它是性价比最高的手段,既约束形状又防止粘连:pattern: '[A-Za-z0-9-]{1,24}' # 编号类 pattern: '\d{1,3}\s*岁' # 带单位的数值 pattern: '[一-鿿〇·]{1,12}' # 中文姓名 - 把相邻字段都配上,边界才生效(
姓名检查号这类粘连靠标签互相切分)。 - 不要用过于宽泛的标签,例如只配一个「号」,会把「检查号」「门诊号」都当成它。
compact: true要慎用:它会删掉值里所有空格,地址类字段会被压成一串。max_length只截断不报错:需要「超长即视为未命中」时,用pattern的限定量词(如[一-鿿]{1,12})。- 上线前用自己的真实样本跑一遍,尤其注意同名标签重复、正副本这类场景。
⚠️ 边界只对「已配置」的标签生效。例如只配置了 姓名 时,姓名:万镭性别:女 中的 性别: 不是边界,值可能被吞成 万镭性别。两种解决办法:
- 把相邻字段也配置上(推荐,
性别本身通常也要抽); - 用
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
然后按顺序执行:
- 健康检查;
- 上传图片;
- IDEA 自动保存上传响应中的
file_id; - 立即调用图片转文字接口,观察
queued/processing进度; - 重复调用直到返回
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,见下方说明 |
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