简介本资源为基于RapidOcr与Onnxruntime的离线文字识别依赖库面向需要在本地完成OCR处理的开发者与算法学习者尤其适合文档处理、车牌识别、屏幕截图转文本等对隐私与实时性有要求的场景。压缩包共991个文件约192.61MB以hpp、json、txt、o、cmake、so、bin、onnx等为主涵盖C头文件、模型配置、编译中间产物、动态库与ONNX模型文件并包含Android端jar、aar、dex、kt等构件便于跨平台集成。已有1493人学习下载。资源提供完整的依赖库与模型文件读者可据此在本地加载RapidOcr模型完成图像预处理、推理执行与结果后处理理解CRNN或Transformer类OCR模型的运行机制并掌握Onnxruntime的Session加载、硬件加速与资源释放等关键环节为离线文字识别项目提供可直接复用的工程基础。1. 离线 OCR 的最后一公里为什么我最终选了 RapidOcr-Onnxruntime上个月帮一个做档案数字化的朋友处理一批扫描件对方明确要求不能联网、不能调云 API、识别结果要能直接进他们的内部系统。我第一反应是 PaddleOCR但部署环境是台内网 Windows 机器装 Paddle 那套依赖折腾了一下午各种 DLL 冲突。后来换到 RapidOcr-Onnxruntime解压即用十分钟跑通。这就是我想聊这份依赖库的原因——它把文字识别里最烦人的模型加载、推理调度、前后处理全打包好了你只需要调一个接口。RapidOcr 本身是个轻量级 OCR 项目底层用 ONNX Runtime 做推理引擎模型是 PP-OCR 系列转过来的 ONNX 格式。相比直接上 PaddleOCR它的优势在于依赖极简就一个 onnxruntime 加几个 DLL启动快CPU 推理也能接受。适合谁内网环境、边缘设备、桌面工具集成、对识别精度要求不是极致但要求稳定可控的场景。如果你要做的是通用文字识别又不想被深度学习框架的依赖地狱折磨这份依赖库值得拆开看看。2. 拆开依赖包模型、推理引擎与调用链2.1 目录结构与核心文件拿到依赖包后别急着写代码先看清楚里面有什么。典型的 RapidOcr-Onnxruntime 依赖包结构大致如下RapidOcr-Onnxruntime/ ├── models/ │ ├── ch_PP-OCRv4_det_infer.onnx # 检测模型 │ ├── ch_PP-OCRv4_rec_infer.onnx # 识别模型 │ └── ch_ppocr_mobile_v2.0_cls_infer.onnx # 方向分类模型 ├── lib/ │ ├── onnxruntime.dll │ ├── opencv_world.dll │ └── RapidOcr.dll (或 .so) ├── config.yaml └── demo.exe / demo.py三个模型各司其职检测模型负责找出文字区域输出文本框坐标方向分类模型判断文本是否倒置或旋转 180 度识别模型把裁剪后的文本区域转成字符。这个三段式流程是 PP-OCR 的标准架构RapidOcr 把它固化成了固定管线。注意不同版本的依赖包模型文件名可能有差异以实际拿到的为准。如果 models 目录下只有两个模型说明方向分类被合并或省略了。2.2 ONNX Runtime 推理引擎的选型逻辑为什么用 ONNX Runtime 而不是直接上 Paddle Inference核心原因是部署便利性。ONNX Runtime 提供跨平台统一 APIWindows 上就一个 onnxruntime.dllLinux 上装个 pip 包或放个 .so 就行。而 Paddle Inference 需要匹配特定版本的 CUDA、cuDNN、MKL版本对不上就是一堆报错。另一个原因是模型格式。PP-OCR 的模型可以通过 Paddle2ONNX 工具转成 ONNX 格式转换后精度损失很小实测在千分之一量级。转完之后推理就不再依赖 Paddle 框架只依赖 ONNX Runtime。这意味着你的部署包体积能小很多启动速度也快不少。我一般会先确认 onnxruntime 的版本和模型 opset 是否匹配。如果加载模型时报NOT_IMPLEMENTED或Unsupported model IR version八成是版本对不上。解决办法是用onnxruntime的 Python 包先验证模型能否加载import onnxruntime as ort # 指定模型路径创建推理会话 session ort.InferenceSession( models/ch_PP-OCRv4_det_infer.onnx, providers[CPUExecutionProvider] # 内网环境用 CPU ) # 打印输入输出节点信息确认模型结构 for inp in session.get_inputs(): print(f输入: {inp.name}, 形状: {inp.shape}, 类型: {inp.type}) for out in session.get_outputs(): print(f输出: {out.name}, 形状: {out.shape})这段代码的作用是验证模型文件完整性以及 ONNX Runtime 能否正常解析。providers参数决定用 CPU 还是 GPU内网机器一般用CPUExecutionProvider如果有独显且装了 onnxruntime-gpu可以换成CUDAExecutionProvider。打印出的输入形状通常是[1, 3, 640, 640]或动态尺寸识别模型输入是[1, 3, 48, 320]这类固定高度、动态宽度的形式。2.3 检测-分类-识别三段管线的参数含义理解管线之后调参才有方向。检测阶段的关键参数是二值化阈值和文本框面积阈值。阈值太低会把噪点当文字太高会漏掉浅色文字。RapidOcr 的配置里通常有det_db_thresh和det_db_box_thresh两个参数前者控制像素级二值化后者控制文本框保留的最小置信度。识别阶段的核心参数是rec_img_h和rec_img_w即输入识别模型前把文本行 resize 到的高度和宽度。PP-OCR 默认高度 48宽度按比例缩放但不超过 320。如果你的文字特别小或特别大这个参数需要调整。方向分类的阈值一般是 0.9低于这个值就不做旋转避免误判。# config.yaml 关键参数示例 det: det_db_thresh: 0.3 # 二值化阈值降低可检出更多弱文字 det_db_box_thresh: 0.5 # 文本框置信度阈值 det_db_unclip_ratio: 1.6 # 文本框扩张比例避免文字被裁切 max_candidates: 1000 # 最大候选框数量 rec: rec_img_h: 48 # 识别输入高度 rec_img_w: 320 # 识别输入最大宽度 rec_batch_num: 6 # 批处理数量显存/内存够可加大 cls: cls_thresh: 0.9 # 方向分类置信度阈值 use_angle_cls: true # 是否启用方向分类det_db_unclip_ratio这个参数容易被忽略。检测模型输出的框往往比实际文字区域小一圈如果不做扩张识别时首尾字符会被切掉。1.5 到 2.0 之间是比较安全的范围。rec_batch_num影响推理速度设太大会吃内存CPU 推理建议 4 到 8 之间。3. 从零跑通一次识别代码、参数与输出解析3.1 最小可运行示例假设你已经拿到了依赖包Python 环境也装好了 onnxruntime 和 opencv-python下面这段代码可以直接跑import cv2 import numpy as np from rapidocr_onnxruntime import RapidOCR # 初始化引擎指定模型目录和配置 engine RapidOCR( det_model_pathmodels/ch_PP-OCRv4_det_infer.onnx, rec_model_pathmodels/ch_PP-OCRv4_rec_infer.onnx, cls_model_pathmodels/ch_ppocr_mobile_v2.0_cls_infer.onnx, use_angle_clsTrue, # 启用方向分类 det_db_thresh0.3, # 检测二值化阈值 rec_batch_num6 # 识别批大小 ) # 读取图片 img cv2.imread(test_scan.jpg) if img is None: raise FileNotFoundError(图片路径不对或文件损坏) # 执行识别 result, elapse engine(img) # result 是列表每项为 [文本框四点坐标, 识别文本, 置信度] if result: for box, text, score in result: print(f文本: {text} 置信度: {score:.4f}) print(f坐标: {box}) else: print(未检测到文字)这段代码的逻辑很直白初始化引擎时把三个模型路径传进去use_angle_cls决定是否启用方向分类。engine(img)返回两个值第一个是识别结果列表第二个是各阶段耗时。结果里每个元素包含文本框坐标四个点的 x,y、识别出的字符串、置信度分数。3.2 参数调整与效果对比默认参数在大多数扫描件上表现不错但遇到特殊情况需要微调。我整理了一个参数对照表方便快速定位参数默认值调大效果调小效果适用场景det_db_thresh0.3减少误检可能漏检检出更多噪点增多干净文档调大复杂背景调小det_db_box_thresh0.5只保留高置信框保留更多候选框文字清晰调大模糊调小det_db_unclip_ratio1.6文本框更宽松文本框更紧凑手写体调大印刷体可调小rec_batch_num6推理更快内存占用高内存友好速度慢内存充足调大嵌入式调小cls_thresh0.9减少误旋转更容易触发旋转正常方向文档调大实际调参时建议一次只改一个参数用同一张测试图对比结果。我一般会准备三张图一张标准印刷文档、一张倾斜拍摄的、一张带表格的覆盖常见场景。3.3 输出结果的后处理识别出来的原始结果往往需要进一步处理才能用。比如文本框坐标是四点形式要转成矩形框方便裁剪或标注def box_to_rect(box): 四点坐标转矩形 (x_min, y_min, x_max, y_max) xs [p[0] for p in box] ys [p[1] for p in box] return int(min(xs)), int(min(ys)), int(max(xs)), int(max(ys)) # 按纵向位置排序还原阅读顺序 result_sorted sorted(result, keylambda x: box_to_rect(x[0])[1]) # 合并同一行的文本 lines [] current_line [] last_y None for box, text, score in result_sorted: _, y_min, _, y_max box_to_rect(box) center_y (y_min y_max) / 2 if last_y is None or abs(center_y - last_y) 15: # 15 像素容差 current_line.append(text) else: lines.append(.join(current_line)) current_line [text] last_y center_y if current_line: lines.append(.join(current_line)) for line in lines: print(line)这段后处理的目的是把散落的识别结果按阅读顺序拼回段落。box_to_rect把四点坐标转成矩形方便计算纵向位置。排序后按中心 y 坐标分组容差 15 像素是个经验值字号大的文档可以适当加大。这一步不做的话输出就是一堆乱序的文本片段没法直接用。4. 避坑指南模型加载、内存与精度问题排查4.1 模型加载失败版本与路径的坑现象初始化引擎时报Failed to load model或Invalid ONNX model。原因最常见的是 onnxruntime 版本和模型 opset 不匹配。比如模型是用 opset 16 导出的但你的 onnxruntime 是 1.8 版本只支持到 opset 13。另一个原因是模型文件下载不完整或者路径里有中文导致读取失败。解决先用onnxruntime.__version__确认版本建议 1.12 以上。然后用 2.2 节的代码单独加载模型验证。路径尽量用英文如果必须用中文路径在 Python 里用os.path.abspath转成绝对路径再传进去。4.2 内存暴涨批处理与图像尺寸的平衡现象处理大图或连续处理多张图时内存持续上涨最终 OOM。原因rec_batch_num设太大或者输入图像分辨率过高。检测模型会把原图 resize 到 640 或 960但如果原图是 4000x3000resize 后仍然很大。另外 OpenCV 的 Mat 对象如果不手动释放在循环里会累积。解决把rec_batch_num降到 4 以下检测输入尺寸限制在 960 以内。循环处理时显式调用del img并配合gc.collect()。如果还是不够可以先把大图切分成小块再识别。4.3 识别精度差预处理与模型选择的取舍现象识别结果乱码、漏字、置信度普遍低于 0.5。原因可能是图像质量太差模糊、光照不均、分辨率过低也可能是模型选错了。PP-OCRv4 的识别模型对印刷体友好但手写体或特殊字体效果会下降。另外如果图片是灰度图或二值图直接送进去可能不如转成三通道效果好。解决先做基础预处理——转灰度、自适应二值化、去噪。如果文字太小先放大 2 倍再识别。模型方面可以尝试换成ch_PP-OCRv3_rec_infer对比效果不同版本对不同场景的适配有差异。4.4 方向分类误判阈值与场景的匹配现象正常方向的文字被旋转了 180 度识别结果完全错误。原因cls_thresh设得太低方向分类模型把正常文本误判为倒置。这种情况在短文本比如单个词或数字上尤其常见因为分类模型缺乏足够上下文。解决把cls_thresh提高到 0.95 甚至 0.99。如果文档方向统一可以直接关掉use_angle_cls省掉这一步推理。对于混合方向的场景建议先做整图方向检测再决定是否启用分类。4.5 多线程调用崩溃会话不是线程安全的现象在 Web 服务或多线程环境里调用引擎程序随机崩溃或返回空结果。原因ONNX Runtime 的 InferenceSession 不是线程安全的多个线程同时调用同一个 session 会导致内存错乱。解决每个线程创建独立的引擎实例或者用锁把推理调用串行化。如果并发量不大加个threading.Lock最简单。并发量大的话建议用进程池而不是线程池每个进程独立加载模型。5. 进阶技巧批量处理与精度验证的实操习惯批量处理是实际项目里绕不开的需求。我一般会写一个带进度条和异常捕获的批处理脚本核心逻辑如下import os import cv2 from concurrent.futures import ProcessPoolExecutor, as_completed from rapidocr_onnxruntime import RapidOCR def ocr_single(img_path): 单张图片识别返回文件名和文本行列表 engine RapidOCR( det_model_pathmodels/ch_PP-OCRv4_det_infer.onnx, rec_model_pathmodels/ch_PP-OCRv4_rec_infer.onnx, use_angle_clsTrue ) img cv2.imread(img_path) if img is None: return img_path, [] result, _ engine(img) if not result: return img_path, [] # 按 y 坐标排序后拼接 sorted_res sorted(result, keylambda x: min(p[1] for p in x[0])) return img_path, [text for _, text, _ in sorted_res] def batch_ocr(img_dir, max_workers4): 批量识别目录下所有图片 img_files [ os.path.join(img_dir, f) for f in os.listdir(img_dir) if f.lower().endswith((.jpg, .png, .bmp)) ] results {} with ProcessPoolExecutor(max_workersmax_workers) as executor: futures {executor.submit(ocr_single, p): p for p in img_files} for future in as_completed(futures): path, lines future.result() results[path] lines print(f完成: {os.path.basename(path)} 行数: {len(lines)}) return results if __name__ __main__: res batch_ocr(./scans, max_workers4) for path, lines in res.items(): print(f\n {path} ) for line in lines: print(line)这里用ProcessPoolExecutor而不是线程池原因是每个进程独立加载 ONNX Runtime 会话避免线程安全问题。max_workers建议设为 CPU 核心数的一半太多反而会因为内存竞争变慢。每个子进程里重新初始化引擎是必要的虽然有点浪费但稳定。精度验证方面我习惯准备一个标注好的小测试集至少 20 张图覆盖不同字体、字号、背景。每次调参后跑一遍统计字符准确率编辑距离和行准确率。不要只看几张图的效果就下结论OCR 的玄学在于同一张图换个参数可能天差地别。提示如果项目对精度要求高可以考虑把检测和识别模型换成更大的版本比如ch_PP-OCRv4_server_det和ch_PP-OCRv4_server_rec代价是推理速度下降 2 到 3 倍。从那以后我每次集成 OCR 依赖库都强制走一遍「单图验证 → 批量压测 → 内存监控 → 精度抽检」的流程不再凭感觉调参。希望帮到你。本文还有配套的精品资源点击获取