Files
ocr-server/README.md
T
zimoyin 5ab4bef80e build: CPU/GPU 双环境、产物命名与打包修复
交付:
  · 产物按变体命名:CPU -> dist/ocr-server/,GPU -> dist/ocr-server-gpu/。
    变体由构建环境实际装的 paddle 自动判断,不需要人工声明
  · GPU 包额外加 --collect-binaries nvidia。漏收的后果实测是最难查的那种:
    引擎能正常加载、设备也识别成 GPU,但第一次推理才报
    cudnn64_9.dll error 126
  · --copy-metadata 的发行包名随变体变化(paddlepaddle / paddlepaddle-gpu),
    改由 scripts/paddle_env.py 动态取;写死任何一个在另一种环境下都打不出包
  · 新增 scripts/prepare_release_config.py 按变体覆盖发布配置(用 Python 改写
    以保持 UTF-8,PowerShell 的 Set-Content 会把中文注释写坏)

环境:
  · paddle 从 pyproject 依赖里移除,改用 scripts/install_paddle.py 安装。
    它没法写死:CPU/GPU 互斥,GPU 还得按显卡选 CUDA 通道(RTX 50 系必须 cu129)。
    钉死 CPU 版时,uv sync / uv run / PyCharm 自动同步都会把装好的
    paddlepaddle-gpu 静默挤掉、服务悄悄退回 CPU(实测踩过三次)
  · 新增 scripts/switch_env.py:.venv(CPU)与 .venv-gpu(GPU)两套环境共存,
    切换零成本;所有 uv run 补 --no-sync,打包改用 uv sync --inexact
  · 预置模型扩到 8 套(v4/v5 × 服务端/移动端 × 检测/识别,约 398MB)

其它:
  · scripts/start.* 先找发布包再退回源码环境;入口脚本名固定是 ocr-server
  · benchmark_ocr.py 输出 segments 与 chars,换设备/模型时可直接比对召回
  · .gitignore 覆盖 .venv-gpu/ 与 dist*/

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-14 03:53:48 +08:00

58 KiB
Raw Blame History

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-gpu/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

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

不同速度档位和模型选择

当前项目默认使用 v5 检测 + v4 移动端识别 的组合:

det_model_name: PP-OCRv5_server_det
rec_model_name: PP-OCRv4_mobile_rec

检测与识别可以独立指定,允许跨代际混用(本项目实测有效,见「推荐搭配」一节)。 scripts/download_models.py 已预置四套模型,切换时不需要联网。

档位 检测模型 识别模型 特点
低配 CPU PP-OCRv5_mobile_det PP-OCRv4_mobile_rec 检测仅约 5MB,资源紧张时用
当前默认 PP-OCRv5_server_det PP-OCRv4_mobile_rec 保召回 + 识别快 8 倍,约 96MB
有 GPU PP-OCRv5_server_det PP-OCRv5_server_rec 精度优先,配 device: gpu + use_tensorrt
速度优先(会丢字) PP-OCRv4_mobile_det PP-OCRv4_mobile_rec ⚠️ v4 移动端检测在密集图上丢字约 90%,仅适合文本稀疏的图

切换前建议:

  1. 先用 scripts/benchmark_ocr.py 和真实业务图片对比耗时、漏检率和字符数;
  2. 只修改 config.yaml 的两个模型名(模型已预置,无需改 model_dir);
  3. 验证不满意时,把模型名改回原值即可,不改动任何模型文件。

服务只读加载模型,不会修改权重。模型文件不在 git 里(.gitignore 已排除 models/), 但打包脚本会自动把 models/ 复制进发布目录。

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

det_model_name: PP-OCRv5_server_det       # 检测保持 v5,保证召回
rec_model_name: PP-OCRv4_mobile_rec       # 识别换移动端,快约 8 倍
enable_mkldnn: true                       # 依赖 paddlepaddle 3.2.x
text_recognition_batch_size: 32           # 1.png 实测 23.87s -> 19.03s,输出不变
text_det_limit_side_len: 1024             # 比 640 多召回约 28% 字符
cpu_threads: 1                            # 开 oneDNN 后几乎无影响,省核给 worker
ocr_workers: 1                            # 有并发上传时按核数加大

叠加效果(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 倍,而框数与字符数与精度优先档基本一致,召回没有损失。

在这之上再调 text_recognition_batch_size(上表是 side=512 的数据,下表统一用 当前默认的 side=1024,同一台机器、同一张 1.png):

batch 耗时 框数 字符数
8 23.87s 428 2240
16 21.62s 428 2241
32 19.03s 428 2241
64 18.32s 428 2238

框数完全一致,字符数只差 1~3 个,调到 32 就能拿到大部分收益;换成 64 只再多省 0.7 秒,已经饱和。

⚠️ 注意批次大小不是逐字节一致的:同一张 1.png,batch=8 得 2240 字符、 batch=32 得 2241 字符;官方样例图则是 253 → 250。逐条对比后确认,差异只出现在 英文分词空格(日期 DATE → 日期DATE)和个别低置信字符(高级搜索> → 高级搜索>>)上, 正文中文没有差异。切换 batch 仍建议核对一下真实图片的字符数。

同一配置下另外两张图(完整服务路径):

图片 耗时 框数 字符数
2.png (1920x1080) 7.49s(原 213.52s) 73 430
general_ocr_002.png (896x528) 8.01s(原 70.45s) 35 245

cpu_threads:开启 oneDNN 之后几乎不影响耗时

cpu_threads: max   # = os.cpu_count(),本机 20 逻辑核 → 20
cpu_threads: 1     # 当前默认

⚠️ 本节结论已更新。 早期(未启用 oneDNN 时)确实需要靠线程数提性能, 但启用 oneDNN 后识别推理本身就已是多线程,再加线程不再获益。官方样例图 (896×528) 实测:

cpu_threads=1  -> 7.25s
cpu_threads=4  -> 6.82s
cpu_threads=8  -> 7.22s
cpu_threads=14 -> 7.29s
cpu_threads=20 -> 7.25s

差异全部落在测量噪声内。所以保持 1 即可,把省下的核留给 ocr_workers(并发吞吐)或同机其它服务。

不换模型的加速方式

不用换模型、不用动模型文件,先调这几个参数(按收益排序):

text_recognition_batch_size: 32   # 首选。1.png 实测 23.87s -> 19.03s,输出不变
text_det_limit_side_len: 768      # 其次。省约 3s,字符数约 -2%
ocr_workers: 4                    # 只在有并发上传时才有效,每个 worker 约 +105MB

text_recognition_batch_size 是性价比最高的旋钮:框越多收益越大,识别框数不变, 字符数只差 1~3 个(差异仅限英文分词空格与个别低置信字符)。调到 32 就能拿到 大部分收益,再往上饱和。

text_det_limit_side_len 主要影响检测耗时,调小会漏检小字,属于拿召回换速度, 务必用真实图片对比字符数后再定。详见下方「text_det_limit_side_len 与文本密度强相关」。

日志与推理进度

服务使用普通换行日志,不使用 \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.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 个片段,检测模型相同):

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 --no-sync python scripts/benchmark_ocr.py 你的图.png 3

⚠️ --no-sync 不能省。uv run 默认会按 pyproject.toml 同步环境,而那里声明的是 CPU 版 paddlepaddle,会把装好的 paddlepaddle-gpu 静默冲掉——测出来的其实是 CPU 成绩。

修改 config.yaml 后重新执行,比较输出的 elapsed_ms、segments、chars。 建议至少使用 10 张代表性图片,不要只根据一张图片决定模型或参数;换模型或换设备时 重点看 segments 和 chars,只快不准是没用的。

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

⚠️ start.* 会优先跑 dist\ocr-server\ 里的发布包,找不到才退回源码(.venv)。 所以只要 dist\ 里有旧包,你改的源码就不会生效,而且日志里看不出区别。 实测踩过一次:改了 device 相关的源码后启动,跑的还是几天前那个包, 配上新写的 config.yaml,直接崩在 PaddleX 内部。

判断方法看启动日志的 model_dir——指向 dist\ocr-server\models 就是跑的发布包:

INFO [ocr_server] 启动 OCR 服务 ... model_dir=D:\...\dist\ocr-server\models   ← 发布包
INFO [ocr_server] 启动 OCR 服务 ... model_dir=D:\code\work\ocr-server\models  ← 源码

改完源码要立刻验证,直接跑 .venv\Scripts\ocr-server.exe(Windows)或 .venv/bin/ocr-server(Linux),绕过发布包;要跑发布包就先重新打包。

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-gpu
curl -LsSf https://astral.sh/uv/install.sh | sh
# 重新打开 shell,或按安装提示加载 ~/.local/bin
uv python install 3.12
uv sync --python 3.12
# paddle 不在依赖里,需按机器单独装一次;没有显卡就是 CPU 版
.venv/bin/python scripts/install_paddle.py
# 按需修改项目根目录 config.yaml,然后启动
uv run --no-sync 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/python scripts/install_paddle.py
.venv/bin/ocr-server

Ubuntu 源码启动:

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

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

cd /opt/ocr-server-gpu
chmod +x scripts/package-ubuntu.sh
./scripts/package-ubuntu.sh          # CPU 包 -> dist/ocr-server/
./scripts/package-ubuntu.sh --gpu    # GPU 包 -> dist/ocr-server-gpu/

发布目录(CPU 版与 GPU 版的目录名不同,一眼能分辨):

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

dist/ocr-server-gpu/                # GPU 版,另有 _internal/nvidia/ 下的 CUDA 运行库
├── ocr-server-gpu
├── config.yaml
└── models/

启动:

./dist/ocr-server/ocr-server              # CPU 版
./dist/ocr-server-gpu/ocr-server-gpu      # GPU 版
# 或:./scripts/start.sh(优先 CPU 包,再 GPU 包,最后源码)

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. 上传图片

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-OCRv4_mobile_rec
ocr_workers: 1
device: cpu
lang: ch
max_upload_mb: 10
max_image_pixels: 20000000
text_det_limit_side_len: 1024
text_det_limit_type: max
text_det_input_shape: null
text_det_thresh: 0.3
text_det_box_thresh: 0.6
text_det_unclip_ratio: 1.5
text_rec_score_thresh: 0.0
text_rec_input_shape: null
text_recognition_batch_size: 32
cpu_threads: 1
enable_mkldnn: true
mkldnn_cache_capacity: 10
use_tensorrt: false
precision: fp32
enable_cinn: false
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-OCRv4_mobile_rec 文本识别模型名称
ocr_workers 1 OCR 工作线程数;每个 worker 独立加载一份模型(约 +105MB/个)
max_upload_mb 10 单文件大小上限
max_image_pixels 20000000 图片像素上限
device cpu cpu / gpu / gpu:0 / auto / npu 等,见「CPU / GPU 切换」
lang ch PaddleOCR 语言
text_det_limit_side_len 1024 检测图像最长边;调小可加速,代价是漏检小字
text_det_limit_type max 检测缩放限制类型
text_det_input_shape null 固定检测输入尺寸(如 [3, 960, 960]);null 表示动态缩放
text_det_thresh 0.3 检测二值化阈值
text_det_box_thresh 0.6 检测框置信度阈值
text_det_unclip_ratio 1.5 检测框扩张比例
text_rec_score_thresh 0.0 识别结果阈值
text_rec_input_shape null 固定识别输入尺寸(如 [3, 48, 320]);null 表示按宽高比填充
text_recognition_batch_size 32 识别批量大小;性价比最高的旋钮,见下方说明
cpu_threads 1 CPU 推理线程数;正整数或 max。开 oneDNN 后该值几乎无影响
enable_mkldnn true 是否启用 oneDNN 加速;需要 paddlepaddle 3.2.x,见下方说明
mkldnn_cache_capacity 10 oneDNN 算子缓存容量,仅 enable_mkldnn: true 时生效
use_tensorrt false 是否启用 TensorRT;只在 device 为 GPU 时生效
precision fp32 fp32 / fp16;fp16 只在 GPU 上生效
enable_cinn false 是否启用 CINN 编译器(面向国产加速卡);普通 CPU/GPU 保持 false
log_level INFO 日志级别:DEBUG、INFO、WARNING、ERROR

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

调优参数速查(按收益排序)

参数 怎么调 实测收益
text_recognition_batch_size 8 → 32 1.png 同分辨率 23.87s → 19.03s,框数不变,字符数 2240 → 2241
text_det_limit_side_len 1024 → 768 19s → 16s,字符数从 2240 降到 2191(约 −2%)
ocr_workers 按并发量加大 推理接近单线程,并发上传时吞吐接近线性;每个 worker 约 +105MB 内存
cpu_threads 保持 1 开了 oneDNN 之后 1/4/8/14/20 差异都在噪声内
device / use_tensorrt 有 NVIDIA 卡时改 GPU 需换 paddlepaddle-gpu,见「CPU / GPU 切换」

CPU / GPU 切换

device: cpu        # 默认。固定用 CPU,永远不碰 GPU
device: gpu        # 固定用第 0 块卡
device: gpu:1      # 固定用第 1 块卡
device: auto       # 启动时探测:有可用 CUDA 设备就用 GPU,否则用 CPU

推荐用 auto:同一份 config.yaml 在「有卡的开发机」和「没卡的客户机」之间 搬来搬去不用改这一行,日志里会明确打出实际选了什么:

INFO [ocr_server.ocr] device=auto:检测到可用的 CUDA 设备,使用 GPU
INFO [ocr_server.ocr] device=auto:没有可用的 GPU(当前 PaddlePaddle 3.2.2 是纯 CPU 版本),使用 CPU

注意日志级别的区别:auto 探测不到卡是预期行为,报 INFO; 而显式写了 device: gpu 却用不了是配置问题,报 WARNING。

本机上三种取值的实际效果(有 RTX 5060,但装的是 CPU 版 paddle):

配置 实际使用 日志级别
device: auto cpu INFO
device: cpu cpu —
device: gpu cpu(回落) WARNING

⚠️ 只改 yaml 是启不了 GPU 的。 PyPI 上的 paddlepaddle 是纯 CPU 版本, 需要换成 paddlepaddle-gpu:

# 先确认本机显卡型号和驱动版本
nvidia-smi

先选对 CUDA 通道,选错装了也跑不起来(见下表)。当前项目环境实测是 paddlepaddle 3.2.2(CPU 版),is_compiled_with_cuda() 为 False。

显卡 计算能力 该选哪个通道
RTX 50 系(5060 / 5070 / 5080 / 5090) sm_120 Blackwell 必须 cu129
RTX 40 系 / 30 系 sm_89 / sm_86 cu126 或 cu129
更老的卡 ≤ sm_80 cu118 也可以

⚠️ RTX 50 系不能用 cu118 / cu126:这两个 wheel 的内核里没有 sm_120, 装上去会在第一次推理时抛 Mismatched GPU Architecture: The installed PaddlePaddle package was compiled for 60 61 70 75 80 86, but your current GPU is 120。 必须用 cu129,且 PaddlePaddle 版本要 ≥ 3.2.1。

两套环境共存,随时切换(推荐)

CPU 和 GPU 各用一套虚拟环境,都建好之后切换是零成本的,不用卸载重装:

.venv/Scripts/python.exe scripts/switch_env.py --list    # 查看两套环境的现状
.venv/Scripts/python.exe scripts/switch_env.py --cpu     # 建立/更新 .venv(CPU)
.venv/Scripts/python.exe scripts/switch_env.py --gpu     # 建立/更新 .venv-gpu(GPU)
CPU 环境 .venv      paddlepaddle==3.2.2     | CUDA 可用:False,GPU 数:0
GPU 环境 .venv-gpu  paddlepaddle-gpu==3.2.2 | CUDA 可用:True,GPU 数:1
用途 命令
跑源码(CPU) .venv\Scripts\ocr-server.exe
跑源码(GPU) .venv-gpu\Scripts\ocr-server.exe
打 CPU 包 .\scripts\package-windows.ps1
打 GPU 包 $env:UV_PROJECT_ENVIRONMENT=".venv-gpu"; .\scripts\package-windows.ps1

之所以不做成「一个环境来回切」:paddlepaddle 与 paddlepaddle-gpu 互斥(都提供 paddle 顶层包和同一批文件),而且 GPU 版还要拖进约 3.1GB 的 CUDA 运行库, 反复装卸很浪费。代价是两套环境同时存在,磁盘多占约 4GB。

只要一套环境时

装的方式是用项目自带的脚本,它会读 nvidia-smi 自动判断装哪个版本和哪个 CUDA 通道:

uv run --no-sync python scripts/install_paddle.py          # 有 N 卡就装 GPU 版,没有就装 CPU 版
uv run --no-sync python scripts/install_paddle.py --gpu    # 强制 GPU 版,通道按显卡自动推荐
uv run --no-sync python scripts/install_paddle.py --cpu    # 强制 CPU 版(顺带清掉 3GB 的 CUDA 库)
uv run --no-sync python scripts/install_paddle.py --gpu --dry-run   # 只看方案,不动环境

想手工装也行,等价命令是:

uv pip uninstall paddlepaddle paddlepaddle-gpu
uv pip install "paddlepaddle-gpu==3.2.2" \
    --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu129/

为什么 paddlepaddle 不在 pyproject.toml 的依赖里? 因为它没法写死:CPU 版和 GPU 版互斥(同一批 paddle 文件,装了会互相覆盖), GPU 版还要按显卡选 CUDA 通道。早先把它钉成 CPU 版时,uv sync、uv run、 PyCharm 的自动同步都会把装好的 paddlepaddle-gpu 静默挤掉、服务悄悄退回 CPU—— 实测踩过三次。

现在的取舍是:任何一次环境同步都会把 paddle 整个移除(连 protobuf、opt-einsum 这些依赖一起),服务启动时报错并告诉你运行 install_paddle.py。 会吵,但不会静默降级。每次跑完 uv sync 记得重新执行一次 install_paddle.py。

注意:不要用 PyPI 上的 paddlepaddle-gpu——它停在 2.6.2 且早已废弃, 装上去和本项目的 PaddleOCR 3.x / paddlepaddle 3.2.x 对不上。 只能用 PaddlePaddle 官方源,实测该源上 cu118 / cu126 / cu129 三个通道 都有 paddlepaddle_gpu-3.2.2 的 Windows 与 Linux 轮子。

⚠️ RTX 50 系要留个心眼:社区反馈 Blackwell 的预编译 wheel 支持还不够完整, 官方主要在 PaddleOCR-VL 上验证过(且只验证了 RTX 5070),经典 PP-OCR 推理管线 (也就是本项目用的这套)在部分平台仍有缺口,Windows 上尤其明显。 换完 wheel 后务必先用 benchmark_ocr.py 跑通一次真实图片再决定是否上 GPU; 跑不通就退回 CPU 包,不要卡在这里。

装完之后能自由切换吗?能

GPU 版 wheel 里同时带着完整的 CPU 内核,PaddleX 在 device 为 cpu 时会显式 config.disable_gpu(),所以三种取值随时可切、不需要重装:

配置 行为
device: cpu 强制 CPU,走 oneDNN
device: gpu / device: auto 走 GPU

实测(RTX 5060 Laptop,paddlepaddle-gpu 3.2.2 cu129):

图片 CPU GPU 加速 框数 字符数
1.png(1920×1080,428 框) 17.45s 1.44s 12× 428 → 428 2241 → 2241
general_ocr_002.png(34 框) 6.89s 0.23s 30× 34 → 34 250 → 250

框数与字符数和 CPU 完全一致——在这两张图上没有复现社区报告的 sm_120 静默丢框问题。 但上线前必须用你自己的真实图片再核一遍(尤其是扫描件 / PDF 渲染图, 社区那个 bug 正是在这类图上出现的,手机照片反而正常)。

⚠️ uv sync / uv run 会把 GPU 环境悄悄冲掉

pyproject.toml 里声明的是 CPU 版 paddlepaddle。裸跑 uv sync 或 uv run (uv run 启动前也会同步一次)的结果是卸载 paddlepaddle-gpu 和全部 nvidia-* 运行库、装回 CPU 版,而且不报错:

Would uninstall 9 packages
 - nvidia-cublas-cu12==12.9.0.13   ...(7 个 nvidia-* 运行库)
 - paddlepaddle-gpu==3.2.2
 + paddlepaddle==3.2.2

项目里的脚本都已经处理好了:

场景 处理方式
打包脚本 uv sync --dev --inexact --no-install-package paddlepaddle(实测 dry-run 为 no changes),其余 uv run 全部加了 --no-sync
启动脚本 优先直接执行 .venv 里的入口程序,不经过 uv;不得已走 uv 时用 uv run --no-sync
benchmark_ocr.py、download_models.py 命令里都要求带 --no-sync

但你自己手动敲 uv sync 或 uv run 时它照样会冲掉。 装完 GPU 后如果发现 「怎么又变回 CPU 了」,先想想是不是跑过这两个命令。判断方法看启动日志:

INFO [ocr_server.ocr] device=auto:检测到可用的 CUDA 设备,使用 GPU        ← 正常
INFO [ocr_server.ocr] device=auto:没有可用的 GPU(当前 PaddlePaddle 3.2.2 是纯 CPU 版本)…  ← 被冲掉了

(单独用 --no-install-package paddlepaddle 不够:它会把 paddlepaddle-gpu 当多余包删掉; 单独用 --inexact 也不够:它会装上 CPU 版造成两个发行包并存、文件互相覆盖。必须两个合用。)

交付包:CPU / GPU 是两个产物

光改配置在交付的 exe 包里是没用的:PyInstaller 会把打包那一刻的 paddle 打进产物, CPU 包无论客户怎么改 yaml 都用不了 GPU。所以交付时打两个包:

# CPU 包 -> dist\ocr-server\ocr-server.exe
.\scripts\package-windows.ps1

# GPU 包 -> dist\ocr-server-gpu\ocr-server-gpu.exe
# 用 switch_env.py 建好的 GPU 环境来打,它会自动识别成 GPU 变体
$env:UV_PROJECT_ENVIRONMENT=".venv-gpu"
.\scripts\package-windows.ps1
# Linux 同理
./scripts/package-ubuntu.sh              # CPU 包 -> dist/ocr-server/
./scripts/package-ubuntu.sh --gpu        # GPU 包 -> dist/ocr-server-gpu/

打包脚本会自动做这几件事,不需要手工干预:

行为 说明
自动识别变体 按构建环境实际安装的 paddle 判断,不靠人工声明
产物名区分变体 CPU → dist/ocr-server/,GPU → dist/ocr-server-gpu/,两个包不会互相覆盖
预置 device GPU 包的 config.yaml 里 device 写成 auto:客户机有卡就用卡、没卡自动回落 CPU,两种机器都能直接跑
--copy-metadata 用对发行包名 CPU 版叫 paddlepaddle、GPU 版叫 paddlepaddle-gpu,写死任何一个在另一种环境下都会打包失败
环境不匹配直接报错 加 -Gpu / --gpu 断言时,如果构建环境装的是 CPU 版,脚本会带着安装命令报错退出

-Gpu / --gpu 只是断言,不是开关:不加该参数时脚本也按实际安装的版本判断。

⚠️ 不要指望 GPU 包能当 CPU 包用。 运行时的兜底(device: auto / device: gpu) 只能兜住「能 import paddle、但拿不到 CUDA 设备」这一种情况。如果客户机上 根本没有 NVIDIA 的 CUDA 运行库,paddlepaddle-gpu 可能在 import 阶段就报错 (典型是缺 libcublasLt.so.12 这类),那时候我们的兜底代码还没机会执行。 PaddlePaddle 官方安装指南的口径也是「没有 NVIDIA GPU 就装 CPU 版」。 所以:确定没卡的客户机,发 CPU 包;不确定的,两个包都带上。

变体没有「强制」开关:产物里打进的就是构建环境当前的 paddle,改个名字不会改变这一点, 只会让包名和内容对不上。要打 CPU 包就换回 CPU 版 paddle 再打。

GPU 包必须额外收 nvidia 运行库(打包脚本已处理)

paddlepaddle-gpu 的 CUDA 运行库(cudnn / cublas / cufft 等)不在 paddle 包里, 而是装在独立的 nvidia-* 发行包里。PyInstaller 的 --collect-all paddle 收不到它们, 所以 GPU 包额外加了 --collect-binaries nvidia。

漏收的后果实测是最难排查的那种:引擎能正常加载、设备也正确识别成 GPU, 但第一次推理才报错:

PreconditionNotMetError: The third-party dynamic library (cudnn64_9.dll)
that Paddle depends on is not configured correctly. (error code is 126)

收进来的落点是 _internal/nvidia/<包>/bin/,正好是 paddle 在 __init__.py 里用 os.add_dll_directory(os.path.dirname(paddle.__file__) + "/../nvidia/<包>/bin") 寻找的路径。

体积(实测):CPU 包约 1.0GB;GPU 包约 5.0GB,其中 3.1GB 是 CUDA 运行库 (cudnn 1.06GB、cublas 736MB、cusparse 456MB、cusolver 442MB、cufft 275MB…), 源目录本身就那么大,不是重复打包。要瘦身只能砍裁用不到的库,有运行时踩坑风险。

开启 GPU 后还可以叠加:

device: gpu
use_tensorrt: true     # TensorRT 加速,首次推理会花时间构建引擎
precision: fp16        # 半精度,更快、显存更省,但需核对字符数

兜底行为:如果配了 device: gpu(或 auto)但 GPU 实际不可用, 启动时会打印中文日志并自动回落 CPU,不会让服务起不来。 检查覆盖两种情况,不只是「装没装 GPU 版」:

  • 装的是纯 CPU 版 paddle → 直接回落;
  • 装的是 GPU 版但机器上没有可用的 N 卡或驱动 → 也会回落 (这一点单查 is_compiled_with_cuda() 是查不出来的,那是编译期属性, 装了 GPU 版就返回 True,所以还要实际探一次可见设备数)。

上线前请确认启动日志里「加载 OCR 引擎」那一行打印的 device= 是你期望的值:

WARNING [ocr_server.ocr] 配置 device=gpu,但 GPU 无法启用:当前 PaddlePaddle 3.2.2 是纯 CPU 版本。…
WARNING [ocr_server.ocr] use_tensorrt 已开启,但生效设备是 cpu;TensorRT 只在 GPU 上生效,本次忽略该项。
INFO  [ocr_server.ocr] 加载 OCR 引擎: det=… rec=… device=cpu cpu_threads=1 …

同理,use_tensorrt: true 但设备是 CPU 时会打印警告并忽略该项 (TensorRT 只在 GPU 分支生效)。

为什么不能照搬 ONNX Runtime 的调优文章

网上关于「PP-OCR 部署优化」的资料大多讲的是 ONNX Runtime / TensorRT 路线 (intra_op_num_threads、providers、trt_max_workspace_size、INT8 量化等)。 本项目走的是 Paddle Inference(paddleocr → paddlex → paddlepaddle), 模型格式和执行引擎都不一样,那些参数名在这里并不存在。对应关系:

常见文章里的说法 本项目实际参数
intra_op_num_threads cpu_threads
inter_op_num_threads 无对应(Paddle 只有单一线程数)
graph_optimization_level 无对应(Paddle 默认开启,set_optimization_level(3))
batch_size text_recognition_batch_size
dynamic_shapes text_det_limit_side_len、text_det_input_shape、text_rec_input_shape
TensorRT + trt_fp16_enable use_tensorrt: true + precision: fp16
gpu_mem_limit 无对应(Paddle 用 FLAGS_* 环境变量控制)
INT8 量化、ONNX 导出 不适用(Paddle 需另建校准集走 run_mode: trt_int8)

简单说:照抄那些文章的代码在本项目里会直接报「不认识的参数」,请以上表为准。

模型预置

scripts/download_models.py 会把交付包需要的八套模型一次性下载到 model_dir/official_models/,共约 398MB:

uv run python scripts/download_models.py
# 打包时 scripts/package-windows.ps1 / package-ubuntu.sh 会自动复制 models/ 进发布目录

检测

模型 体积 用途
PP-OCRv5_server_det 85MB 召回最好,密集小字靠它,默认用它
PP-OCRv5_mobile_det 5MB 资源紧张时用(比 v4 移动端检测强得多)
PP-OCRv4_server_det 109MB v4 代际服务端,对比备选
PP-OCRv4_mobile_det 5MB ⚠️ 密集文本大面积漏检(1.png 只检出 46 框),别用在表格/文档图上

识别

模型 体积 用途
PP-OCRv5_server_rec 82MB 精度最高,也最慢。GPU 机器上可用它冲精度
PP-OCRv5_mobile_rec 17MB v5 代际移动端,速度与精度折中
PP-OCRv4_server_rec 87MB v4 代际服务端,对比备选
PP-OCRv4_mobile_rec 11MB 默认。密集文本字符数与 v5 服务端基本一致,快约 8 倍

八套都在本地之后,交付后断网也能直接改 det_model_name / rec_model_name 切换。 脚本会跳过已完整的目录,重复执行不会重新下载;上次下载中断留下的空壳目录(只含 .cache)会被自动清理。

体积提示:这八套会随发布包一起发给客户(约 398MB)。如果确定用不上某个代际, 可以从 src/ocr_server/ocr.py 的 STAGED_DET_MODELS / STAGED_REC_MODELS 里删掉再重新下载,打包时 models/ 目录里没有的自然不会被带上。

测试

uv run pytest -q
uv pip check