Files
ocr-server/README.md
T
2026-10-12 11:03:59 +08:00

18 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.py # 下载或补齐缺少的模型
└── 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

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

也可以手动提前下载或补齐模型:

uv run python scripts/download_models.py

脚本会读取 config.yaml,把模型下载到 model_dir 指定的目录。模型下载需要联网;完整分发包可以直接携带整个 models/ 目录,从而不依赖首次启动联网。下载时不会覆盖已有完整模型目录。

不同速度档位和模型选择

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

不换模型的加速方式

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

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 字段与日志中的进度一致。

调整日志级别:

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 逻辑核机器上的实测 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」,不是队列或接口阻塞。

换成移动端模型(实测约 3.4 倍提速)

同一张图片、同样 text_det_limit_side_len: 960 与 text_recognition_batch_size: 8:

模型组合 模型体积 识别耗时 识别行数
PP-OCRv5_server_det + PP-OCRv5_server_rec 约 167 MB 约 60 秒 34
PP-OCRv4_mobile_det + PP-OCRv4_mobile_rec 约 16 MB 约 18 秒 39

切换方式:

det_model_name: PP-OCRv4_mobile_det
rec_model_name: PP-OCRv4_mobile_rec

模型文件需要存在于 model_dir/official_models/ 下;不存在时首次识别会自动下载。

切换前建议先用 benchmark_ocr.py 和真实业务图片对比准确率:移动端模型体积小、速度快,但中文识别精度通常低于 PP-OCRv5 服务模型,且这两个模型属于 PP-OCRv4,不是 PP-OCRv5。不同业务对精度敏感度不同,请以实际样本为准。

其他提速方向:

  1. 降低 text_det_limit_side_len(例如 640),可减少检测耗时;
  2. 升级到 oneDNN 与 PIR 兼容的 PaddlePaddle 版本后再开启 enable_mkldnn;
  3. GPU 部署。

如何测速

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

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)过滤低置信度片段,服务会重新计算行编号和段编号。

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 10 CPU 推理线程数(Paddle cpu_math_library_num_threads)
log_level INFO 日志级别:DEBUG、INFO、WARNING、ERROR

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

测试

uv run pytest -q
uv pip check