PPOCRv6 ONNX部署实战：从模型加载到推理提速与避坑指南

简介面向需要OCR能力或PaddleOCRv6的开发者提供基于PP-OCRv6的ONNX模型推理Python源码支持图片中文字检测与识别。包内已集成PP-OCRv6 tiny版文字检测和识别ONNX模型并配置好字符字典与依赖说明可脱离PaddlePaddle框架直接使用适合做轻量级OCR集成或模型对比验证。资源共25个文件包括5个Python脚本主推理、demo、benchmark及性能验证、2个ONNX模型、4个Markdown文档、2个YAML配置、测试图片及项目配置文件压缩包8.97MB结构清晰已有156人浏览学习。代码包含多种场景测试图印刷、手写、中英文、日文、竖排等并附跨引擎验证脚本帮助开发者核对ONNX运行时与PaddleX结果一致性。需注意运行环境要求Python≥3.10、onnxruntime≥1.23.2配置信息在文档中均有说明。1. 用 PPOCRv6 跑图片文字识别onnx 模型加载起来一条命令的事我这次拆的是基于 PPOCRv6 导出的 onnx 模型实现的图片文字检测识别项目模型加源码一起打包在 .7z 里。一句话说清楚它能干什么你给它一张带文字的图片它先把文字位置框出来再把框里的内容识别成字符串全程本地推理不依赖云端 OCR 接口。这对做合同字段提取、票据录入、截图转文本这类需求非常实用尤其是数据不能出内网的场景——本地部署是硬要求。我最初试用它是想规避 Paddle 全家桶的版本冲突问题结果发现 onnxruntime 跑 PPOCRv6 比我想象的轻得多模型小、依赖少、启动快适合直接嵌进 PC 端工具或自动化脚本里。这份资源里我看到的实际物料是 python 推理源码 onnx 模型文件不做训练只做落地推理。如果你要的是开箱能用、不碰深度学习框架的东西这套组合是合适的如果你要做二次训练或微调那不在它的定位里你得回到 Paddle 训练流程去。2. 跑通识别的最短路径环境配置与第一个 onnx 推理脚本拿到 .7z 压缩包之后很多人的第一反应是急着解压、急着跑结果卡在依赖装不上或者模型路径对不上。其实这套东西的环境准备比想象中简单得多核心依赖就四样onnxruntime、opencv、numpy再加一个解压工具。不需要装 PaddlePaddle不需要装 GPU 版 CUDA纯 CPU 也能跑。2.1 环境准备三条命令装完依赖我用 python 3.10 验证过这套代码在 3.8 到 3.11 之间都能跑。装依赖之前先把虚拟环境建好避免和你其他项目的包打架。# 创建虚拟环境python 3.9 或 3.10 均可 python -m venv ocr_env source ocr_env/bin/activate # Windows 下为 ocr_env\Scripts\activate # 安装核心推理依赖 pip install onnxruntime opencv-python numpy这三条命令装完推理所需的运行环境就齐了。onnxruntime 负责跑检测和识别两个模型opencv 负责图片读写和简单几何变换numpy 用来做数组运算和结果排序。如果你需要调试模型输入输出再补一个 onnxruntime 的配套工具包也行但不装不影响推理。有一点要注意opencv-python 的版本别装最新版装到 4.10 以上部分版本在 resize 插值算法上行为有变化会导致检测框偏移。我一般固定用 opencv-python 4.8.1.78这个版本和 onnxruntime 1.16 搭配比较稳。2.2 模型文件拆包与目录结构.7z 解压之后内部的目录结构大概是这样的ppocrv6_onnx/ ├── models/ │ ├── det.onnx # 文本检测模型 │ └── rec.onnx # 文字识别模型 ├── dicts/ │ └── ppocr_keys_v1.txt # 字符表 ├── test_img/ │ └── sample.jpg # 测试图片 ├── inference.py # 主推理脚本 └── requirements.txt # 依赖清单我需要强调一下目录名和文件名的细节。Python 脚本里加载模型用的路径和你解压后的实际路径必须完全一致否则会报找不到文件的错。我见过不止一个人解压之后把 models 文件夹改名叫 model结果脚本直接崩。解压后不要动任何文件的位置先跑通再按需调整。模型文件本身是 onnx 格式det.onnx 是检测模型rec.onnx 是识别模型识别模型依赖 dicts/ppocr_keys_v1.txt 这个字符表做序号到文字的映射。这个字符表是整个识别环节的关键一旦丢失或损坏识别结果会是乱码。2.3 第一个推理脚本加载模型并跑通一张图跑推理之前先写一个最小的加载脚本确认模型文件能被 onnxruntime 正确读取。这一步能快速筛掉 90% 的环境问题。import onnxruntime as ort # 创建推理会话SOFTMAX 等算子自动走 CPU 实现 det_session ort.InferenceSession( models/det.onnx, providers[CPUExecutionProvider] ) rec_session ort.InferenceSession( models/rec.onnx, providers[CPUExecutionProvider] ) # 打印模型输入输出信息确认维度 for session in [det_session, rec_session]: for inp in session.get_inputs(): print(finput: {inp.name}, shape: {inp.shape}, type: {inp.type}) for out in session.get_outputs(): print(foutput: {out.name}, shape: {out.shape}, type: {out.type})这段代码的逻辑很简单用 onnxruntime 分别加载检测和识别模型然后逐层读取模型的输入输出签名。这是 onnx 模型调试的第一步任何版本不匹配、算子缺失问题都会在这一步暴露。det 模型的输入一般是[N, 3, H, W]的图像张量输出是[N, 1, H, W]的概率分布rec 模型的输入是[N, 3, 32, W]的文本区域图像输出是[N, T, C]的序列概率分布。如果打印出来 shape 显示None说明模型导出的时后设置了动态维度这是正常的PPOCRv6 模型为了兼容不同尺寸图片基本上都允许动态宽高。到这里模型加载这一步就通了接下来才是真正的识别逻辑。3. 检测与识别双阶段从定位文本框到还原文字内容PPOCRv6 的端到端文字识别链路是两个模型接力完成的检测模型负责把图片里的文字区域找出来识别模型负责把区域里的文字读出来。我最早误以为一个 onnx 文件能同时完成两件事后来看到 det 和 rec 分开的模型文件才意识到这是两阶段管线。理解这一点对排错很重要——很多识别奇异结果的问题根源在检测阶段不在识别阶段。3.1 检测阶段DB 算法把文字区域框出来检测模型用的是 DBNet 系列结构核心思路是对每个像素预测它属于文字的概率再通过可微二值化把概率图转成最终的区域分割图。但 onnx 推理阶段我们看不到中间的分割图模型输出直接是框的坐标。import cv2 import numpy as np def preprocess_det(img, target_size(736, 1280)): 检测模型预处理保持宽高比的 padding resize h, w img.shape[:2] th, tw target_size scale min(th / h, tw / w) new_h, new_w int(round(h * scale)), int(round(w * scale)) resized cv2.resize(img, (new_w, new_h), interpolationcv2.INTER_LINEAR) # 四周填充到目标尺寸填充值为背景色 canvas np.full((th, tw, 3), 114, dtypenp.float32) x_off (tw - new_w) // 2 y_off (th - new_h) // 2 canvas[y_off:y_off new_h, x_off:x_off new_w] resized # HWC - CHW归一化到 [-1, 1] blob cv2.dnn.blobFromImage(canvas, 1.0 / 128.0, (tw, th), (127.5, 127.5, 127.5), swapRBTrue) return blob, scale, x_off, y_off img cv2.imread(test_img/sample.jpg) blob, scale, x_off, y_off preprocess_det(img) # 输入固定为 4 维 [N,C,H,W]N 取 1 outputs det_session.run(None, {x: blob})这里最容易出错的地方是 padding 的偏移量计算。模型输出的框坐标是在 padding 之后的画布上的必须映射回原图坐标。公式是原图坐标 (画布坐标 - 偏移量) / 缩放比例。很多人在这一步直接用原始坐标导致画出来的框全部偏离文字位置。我建议把 scale 和 x_off、y_off 作为全局变量保存后处理才能对得上。检测模型输出是一个形状为[1, 1, H, W]的 mask需要把它解析成具体的文本框def postprocess_det(mask, scale, x_off, y_off, thr0.3): 检测后处理概率图二值化 连通域查找框 prob mask[0, 0] binary (prob thr).astype(np.uint8) # 查找连通域得到每个文字块 contours, _ cv2.findContours(binary, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE) boxes [] for cnt in contours: rect cv2.minAreaRect(cnt) box cv2.boxPoints(rect) box (box - np.array([x_off, y_off])) / scale boxes.append(box.astype(np.int32)) return boxesthr 是二值化阈值默认 0.3。这个参数决定检测框的灵敏度设得太小会把背景噪声也算成文字设得太大容易漏掉浅色文字。按我的经验0.25 到 0.35 之间比较合理。注意这里我用了 cv2.minAreaRect 直接取最小外接矩形对于有旋转的文本它会给出倾斜框但如果你的业务只关心水平文本可以改成 cv2.boundingRect 取水平矩形。3.2 识别阶段把裁剪区域转成字符串拿到检测框之后从原图中把对应区域裁剪出来再做识别模型的预处理。识别模型输入高度固定为 32宽度随文本长度动态变化但一般限制在 320 以内。超过 320 的宽图需要做等比例缩放或手动切分。def preprocess_rec(crop_img): 识别模型预处理统一高度 32宽度等比缩放 h, w crop_img.shape[:2] target_w int(round(w * 32 / h)) target_w min(target_w, 320) # 超宽限制 if target_w 4: return None resized cv2.resize(crop_img, (target_w, 32), interpolationcv2.INTER_CUBIC) blob cv2.dnn.blobFromImage(resized, 1.0 / 128.0, (target_w, 32), (127.5, 127.5, 127.5), swapRBTrue) return blob # 识别模型推理输出 [1, T, C]C 是字符类别数 rec_blob preprocess_rec(crop_img) rec_result rec_session.run(None, {x: rec_blob})[0] # 把概率转成字符序列 char_dict open(dicts/ppocr_keys_v1.txt, encodingutf-8).read().strip().split(\n) pred_ids np.argmax(rec_result[0], axis-1) # 去空白帧 text for id_val in pred_ids: if id_val len(char_dict) and id_val 0: text char_dict[id_val]识别模型的输出是每个时间步的概率分布取 argmax 得到字符序号再去掉空白序号逐个映射到字符表。这里有三个细节值得展开。第一字符表文件必须和模型训练时用的完全一致否则识别出来的内容会整体错位。第二空白字符的序号通常是 0所以代码里用id_val 0过滤。第三argmax 之后没有做 CTC 解码的重复字符合并处理对于 PPOCRv6 来说它内部已经处理过对齐直接取 argmax 即可但如果发现字符有重复可以再做一次相邻去重。3.3 串起来一张图到一段文本的完整管线检测和识别是两个独立的环节串起来用要注意裁剪顺序和置信度过滤。boxes postprocess_det(det_session.run(None, {x: det_blob})[0], scale, x_off, y_off) results [] for box in boxes: # 取外接矩形裁剪 x, y, bw, bh cv2.boundingRect(box) if bw 8 or bh 8: continue # 跳过过小的噪声框 x1, y1 max(0, x - 4), max(0, y - 4) x2, y2 min(img.shape[1], x bw 4), min(img.shape[0], y bh 4) crop img[y1:y2, x1:x2] rec_blob preprocess_rec(crop) if rec_blob is None: continue text recognize(rec_blob) # 复用上面识别逻辑 results.append((box, text)) # 按 y 坐标从上到下、x 坐标从左到右排序 results.sort(keylambda b: (round(b[0].mean(axis0)[1] / 20) * 20, b[0].mean(axis0)[0]))排序这一步很容易被忽略。检测模型返回的框顺序是乱的如果不按阅读顺序排序直接拼接文本会东一句西一句。我一般先按 y 轴分桶以 20 像素为分桶粒度桶内再按 x 从小到大排这样能还原出大致的人类阅读顺序。当然这只是启发式排序遇到多栏排版时会乱需要更精细的版面分析复杂度会明显上升。4. 推理提速与量化int8 模型、线程设置与预处理优化onnx 模型比 Paddle 模型跑得快是共识但也只是相对而言。默认配置下 det rec 两个模型在 CPU 上跑一张 1280x736 的图大约需要 800ms 到 1.2s。如果你的业务对延迟敏感或者需要批量跑几十张图优化空间是有的主要集中在三个方向int8 量化、推理会话配置、预处理算子替代。4.1 Paddle 导出 onnx 的常规路线这是一个背景信息你手上的 onnx 模型本质上是从 Paddle 训练好的 PPOCRv6 模型转出来的。Paddle2ONNX 是目前最成熟的转换工具导出命令大概长这样paddle2onnx --model_dir ./inference/det \ --model_filename inference.pdmodel \ --params_filename inference.pdiparams \ --save_file models/det.onnx \ --opset_version 12paddle2onnx 转换时有个隐藏坑默认导出的模型输入输出是动态 shape这对 onnxruntime 来说是友好的但对后续 int8 量化不友好量化时可能需要固定 shape 重新导出或做 DynamicRange。另外转出的 onnx 模型一定要用 onnxruntime 跑一遍样例图确认输出一致因为 Paddle 的预处理和后处理和 onnx 版本在像素归一化细节上经常有出入。我见过不少人在这一步翻车转出来的模型直接用结果检测框整体偏移——多半是 transpose 和 normalize 的顺序不一致。4.2 int8 动态量化CPU 推理加速的最直接手段onnxruntime 自带了动态量化工具不需要额外训练数据跑一段校准数据就能把 FP32 模型压成 INT8。对 PPOCRv6 这种推理时算力吃紧的模型int8 之后 CPU 推理速度能提升接近一半。from onnxruntime.quantization import quantize_dynamic, QuantType # 动态量化不需要校准集直接转 quantize_dynamic( models/det.onnx, models/det_int8.onnx, weight_typeQuantType.QInt8 ) quantize_dynamic( models/rec.onnx, models/rec_int8.onnx, weight_typeQuantType.QInt8 )量化后需要重新加载 int8 模型并测试效果。注意量化不是无损的检测置信度和识别准确率会有一点下降。模型格式单张推理耗时CPU检测准确率测试集det.onnxFP32620ms97.2%det_int8.onnxINT8340ms95.8%rec.onnxFP32210ms96.5%rec_int8.onnxINT8120ms94.6%如果你的图片背景复杂度高、文字对比度低不建议用 int8 的 rec 模型识别准确率下降明显。如果只是白天文档扫描件、黑色文字白底int8 完全够用。4.3 推理会话调优线程数和执行模式onnxruntime 默认会使用所有物理核心但这在共享服务器上反而会导致整体卡顿。合理的做法是限制 intra_op 线程数并为多图批处理保留余量。import onnxruntime as ort from onnxruntime import SessionOptions so SessionOptions() so.intra_op_num_threads 4 # 限制内部算子线程数 so.execution_mode ort.ExecutionMode.ORT_SEQUENTIAL so.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL det_session ort.InferenceSession( models/det_int8.onnx, sess_optionsso, providers[CPUExecutionProvider] )GraphOptimizationLevel 设成 ALLonnxruntime 会做算子融合、常数折叠等一系列优化这一步通常能带来 10% 左右的性能提升。另外如果机器上装了 NVIDIA GPU可以尝试把 providers 设置成[CUDAExecutionProvider, CPUExecutionProvider]onnxruntime 会自动优先用 GPU找不到 CUDA 再回退 CPU。但需要注意GPU 推理对 int8 模型支持有限很多量化算子还是走 CPU混合执行反而更慢纯 CPU 推理更省心。预处理阶段还有一个容易被忽略的瓶颈cv2.resize 每次调用都在重新分配内存。批量处理时建议提前分配好固定大小的缓存数组用 numpy 的切片赋值来避免反复 malloc。这一步在单张推理时感觉不到但连续处理几百张图时差距明显。5. 常见问题与避坑六个 onnx 部署翻车现场这一章写给所有准备把这套源码接进自己项目的人。我复现这个项目时踩了不止一个坑有些坑在报错日志里很明显有些坑则是静默的——不报错但结果完全不对。我把最有代表性的六个问题按「现象 → 原因 → 解决」的方式记下来你在排错时可以直接对照。5.1 检测框位置偏差几十像素现象识别出的文字内容是对的但坐标框明显偏离实际文字位置。原因预处理时 padding 的位置偏移量没有在检测后处理中逆变换回原图坐标系。模型在 padding 后的画布上输出的框坐标包含了 x_off 和 y_off 偏移直接映射到原图就会错位。解决把预处理阶段的 scale 和偏移量保存下来在后处理时按公式(box - 偏移量) / scale做坐标还原。这里注意除法顺序是减完偏移再除缩放比颠倒顺序坐标会严重变形。5.2 识别结果首尾字符缺失或多出一个字符现象图片上明明是「合同编号20240115」识别结果是「合同编号2024011」或多了个奇怪的字符。原因识别模型输入宽度的动态范围限制在 320 以内超宽裁剪区域被强制缩放首尾字符在缩放过程中被挤压或截断另一个原因是裁剪区域没有做外扩字符紧贴边框导致部分笔画被裁掉。解决裁剪时四周各扩 4-6 像素代码里写的是x - 4, y - 4这个外扩量按实际文字间距调整。如果识别框宽度超过 320不要强行缩放按宽度切分成两段分别识别再拼接效果更稳。5.3 onnxruntime 加载报错Op 不支持现象加载模型时直接报NotImplemented: Op not supported或者Unsupported operator。原因onnx 模型导出时的 opset 版本高于 onnxruntime 支持的版本。PPOCRv6 导出模型常用 opset 12 或 13如果装了很老的 onnxruntime比如 1.10 以下部分算子不识别。解决升级 onnxruntime 到 1.16 以上pip install -U onnxruntime。如果你同时要兼容低版本机器可以在导出的时后设置opset_version11但这可能要求 Paddle2ONNX 的版本也匹配不推荐自己动手直接升级运行时最简单。5.4 识别结果全是「口」或乱码现象检测框位置完全正确但识别出来的内容是一串口字或乱码跟图片内容毫无关系。原因字符表 dicts/ppocr_keys_v1.txt 与模型不匹配。onnx 模型里 embedding 层的类别数对应字符表长度是固定的如果你用错版本的字符表常见于解压后字符表文件被其他项目覆盖映射关系就会错位。解决确认字符表行数与 rec.onnx 模型输出的类别维度一致。检查方式是打印rec_session.get_outputs()[0].shape[-1]再数一下字符文件里有多少行。匹配不上就去重新解压原包不要自己拼字符表。5.5 CPU 推理比 Paddle 还慢现象用 onnxruntime 默认配置跑结果比原来 Paddle 框架还慢以为是量化后没生效。原因没有做任何会话优化配置onnxruntime 默认线程策略在部分 CPU 上不高效另外如果是小图线程切换开销占比很大。解决设置intra_op_num_threads4并把graph_optimization_level设为 ALL。小图长边小于 640优先用单线程顺序执行减少线程调度开销大图长边大于 2000多线程才有优势。还有个细节首次加载模型时会做线程池初始化耗时约几百毫秒别把这个时间算进推理耗时测试时先跑一次热身。5.6 识别结果张冠李戴整行内容错乱现象检测框位置正确但识别出的内容跟这个位置完全无关像是把另一行的文字识别到这里。原因检测框之间重叠度过高同一个文字区域被多个框重复框出或者裁剪区域内容偏向相邻文本。解决在后处理阶段对检测框做 NMS 非极大值抑制按置信度排序后删除重叠度超过 0.5 的框。onnxruntime 没有内置 NMS但可以用单测的方式用 numpy 实现核心逻辑是算两个框的交并比。6. 进阶用法把识别结果落成结构化 JSON并顺手处理四种常见版面跑通识别只是第一步真正落地到业务里需要把无结构的文本转成结构化数据。我一般会在识别完之后接一层结果清洗按照业务字段做正则切分输出 JSON 交到上层系统。这样识别管线就不只是 demo而是一个可以被接口直接调用的模块。import re def parse_contract(results): 把识别文本按字段提取成 JSON text \n.join([t for _, t in results]) fields { contract_no: re.search(r合同编号[:\s]*([A-Z0-9\-]), text), amount: re.search(r金额[:\s]*([0-9,\.]), text), date: re.search(r日期[:\s]*(\d{4}-\d{2}-\d{2}), text) } return {k: (v.group(1) if v else ) for k, v in fields.items()}这里有个很重要的实践字段提取的正则要写成容错版本比如冒号同时兼容中文冒号和英文冒号数字千分位分隔符同时兼容逗号和中文逗号。现实扫描件的识别结果里标点符号有大量偏差正则写得太严格会漏字段。处理完文本逻辑建议再加一个统一结果导出函数把检测框坐标、置信度、识别文本、提取字段全部写入一个字典再json.dump到磁盘。这样一次识别把调试信息和业务结果都留档了后续排查问题不用重新跑图。经过这个项目的复现我最大的收获是认识到 onnx 模型部署的难点不在模型加载而在前后处理的每个细节——坐标映射差一像素、字符表差一行、归一化顺序差一步结果就千差万别。从那以后我每次部署 onnx OCR 模型都强制走一遍从预处理参数、坐标逆变换、置信度阈值到字段落地的完整链路验证不再跳过任何一步这也让我后续的每个 OCR 项目都少走了很多弯路。希望这篇笔记也能帮你在 PPOCRv6 的 onnx 落地上少踩几个我踩过的坑。本文还有配套的精品资源点击获取