PP-OCR ONNX/MNN Deployment Scaffold

该工程骨架用于搭建 PP-OCR 系列模型的 C++ 推理部署链路，支持 ONNX Runtime 与 MNN 两种后端。

.
├── SKILL.md
├── docs/PP-OCR_ONNX_MNN_Deployment_Design.md
├── configs/ppocr_v5_mobile.yaml
├── scripts/download_ppocr_models.sh
├── scripts/export_paddle_to_onnx.sh
├── scripts/convert_onnx_to_mnn.sh
├── tools/verify_onnx.py
├── tools/compare_ocr_json.py
└── cpp/

快速流程

# 1. 下载 PaddleOCR inference 模型，版本通过参数传入
bash scripts/download_ppocr_models.sh --version v5
# 可选：bash scripts/download_ppocr_models.sh --version v4 --lang ch
# 可选：bash scripts/download_ppocr_models.sh --version v3 --skip-cls

# 2. 转 ONNX
bash scripts/export_paddle_to_onnx.sh

# 3. 转 MNN
MNN_CONVERT=/path/to/MNNConvert bash scripts/convert_onnx_to_mnn.sh

# 4. 验证 ONNX 模型输出 shape
python tools/verify_onnx.py --config configs/ppocr_v5_mobile.yaml --image examples/test.jpg

# 可选：运行 det+rec OCR 并保存识别结果可视化
bash scripts/verify_onnx_ocr.sh --image examples/test.jpg

# 5. 编译 C++ Demo
cd cpp
cmake -S . -B build-ONNX -DUSE_ONNX=ON
cmake --build build-ONNX -j

# 6. C++ 推理并将 OCR 识别文本可视化到图像
./build-ONNX/ppocr_demo \
  --config ../configs/ppocr_v5_mobile.yaml \
  --image ../examples/test.jpg \
  --json-output ../output/cpp_ocr_result.json \
  --vis-output ../output/cpp_ocr_text_vis.jpg \
  --font-path /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc \
  > ../output/cpp_ocr_stdout.json

模型下载脚本

scripts/download_ppocr_models.sh 会把 PaddleOCR inference 模型下载并解压到：

models/paddle/det
models/paddle/cls
models/paddle/rec

常用命令：

# 默认下载 PP-OCRv5 mobile det/rec + 通用 cls
bash scripts/download_ppocr_models.sh --version v5

# 下载 PP-OCRv4 中文模型
bash scripts/download_ppocr_models.sh --version v4 --lang ch

# 下载 PP-OCRv3 英文模型，不下载方向分类模型
bash scripts/download_ppocr_models.sh --version v3 --lang en --skip-cls

# 官方 URL 变化或需要自定义模型时，可显式传入 URL
bash scripts/download_ppocr_models.sh \
  --version v5 \
  --det-url https://example.com/det_infer.tar \
  --rec-url https://example.com/rec_infer.tar \
  --cls-url https://example.com/cls_infer.tar

如目录已存在，脚本默认跳过；需要重新下载可追加 --force。

下载脚本会尝试从 models/paddle/rec/inference.yml 中的 PostProcess.character_dict 自动导出识别字典到：

models/dict/ppocr_keys_v1.txt

如果你已有模型但缺少字典，也可以手动生成：

python tools/verify_onnx.py --config configs/ppocr_v5_mobile.yaml --dump-dict

Paddle 模型转 ONNX

OCR 推理链路默认包含三类模型：

cls / det / rec

导出脚本默认要求三者都存在：

bash scripts/export_paddle_to_onnx.sh

如果提示 paddle2onnx: command not found，请先安装：

python -m pip install paddle2onnx

脚本会优先调用命令行 paddle2onnx，如果命令不存在但 Python 模块可用，则自动回退到：

python -m paddle2onnx

默认输入/输出目录：

PADDLE_ROOT=models/paddle ONNX_ROOT=models/onnx bash scripts/export_paddle_to_onnx.sh

如果确实只想转换已存在的部分模型，可临时允许跳过缺失模型：

REQUIRE_ALL=0 bash scripts/export_paddle_to_onnx.sh

ONNX OCR 结果可视化

tools/verify_onnx.py 除了验证模型输入输出 shape，还支持运行 ONNX Runtime OCR 链路并绘制结果：

推荐使用封装脚本：

bash scripts/verify_onnx_ocr.sh \
  --config configs/ppocr_v5_mobile.yaml \
  --image examples/test.jpg \
  --vis-output output/ocr_vis.jpg \
  --json-output output/ocr_result.json

等价 Python 命令：

python tools/verify_onnx.py \
  --config configs/ppocr_v5_mobile.yaml \
  --image examples/test.jpg \
  --ocr \
  --vis-output output/ocr_vis.jpg \
  --json-output output/ocr_result.json

输出：

output/ocr_vis.jpg：在原图上绘制检测框、识别文本和识别分数。
output/ocr_result.json：保存 image_id、ocr_results[].box/text/det_score/rec_score/angle。

注意：该可视化功能依赖 onnxruntime、opencv-python、PyYAML，并要求配置中的 models.det、models.rec、models.rec_dict 路径有效。如果 models.rec_dict 不存在，脚本会自动尝试从 models.rec_inference_yml（默认 models/paddle/rec/inference.yml）读取字典。

中文可视化文本使用 Pillow + 中文字体绘制，避免 cv2.putText 中文乱码。脚本会自动尝试常见字体路径，例如：

/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc
/usr/share/fonts/truetype/droid/DroidSansFallbackFull.ttf

如果你的系统字体位置不同，可显式指定：

python tools/verify_onnx.py \
  --config configs/ppocr_v5_mobile.yaml \
  --image examples/test.jpg \
  --ocr \
  --vis-output output/ocr_vis.jpg \
  --font-path /path/to/chinese_font.ttf

C++ 推理结果可视化

C++ demo 支持通过 --vis-output 直接把 OCR 识别文本可视化到图像中。实现方式是：C++ 完成推理、生成 JSON，并使用 OpenCV freetype 模块加载中文/CJK 字体绘制检测框、识别文本和识别分数，不再依赖 Python 可视化脚本。

ONNX Runtime 后端可使用 USE_ONNX=ON 创建独立编译目录。USE_ONNX 是 USE_ONNXRUNTIME 的兼容别名；如果未传 ORT_ROOT，CMake 会默认尝试 /home/panguofeng/tools/onnxruntime/onnxruntime-linux-x64-1.16.3：

cd cpp
cmake -S . -B build-ONNX -DUSE_ONNX=ON
cmake --build build-ONNX -j
cd ..
./cpp/build-ONNX/ppocr_demo \
  --config configs/ppocr_v5_mobile.yaml \
  --image examples/test.jpg \
  --json-output output/cpp_onnx_ocr_result.json \
  --vis-output output/cpp_onnx_ocr_text_vis.jpg \
  --font-size 20

cd cpp
./build/ppocr_demo \
  --config ../configs/ppocr_v5_mobile.yaml \
  --image ../examples/test.jpg \
  --json-output ../output/cpp_ocr_result.json \
  --vis-output ../output/cpp_ocr_text_vis.jpg \
  --font-path /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc \
  --font-size 20 \
  > ../output/cpp_ocr_stdout.json

输出：

output/cpp_ocr_result.json：C++ OCR JSON 结果。
output/cpp_ocr_stdout.json：stdout 中同步打印的 OCR JSON。
output/cpp_ocr_text_vis.jpg：绘制了检测框、中文识别文本和识别分数的可视化图片。

如果未传入可用 --font-path，C++ 会自动尝试常见中文/CJK 字体路径；仍未找到时，会回退为只绘制检测框、序号和分数的 ASCII 可视化。

也可以使用封装脚本：

bash scripts/run_cpp_ocr_vis.sh \
  --config configs/ppocr_v5_mobile.yaml \
  --image examples/test.jpg \
  --json-output output/cpp_ocr_result.json \
  --vis-output output/cpp_ocr_text_vis.jpg \
  --font-path /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc

如需对已有 JSON 做二次可视化，可继续使用 tools/visualize_ocr_json.py 作为独立辅助工具；C++ demo 自身已不再调用该脚本。

C++ MNN 推理

项目支持通过 MNN 后端运行 C++ OCR 推理。请先将 ONNX 模型转换为 MNN：

MNN_CONVERT=/path/to/MNNConvert bash scripts/convert_onnx_to_mnn.sh

编译时启用 USE_MNN。项目默认使用内置第三方库目录 cpp/third_party/MNN（包含 include/MNN/*.hpp 和 lib/libMNN.so）；如需使用其他 MNN SDK，可显式传入 -DMNN_ROOT=/path/to/MNN。CMake 会在 ${MNN_ROOT}/lib、${MNN_ROOT}/build、${MNN_ROOT}/build/lib 下查找 libMNN.so：

cd cpp
cmake -S . -B build-mnn -DUSE_MNN=ON
cmake --build build-mnn -j

使用 MNN 配置运行：

cd ..
./cpp/build-mnn/ppocr_demo   --config configs/ppocr_v5_mobile_mnn.yaml   --image examples/test.jpg   --json-output output/cpp_mnn_ocr_result.json   --vis-output output/cpp_mnn_ocr_text_vis.jpg   --font-size 20

说明：configs/ppocr_v5_mobile_mnn.yaml 默认将 det.output_name / rec.output_name 留空，pipeline 会直接使用后端返回的第一个输出；如果你知道转换后的 MNN 输出 tensor 名称，也可以显式填写。若填写的输出名不存在，程序会打印 warning 并回退到第一个输出。

如果运行时提示 MNN model file not found: models/mnn/det.mnn 或 models/mnn/rec.mnn，请先确认 det/rec ONNX 已成功导出并转换为 MNN。某些旧版 Paddle .pdmodel 可能需要匹配版本的 paddle2onnx，或重新下载/导出带 inference.json 的 PaddleOCR inference 模型。

说明

cpp 部分是部署框架骨架，重点展示 PP-OCR 模块划分、后端抽象、DB 后处理与 CTC 解码接口。
真正集成时需要根据你下载的模型输入输出名、shape、字典文件，调整 configs/ppocr_v5_mobile.yaml。
MNN 端建议先用 ONNX Runtime 对齐数值，再做 MNN 结果对齐，避免同时排查转换和后处理问题。

Navigation Menu

Repository files navigation

PP-OCR ONNX/MNN Deployment Scaffold

目录

快速流程

模型下载脚本

Paddle 模型转 ONNX

ONNX OCR 结果可视化

C++ 推理结果可视化

C++ MNN 推理

说明

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
configs		configs
cpp		cpp
docs		docs
examples		examples
models		models
scripts		scripts
tools		tools
.clinerules		.clinerules
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

PP-OCR ONNX/MNN Deployment Scaffold

目录

快速流程

模型下载脚本

Paddle 模型转 ONNX

ONNX OCR 结果可视化

C++ 推理结果可视化

C++ MNN 推理

说明

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages