ncnn+PP-OCRv5：Android离线OCR部署实战

最近在给一个安卓项目加离线OCR能力，目标很明确：拍照或从相册选图，识别出图片里的中英文文字。当时没有多犹豫，直接锁定了 nihui/ncnn-android-ppocrv5 这个开源项目来做。原因很简单：ncnn 在移动端推理框架里属于老牌选手，而 PP-OCRv5（PaddleOCR 的第5代检测识别模型）在中英文识别，尤其是中文场景下，效果比 Tesseract 这类传统 OCR 好太多。

这个仓库是一个可以直接拉下来编译的 Android 示例工程，里面已经把 ncnn 编译好了、PP-OCRv5 的检测和识别模型也转成了 ncnn 格式，还封装好了 JNI 接口。你要做的事情，其实就是把它接入自己的 App，处理好图片选择和权限，再针对自己的业务场景微调几个检测参数。

这篇文章我会把我实际部署的完整过程写出来，包括环境准备、模型格式转换、Android 工程集成、图片 Uri 处理、参数调优，以及一路上踩过的坑。适合刚接触 Android OCR、或者对 ncnn 部署有兴趣的同学，照着走基本能跑通。

1. 项目核心思路：为什么是 ncnn + PP-OCRv5

1.1 这套组合解决了什么问题

OCR 在移动端有两种做法，一种是联云端 API，一种是在本地跑模型。联云端方案识别率确实好，但离线不能用、有并发和费用问题，还会把图片内容送出去，很多企业内部项目根本接受不了。本地方案里，传统做法是 Tesseract，部署简单，中文识别效果却不尽如人意，复杂一点的中文场景基本没法看。

nihui/ncnn-android-ppocrv5 走的是本地推理路线。它在端侧加载两个 ncnn 格式模型，跑两阶段 OCR 流程。第一个模型做文本检测，把图片里的文字行区域用框标出来；第二个模型做文本识别，把每个文字行区域内的内容识别成字符串。检测模型和识别模型都是 PP-OCRv5 系列的，模型体积控制在十几 MB 这个量级，在手机上跑一次完整识别大概在几百毫秒到一两秒之间，实用性很高。

这套方案最大的价值在于：不需要自己折腾从 Paddle 到 ncnn 的转换链路，也不用自己写 JNI 和 OpenCV 图像处理逻辑。项目里全都有，直接拿来用就是。

1.2 对比市面上其他方案

我把常见方案都对比过一遍，下面这张表可以很直观地看出差异：

选 ncnn + PP-OCRv5 不是因为别的选择不行，而是在“端侧离线 + 中文效果好 + 工程化完善”这三个条件同时满足的情况下，它基本是当前最优解。

1.3 ncnn 的工程化优势

ncnn 是腾讯优图实验室开源的移动端推理框架，后来由 nihui 主导维护。它跟 TensorFlow Lite、ONNX Runtime Mobile 比，最大的优势是专门为手机 CPU、ARM 架构做了深度优化，支持 Vulkan GPU 加速，而且没有太多运行时依赖，编译产物非常干净。

在这个项目里，ncnn 承担的是推理引擎的角色。你输入图片给 ncnn，它把图片数据喂给模型做前向计算，然后把结果返回。整个过程在 App 进程内完成，不涉及网络请求，这也是它适合离线场景的根本原因。

2. 部署前环境准备与模型格式转换

2.1 需要提前装好的工具

在动工程之前，先把环境处理好。我用的是 Ubuntu 20.04 做模型转换，Windows 上用 Android Studio 写工程，这个组合比较常见。需要准备的东西有这些：

• Android Studio（新版可以直接从官网下载，安装包不到 1GB，装完在 SDK Manager 里勾选 NDK 和 CMake）
• Android SDK、NDK（建议 NDK r23 或以上，但要避免用最新版，后文有坑）
• CMake 3.10 以上
• Python 3.7 + PaddleOCR 或 PaddleOCR 官方模型库（用于导出 ONNX）
• onnx2ncnn 工具（在 ncnn 源码 build/tools/onnx 目录下）

Android Studio 的安装没什么特别之处，一路下一步就行。需要留意的是首次启动后要下载 SDK 组件，国内网络环境下可能需要开代理，或者直接去 Android 开发者官网下载离线 SDK 包。

2.2 模型转换链路：Paddle → ONNX → ncnn

仓库里默认已经内置了转好的 ncnn 模型，如果你直接用原仓库跑，可以跳过这一步。但如果你想换模型版本、或者后续想针对自己的场景重新训练模型，这条转换链路就很重要了。

PP-OCRv5 官方提供的是 Paddle 训练格式模型，ncnn 不能直接加载 Paddle 模型，需要做两步转换。

第一步，把 Paddle 模型导出为 ONNX。PaddleOCR 官方仓库提供了paddle2onnx工具，导出命令大致是：

paddle2onnx \ --model_dir ./inference/ch_PP-OCRv5_det_infer \ --model_filename inference.pdmodel \ --params_filename inference.pdiparams \ --save_file ./ch_PP-OCRv5_det.onnx \ --opset_version 11

识别的模型同理，把det换成rec再执行一遍。

第二步，用onnx2ncnn把 ONNX 转成 ncnn 的 .param 和 .bin 文件。onnx2ncnn相当于 ncnn 的模型翻译官，做各种算子的翻译和映射，把 ONNX 里的规则翻译成 ncnn 自己的描述语言。

./onnx2ncnn ch_PP-OCRv5_det.onnx ch_PP-OCRv5_det.param ch_PP-OCRv5_det.bin

转换完成后，把生成的 .param 和 .bin 文件放进 Android 工程的assets目录，代码里用loadModel加载即可。

提示：模型转换过程中的算子兼容问题很常见，尤其是自定义算子。遇到报错时优先考虑冻结模型的输入输出维度，onnx2ncnn对静态 shape 的模型支持更好。

2.3 转换过程中常见的坑

转换链路看着简单，实际操作时最容易出问题的是这几个地方。

一个是 Paddle 的动态图导出和静态图导出问题。如果直接拿动态图模型转 ONNX，部分算子会多出不必要的动态维度描述，导致 onnx2ncnn 解析失败或生成错误 shape。建议先通过 Paddle 的paddle.jit.to_static或者在导出 infer 模型时打开--export相关参数，把模型冻结成静态图再转。

另一个是激活函数和归一化算子的融合问题。ONNX 里经常出现一些碎算子，比如BatchNormalization后面挂Relu，ncnn 有融合优化，但某些组合可能支持不完整。碰到这种情况，要么改导出参数，要么手动在 ONNX 里做算子简化，onnxsim这个工具在这时候很有用，跑一遍能大幅减少冗余算子。

另外就是老生长谈的 shape 动态维问题。PP-OCRv5 检测模型要求输入图片宽高是 32 的倍数，识别模型输入固定 48x320（h x w）。这个在 Android 端调用的时候要特别注意，图片 resized 之后要检查是否对齐模型输入要求，否则识别结果会莫名变差。

3. 把 ncnn-android-ppocrv5 集成到自己的 App

3.1 项目目录结构解析

先把这个仓库 clone 下来：

git clone https://github.com/nihui/ncnn-android-ppocrv5.git

目录结构很清晰，核心部分集中在app/src/main下：

• assets/ch_PP-OCRv5_det.param/.bin：文本检测模型
• assets/ch_PP-OCRv5_rec.param/.bin：文本识别模型
• cpp/ncnn_ocr.cpp：JNI 接口层，负责加载模型、调用推理、返回结果
• java/.../MainActivity.java：示例 UI，负责选图和显示结果

如果只是想先跑通 demo，直接用 Android Studio 打开这个工程编译到手机上就能看到效果。界面很简单：一个按钮选图，一个按钮跑识别，下面一个 TextView 显示文字结果。

3.2 把代码搬进自己的工程

实际项目里没人会把 demo 当生产代码用，大部分情况是把 ncnn 推理能力抽出来，嵌入到自己的业务 App。抽取的时候核心就三块：cpp目录下的 JNI 代码、assets目录下的模型文件、以及构建配置。

ncnn_ocr.cpp是整个工程最值钱的部分。它内部主要做了四件事：

1. 加载 ncnn 模型并初始化，打开可选的 Vulkan 加速
2. 接收 Java 层传下来的 Bitmap 或路径，转成 ncnn 需要的 Mat 格式
3. 先跑检测模型，拿到文字行坐标集合
4. 对每个文字行区域做裁剪、缩放、归一化，再跑识别模型，拼出最终字符串

这些逻辑如果你完全自己写，工作量不小。直接搬这个 cpp 是最好的选择，它把 ncnn 的 C API 和 Java 层做了很好的隔离。你唯一要改的，可能就是把自己的包名塞进 JNI 函数注册的地方，以及封装一个更符合自己项目风格的OcrEngine单例。

3.3 构建配置和 so 库

app/build.gradle里有关键的 abiFilters 配置：

defaultConfig { ndk { abiFilters 'arm64-v8a' } }

这里我建议只保留arm64-v8a。现在市面上 99% 的手机都是 64 位处理器，集成armeabi-v7a和x86只会把 APK 体积撑大，没有实际意义。如果测试机是老设备，再加armeabi-v7a也不迟。

ncnn 的 so 库在这个项目里是预编译好的，会随工程一起打包，不需要你自己编译 ncnn。这个省了很多事，因为 ncnn 从源码编译要下载很多依赖，容易卡在各种网络问题上。

3.4 Java 层封装示例

调用识别不复杂，核心代码大概长这样：

public class OcrEngine { static { System.loadLibrary("ncnn_ocr"); } private long nativeHandle; public OcrEngine(String detParam, String detBin, String recParam, String recBin) { nativeHandle = init(detParam, detBin, recParam, recBin); } public native long init(String detParam, String detBin, String recParam, String recBin); public native String recognize(long handle, Bitmap bitmap); // 使用完记得释放 public native void destroy(long handle); }

注意assets里的模型路径要对上，别姓脱了。加载模型的时机建议放在后台线程，因为模型加载在低端机上耗时可能到几百毫秒，放主线程会卡。

4. 图片选择与 Android 11+ 文件访问那点事

4.1 不要直接传 file:// 路径

这块百分百是新人最容易踩的坑。Android 4.4 以后，通过ACTION_GET_CONTENT或ACTION_OPEN_DOCUMENT选图返回的 Uri 都是content://开头，不是file:///storage/...这种路径。很多老教程会教你先拿到文件路径，再传给 native 层，这在 10 以上的设备上完全行不通，因为分区存储机制，直接访问真实路径会抛FileNotFoundException或者权限被拒。

我自己就在这上面折腾了很久。一开始图省事，直接从 Uri 拼路径传给 JNI，结果在 Android 12 的真机上直接报错，输入图片读不出来，OCR 返回空结果。后来改成在 Java 层把 Bitmap 解码好，直接传给 native，这个世界瞬间清净了。

4.2 正确选图姿势

选图用系统 API 就行，不需要申请存储权限。现代方案是ActivityResultContracts.PickVisualMedia，不需要在 Manifest 里声明任何存储权限：

ActivityResultLauncher<String> launcher = registerForActivityResult( new ActivityResultContracts.GetContent(), uri -> { if (uri != null) { startOcr(uri); } }); launcher.launch("image/*");

拿到 Uri 之后，在 Java 层做解码：

ContentResolver resolver = getContentResolver(); InputStream is = resolver.openInputStream(uri); Bitmap bitmap = BitmapFactory.decodeStream(is);

这样拿到的 Bitmap 就可以直接传给 native 层。整个过程完全不碰文件路径，完美避开content://权限和分区存储的各种破事。

提示：从相册选大图时，BitmapFactory.decodeStream会按原始尺寸解码，一张 4800 万像素的照片直接干几百 MB 内存，App 必崩。一定要先用inSampleSize做采样压缩，把长边控制在 2000 像素以内再传给 OCR。

4.3 content:// Uri 的权限生命周期

通过GetContent拿到的 Uri，权限是临时的，只存活到当前 Activity 所在的 task 结束。如果你只是选完图立刻识别，那没问题。但如果你把 Uri 存下来下次启动再用，或者传给其他组件，就会发现权限失效了。

要持久化读取权限，需要手动调用：

getContentResolver().takePersistableUriPermission(uri, Intent.FLAG_GRANT_READ_URI_PERMISSION);

调这个方法之前，Intent 里必须带上对应的 flag。这个逻辑在OpenDocument模式下支持，GetContent模式则没有持久化权限这一说，下次要重新选图。

顺带说一句，很多国内 ROM（比如某些第三方文件管理器）返回的 Uri 前缀五花八门，什么content://com.tencent.wework.fileprovider、content://com.ss.android.uri.key这种，都是不同 App 自定义的 FileProvider。别被前缀吓到，你只要不直接拼路径，直接通过ContentResolver去读 InputStream，都能正常处理。

4.4 Bitmap 预处理和 EXIF 方向

手机拍出来的照片经常带 EXIF 旋转信息，相册软件会读 EXIF 帮你把图显示正，但BitmapFactory.decodeStream不会。这会导致识别时图片是旋转过的，文本行检测框全部歪掉，识别率断崖式下降。

解决办法是在解析完 Bitmap 后，读一下 EXIF 方向并做旋转：

ExifInterface exif = new ExifInterface(inputStream); int orientation = exif.getAttributeInt( ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL); Matrix matrix = new Matrix(); // 根据 orientation 值旋转 0/90/180/270 Bitmap rotated = Bitmap.createBitmap(bitmap, 0, 0, bitmap.getWidth(), bitmap.getHeight(), matrix, true);

另外在传给 native 之前，最好也做一下长边缩放。PP-OCRv5 检测模型内部会把输入图像 resized，但如果原图太大，resize 过程会引入明显的比例失真，加上压缩损失，检测效果会下降。我习惯先把长边压到 1600-2000 像素，识别速度和准确率都更稳定。

5. 识别参数调优：并不是装上就能识别好

5.1 核心参数怎么调

运行起来不代表效果就好，参数调优才是真正决定 OCR 能不能用的环节。项目里 ncnn 的 OCR 检测部分有几个关键参数，直接影响识别效果：

box_thresh是最容易影响识别结果的参数。默认值偏向保守，遇到文字模糊或者背景复杂的情况，检测框可能直接漏检。我之前处理一单证件照类图片，字体偏小且有点反光，默认阈值下能识别出来的文字寥寥无几，把box_thresh调到 0.35 之后，检测框数量明显增加，最终识别内容也完整了很多。

5.2 检测和识别的配合逻辑

两阶段 OCR 模型是串联工作的，检测模块负责找出所有“可能是文字”的位置，识别模块负责把这些位置的文字读出来。这里有一个逻辑陷阱：如果检测框生成质量不行，识别模块再强也没用。

检测框生成质量主要体现在两个维度：框的完整性和框的纯净度。完整性是说一个文字行不要被拆成多个碎框，纯净度是说框里不要夹杂太多背景干扰。unclip_ratio这个参数就是干这个事的。默认 2.0 是我在多种图片上试出来比较中庸的值，如果图片里的文字是横幅、标题那种大字，可以适当调大；如果是表格里的密集小字，调小会更好，因为框扩太多容易把相邻文字行粘在一起。

识别模块内部还有一些后处理逻辑，比如根据置信度过滤输出、处理空白字符等，这些一般不需要动。你唯一可能要调的是rec_thresh，但这个建议保持默认，识别置信度阈值调节效果远不如检测参数敏感。

5.3 性能和内存优化

OCR 在手机上跑，最怕的是卡和内存暴涨。在集成后发现一个典型问题：如果传一张 4000x3000 的原图直接进去，识别过程中内存峰值能到 800MB 甚至 1GB，低端机器直接回收。

后来优化思路很明确：

• 图片在 Java 层先压缩到长边 1600 再传 native
• 只保留arm64-v8a的 so
• 初始化 ncnn 时开启use_vulkan，让 GPU 分担部分计算
• 识别完成后立即释放模型和 Mat，避免长驻内存

按这个方案优化后，中端机识别一张普通图片的内存峰值控制在 200-300MB，单次识别的耗时在 400ms 到 1.2s 之间，日常使用完全能接受。

注意：开启 Vulkan 加速前，先确认测试设备支持 Vulkan。绝大多数 2019 年之后的手机都没问题，但部分低端机或模拟器不支持，开启后直接崩。稳妥的做法是运行时检测ncnn.isSupportVulkan()，支持才开。

6. 我在实际部署中遇到的典型问题排查

6.1 一直加载不出模型

模型加载失败是最常见的。检查点依次是：模型文件 .param 和 .bin 是否确实打包进了 APK 的 assets 目录；assets 目录里的文件名是否和 Java 层传的名字完全一致（大小写也算）；模型加载路径是否正确。

用 Android Studio 的 APK Analyzer 打开构建产物，直接检查 assets 目录，能看到文件就没问题。还有一种隐蔽情况，某些渠道打包插件会对 assets 做压缩或改名，遇到这种情况要在打包配置里排除 assets 目录的处理规则。

6.2 报错 “could not create a primitive”

某些手机上运行时会看到这个名错误，紧跟后面的内容一般是某些算子创建失败。这个坑本质是 ncnn 在某些 ARM 平台或旧 GPU 驱动下，某个算子实现不可用，OpenCV 部分图像处理也会出现类似问题。

我当时查了很久，最后发现是 Vulkan shader 编译的锅。部分国产 GPU 驱动的 shader 编译器和 ncnn 的某些算子不兼容。解决办法很简单：在该设备上关闭 Vulkan 加速，强制走 CPU 推理。牺牲点速度换来稳定，性价比很高。

6.3 返回结果 “no text detected” 或空字符串

模型加载成功、代码没崩，但结果为空。这种情况九成是图片预处理问题。

逐项排查：

• 图片是否全白或全黑、模糊不可读
• 图片是否旋转了 90/180/270 度
• 传入的 Bitmap 是否已经释放
• 图片分辨率是否过大，检测框全被过滤
• box_thresh是否设置过高

之前我拿一个从网上下载的 RGB 格式图片直接测试，native 层按 RGBA 读，结果通道错乱，识别结果基本空。检查后修正了通道顺序，问题就解决了。

6.4 编译报错、NDK 版本冲突等构建问题

用别人项目最怕编译不过。这个项目对 NDK 版本有一定容忍度，但如果你用的 NDK 版本过新，可能会在 CMake 阶段报类似 “Tag number over 30 is not supported” 的错。这个报错跟 protobuf 版本有关，常见于 OpenCV 或 ncnn 内置的模型读取逻辑跟新版本 protobuf 冲突。

建议使用 NDK r23 到 r25 之间的版本，太新太老都容易有幺蛾子。在build.gradle里明确指定：

android { ndkVersion "25.2.9519653" }

另一个常见问题是 C++ 标准库冲突。如果工程里还接了其他 native 库，要确保所有库都使用相同的 STL 实现（c++_shared 或 c++_static），不然运行时会报 symbol not found。

6.5 国产 ROM 的权限和路径问题

在小米、华为等设备上测试时，偶尔会出现选了图片但读不到数据的情况。这类问题基本可以归为 ROM 定制系统的文件访问差异，尤其是相册 App 进程被杀、FileProvider 路径失效等。规避手段就是前面说的：依赖ContentResolver.openInputStream读取，不信任任何直接路径获取逻辑。

另外国内 ROM 经常有“分离的存储权限”这种东西，即使 Manifest 里声明了存储权限，用户没在设置里手动打开也没用。最好的做法是根本不要申请存储权限，走系统文件选择器就不会有这些权限问题。

7. 几个可以继续扩展的方向

如果你不想止步于现成 demo，这几个方向我认为价值比较大。

第一个是替换模型文件。PP-OCRv5 模型是通用场景的，如果你要识别特定类型的内容，比如发票、说明书、或者某种特殊字体，可以考虑用 PaddleOCR 的微调训练，训练好的模型按第一节的链路转成 ncnn 格式替换进来即可。我自己试过用少量业务数据微调后的识别模型，准确率提升很明显。

第二个是加文本方向分类。PP-OCRv5 的识别模型对 0 度和 180 度的识别做了优化，但 90 度和 270 度的图还是需要先用分类模型调整方向。如果你需要识别的图片方向不固定，可以额外接一个文本方向分类器，在传给识别模型之前先做旋转归一化。

第三个是识别结果的结构化输出。ncnn OCR 返回的是纯文本和每行文字行的坐标框。有了坐标框，你可以自己实现版面分析，比如把表格、段落、标题这些结构信息提取出来，输出 JSON 格式，这对做文档扫描类 App 很有用。

第四个是接入大图的分块识别。如果图片分辨率特别大，整图缩放送进去会丢掉小字细节。可以把图片按重叠分块的方式切成若干小图，分别识别再拼接结果。这个方案我在做票据识别时验证过，细节召回率提升很明显。

回过来再聊一点实际体会。把 OCR 从云端搬到端侧最直观的价值是：识别一张图不再有网络耗时，也不会有隐私顾虑。而 ncnn + PP-OCRv5 这个组合，让我第一次觉得“端侧中文 OCR”达到了能落地的质量线。过程中模型转换、Uri 处理、参数调节这些细节，说多了都是泪，但只要按上面的链路走一遍，基本能避开我踩过的所有坑。

最后再分享一个小技巧：如果你在开发阶段想快速验证模型效果，不用每次都编译装 App，可以在 Ubuntu 上直接用 ncnn 的 C++ 示例程序跑一张本地图片，输出识别文本，调试速度和方便程度都高很多。等确认模型没问题了，再回头调 Android 工程，能省下大量编译等待时间。