PaddleOCR Android 部署实战基于 ONNX Runtime 的 PP-OCRv6 移动端 SDK 集成指南【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR导读本文以 PaddleOCR 仓库中 android_deployment.md 官方部署文档为主体系统讲解如何在 Android 平台基于 ONNX Runtime 完成 PP-OCRv6 文本检测与识别的端到端部署。你将掌握 SDK/Demo 分离的项目架构、模型下载与放置规范、Gradle 编译运行流程、两种 SDK 集成方式源码依赖与 AAR、完整的 API 调用与参数调优方法以及基于 Instrumentation 测试的自动化性能 Benchmark 方案可直接落地到自有 App 的 OCR 能力建设中。一、项目概述PP-OCRv6 在 Android 上的部署形态deploy/ppocr-android是 PaddleOCR v6 在 Android 平台的官方部署示例其核心设计是基于 ONNX Runtime 的移动端 OCR 推理。与传统的 Paddle Lite 方案不同该项目通过将 PP-OCRv6 系列模型导出为 ONNX 格式借助 ONNX Runtime Android 运行时在移动端完成推理从而获得良好的跨平台可移植性与性能表现。项目采用SDK 与 Demo 分离的架构ppocr-sdk是一个独立的 Android LibraryAAR封装了完整的 OCR 推理管线可单独集成到第三方应用app则是一个基于 MVVM Jetpack Compose 的 Demo 应用用于演示 SDK 的完整调用流程。这种架构让开发者可以直接复用 SDK 模块而无需关心底层 ONNX Runtime 会话管理、OpenCV 图像处理等细节。功能特性文本检测 文本识别端到端流程一次输入图片即可得到带坐标与置信度的文本行结果支持 PP-OCRv6 系列 ONNX 模型同时兼容 PP-OCRv5 mobile 模型详细的性能计时检测/识别各阶段预处理、推理、后处理耗时均可获取MVVM Jetpack Compose 构建的现代化 Demo 应用支持 AAR 方式集成也可源码方式依赖项目结构deploy/ppocr-android/ ├── ppocr-sdk/ # OCR SDKAndroid Library │ ├── src/main/ │ │ ├── assets/models/ # 模型文件目录 │ │ │ ├── det/ # 检测模型inference.onnx │ │ │ └── rec/ # 识别模型inference.onnx, inference.yml │ │ └── java/com/paddle/ocr/ │ │ ├── PaddleOCR.kt # [公开 API] SDK 入口 │ │ ├── PaddleOCRConfig.kt # [公开 API] 推理参数配置 │ │ ├── EngineConfig.kt # [公开 API] 推理线程配置 │ │ ├── engine/ # 检测/识别引擎与 ONNX 会话管理 │ │ ├── preprocess/ # 检测/识别预处理DetPreprocessor 等 │ │ ├── postprocess/ # DB 后处理、CTC 解码、文本行排序等 │ │ ├── model/ # 结果数据模型OCRRunResult 等 │ │ └── util/ # Bitmap/OpenCV/YAML 等工具类 │ ├── proguard-rules.pro # SDK 混淆规则 │ └── build.gradle.kts ├── app/ # Demo AppCompose UI │ ├── src/main/java/com/paddle/ocr/demo/ │ │ ├── OCRApplication.kt # 初始化 SDK │ │ └── ui/ # Compose UIHomeScreen、ViewModel 等 │ └── build.gradle.kts ├── gradle/libs.versions.toml # 统一版本目录 ├── run_benchmark.sh # 性能测试脚本 └── settings.gradle.kts # 工程配置包含 :app 与 :ppocr-sdk从源码结构看SDK 内部的模块划分与 Python 端 PP-OCR 管线一一对应DetectionEngine检测引擎负责定位文本区域RecognitionEngine识别引擎负责逐区域识别二者由OCREngine统一编排为完整流水线这部分实现位于 OCREngine.kt。二、环境要求依赖版本Android StudioLadybug (2024.2)JDK17Kotlin2.1.0minSdk26 (Android 8.0)ONNX Runtime1.21.1OpenCV4.5.3这些版本约束在 libs.versions.toml 中通过版本目录Version Catalog统一管理包括 AGP 8.7.3、Compose BOM 2024.12.01、kotlinx-coroutines 1.9.0 等。值得注意的是minSdk 26Android 8.0意味着覆盖了绝大多数存量设备ONNX Runtime 1.21.1 与 OpenCV 4.5.3通过com.quickbirdstudios:opencv依赖引入则是移动端推理与图像处理的两大运行时基础。提示国内网络环境下settings.gradle.kts已默认配置了阿里云 Maven 镜像google/central/gradle-plugin可显著加速依赖下载。三、快速开始从克隆到跑通 Demo1. 克隆项目git clone https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR/deploy/ppocr-android2. 准备模型本项目支持以下模型检测模型与识别模型需成对下载模型HuggingFaceBOSPP-OCRv6_small检测模型PP-OCRv6_small_det_onnx/ 识别模型PP-OCRv6_small_rec_onnx检测模型PP-OCRv6_small_det_onnx_infer.tar/ 识别模型PP-OCRv6_small_rec_onnx_infer.tarPP-OCRv6_tiny检测模型PP-OCRv6_tiny_det_onnx/ 识别模型PP-OCRv6_tiny_rec_onnx检测模型PP-OCRv6_tiny_det_onnx_infer.tar/ 识别模型PP-OCRv6_tiny_rec_onnx_infer.tarPP-OCRv5_mobile检测模型PP-OCRv5_mobile_det_onnx/ 识别模型PP-OCRv5_mobile_rec_onnx检测模型PP-OCRv5_mobile_det_onnx_infer.tar/ 识别模型PP-OCRv5_mobile_rec_onnx_infer.tar下载并解压后将文件放入ppocr-sdk/src/main/assets/models/目录注意检测与识别模型的放置路径不同检测模型将inference.onnx放入models/det/识别模型将inference.onnx和inference.yml放入models/rec/其中inference.yml是识别模型的配套配置文件SDK 在初始化时会通过ModelConfig.parse(context, recConfigAsset)解析其中的字符表character list用于后续 CTC 解码还原文本见 OCREngine.kt 的初始化逻辑。默认的模型资源路径为models/det/inference.onnx与models/rec/inference.onnx这与 OCREngine.kt 中的默认参数一致。3. 编译运行# 编译 Debug APK ./gradlew :app:assembleDebug # 安装到设备 ./gradlew :app:installDebug或使用 Android Studio 直接打开deploy/ppocr-android目录运行。注意工程包含:app与:ppocr-sdk两个模块见 settings.gradle.kts。4. 体验 Demo打开 PP-OCRv6 Demo 应用等待模型加载完成应用启动时会通过OCRApplication.kt初始化 SDK点击 Select from Gallery 选择图片查看识别结果和耗时统计Demo 的 Compose UI 位于 app/src/main/java/com/paddle/ocr/demo/ui其中OCRViewModel通过协程调用 SDK 的 suspend APITimingBar组件以可视化方式展示各阶段耗时方便开发者直观了解性能分布。四、SDK 集成两种方式接入你的应用方式一源码依赖将ppocr-sdk/目录复制到你的项目根目录在settings.gradle.kts中添加模块include(:ppocr-sdk)在 App 模块的build.gradle.kts中添加依赖implementation(project(:ppocr-sdk))源码方式便于直接阅读、调试 SDK 内部实现适合需要深度定制预处理/后处理逻辑的场景。方式二AAR 依赖# 构建 AAR ./gradlew :ppocr-sdk:assembleReleaseAAR 输出路径ppocr-sdk/build/outputs/aar/ppocr-sdk-release.aar在 App 模块的build.gradle.kts中添加dependencies { implementation(files(libs/ppocr-sdk-release.aar)) // AAR 不传递依赖需手动添加 implementation(com.microsoft.onnxruntime:onnxruntime-android:1.21.1) implementation(com.quickbirdstudios:opencv:4.5.3) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0) }关键提醒AAR 不会传递依赖ONNX Runtime、OpenCV、协程这三个运行时依赖必须由集成方手动声明且版本需与 SDK 编译时保持一致1.21.1 / 4.5.3 / 1.9.0可参考 libs.versions.toml。混淆规则SDK 发布时已内置 proguard-rules.pro内容为-keep class com.paddle.ocr.** { *; } -keep class ai.onnxruntime.** { *; }即保留 SDK 全部类与 ONNX Runtime 运行时类集成方在开启混淆时需确保该规则被引入否则运行时会因类被混淆而抛出ModelLoadFailed等异常。五、API 参考从创建实例到释放资源创建实例// 默认配置 val ocr PaddleOCR.create(context) // 自定义配置 val ocr PaddleOCR.create( context context, config PaddleOCRConfig( detThresh 0.3f, detBoxThresh 0.6f, recScoreThresh 0.0f, recBatchSize 1, ), engineConfig EngineConfig(numThreads 4), detModelAssetPath models/det/inference.onnx, recModelAssetPath models/rec/inference.onnx, recConfigAssetPath models/rec/inference.yml, )从源码看PaddleOCR.kt 提供了三个重载的create()create(context)使用默认配置快速创建create(context, config, engineConfig)自定义推理参数与线程数create(context, config, engineConfig, detModelAssetPath, recModelAssetPath, recConfigAssetPath)同时自定义模型资源路径适用于模型放在 assets 其他位置或多模型切换场景。create()内部在Dispatchers.IO上构建OCREngine期间会加载检测/识别两个 ONNX 模型并解析识别配置见 OCREngine.kt因此它是suspend 函数必须在协程中调用且首次调用耗时较长对应coldLoadTimeMs。执行 OCR// 传入 Bitmap val result ocr.recognize(bitmap) // 传入图片字节数据推荐与 Python 流程一致 val result ocr.recognize(imageBytes) // 读取结果 result.results.forEach { item - println(文本: ${item.text}, 置信度: ${item.confidence}) println(坐标: ${item.box.points}) } println(检测: ${result.detectionTimeMs}ms, 识别: ${result.recognitionTimeMs}ms)recognize()同样为 suspend 函数PaddleOCR.kt内部在Dispatchers.IO执行完整管线。字节数组入口recognize(imageBytes)会通过 OpenCV 的imdecode解码见 OCREngine.kt支持 JPEG/PNG 等常见格式且与 Python 端cv2.imread的 BGR 色彩空间处理流程一致官方推荐优先使用该入口。释放资源ocr.release()release()会依次关闭 ONNX Runtime 的识别会话、检测会话与环境见 ORTSessionManager.kt避免 native 内存泄漏。建议在 Activity/Fragment 销毁或应用退出时调用。配置参数详解data class PaddleOCRConfig( val detImgMode: String BGR, // 输入色彩模式 val detLimitSideLen: Int 64, // 检测侧边长限制 val detLimitType: String min, // 限制策略 val detMaxSideLimit: Int 4000, // 最长边上限 val detThresh: Float 0.3f, // 二值化阈值 val detBoxThresh: Float 0.6f, // 检测框置信度阈值 val detUnclipRatio: Float 1.5f, // 检测框扩展比例 val detMaxCandidates: Int 3000, // 最大候选框数 val detUseDilation: Boolean false, // 是否膨胀 val detScoreMode: String fast, // 打分模式 val detBoxType: String quad, // 检测框类型 val recScoreThresh: Float 0.0f, // 识别置信度阈值 val recBatchSize: Int 1, // 识别批大小 )结合源码这些参数的作用如下detImgMode输入色彩模式BGR与 Python 端 OpenCV 读取图像后的通道顺序一致。detLimitSideLen/detLimitType/detMaxSideLimit检测前图像缩放策略。detLimitSideLen64、detLimitTypemin表示以最短边为 64 为基准进行等比缩放更小的边长限制意味着更快的推理速度detMaxSideLimit4000约束最长边不超过 4000防止超大图导致显存/内存溢出。这三个参数直接传给 DetPreprocessor 控制输入尺寸。detThreshDBDifferentiable Binarization后处理的二值化阈值值越小越容易将低置信度像素判为文本区域。detBoxThresh检测框置信度阈值低于该值的候选框被过滤调高可减少误检框。detUnclipRatio检测框 Vatti clipping 扩展比例1.5 表示外扩 1.5 倍数值越大包围盒越宽松有助于包含完整文本但也会引入更多背景。detMaxCandidates最大候选框数量上限防止后处理阶段产生过多候选导致耗时激增。detUseDilation是否对分割结果做膨胀操作可增强细长文本的连通性。detScoreMode检测框打分模式fast/slow影响后处理精度与速度的取舍。detBoxType检测框类型quad四边形 /poly多边形。recScoreThresh识别置信度阈值低于该值的识别结果会被过滤见 OCREngine.kt 的过滤逻辑默认 0.0 表示不过滤。recBatchSize识别批大小。默认 1 时逐行识别内存占用低且可获得perLineRecMs逐行耗时调大可利用 ONNX Runtime 的 batch 推理提升吞吐但会增加内存与首帧延迟。在 OCREngine.kt 中检测框按阅读顺序分批送入识别引擎。这些参数的命名与取值与 Python 端 PP-OCR 的det_db_thresh、det_db_box_thresh、det_db_unclip_ratio等一一对应方便开发者将服务端调优经验直接迁移到移动端。推理线程配置data class EngineConfig( val numThreads: Int 4, )EngineConfig目前提供numThreads线程数配置默认 4。在 ORTSessionManager.kt 中它通过setIntraOpNumThreads(numThreads)设置 ONNX Runtime 会话的算子内线程数同时会话启用了OptLevel.ALL_OPT全量图优化。线程数需结合设备 CPU 核数实测调整线程过少导致算力闲置过多则引入线程调度开销。结果模型data class OCRRunResult( val results: ListOCRResult, // 识别结果列表 val detectionTimeMs: Long, // 检测耗时 val recognitionTimeMs: Long, // 识别耗时 val totalTimeMs: Long, // 总耗时 val lineCount: Int, // 识别行数 // 详细计时 val detPreprocessMs: Long, // 检测预处理耗时 val detInferenceMs: Long, // 检测推理耗时 val detPostprocessMs: Long, // 检测后处理耗时 val recPreprocessMs: Long, // 识别预处理耗时 val recInferenceMs: Long, // 识别推理耗时 val recPostprocessMs: Long, // 识别后处理耗时 val pipelineOverheadMs: Long, // 管线调度开销 val coldLoadTimeMs: Long, // 模型冷加载耗时 // 输入张量形状 val detInputShape: ListInt, // 检测输入形状 val recInputShapes: ListListInt,// 识别输入形状列表 // 逐行识别耗时仅 recBatchSize 1 时填充 val perLineRecMs: ListLong, ) data class OCRResult( val box: OCRBox, // 检测框坐标 val text: String, // 识别文本 val confidence: Float, // 置信度 )OCRRunResult.kt 中的字段由OCREngine.run()逐阶段累计得到OCREngine.kt。OCRBox提供检测框四边形的点坐标box.points可用于在图片上绘制框选、按坐标裁剪或与其他视觉模块联动perLineRecMs在recBatchSize 1时提供逐行耗时是分析长文本场景识别瓶颈的利器。六、性能测试自动化 Benchmark 方案项目提供了自动化性能测试脚本基于 Instrumentation 测试connectedAndroidTest在真实设备上运行可输出各阶段耗时的均值、标准差、P90 与最小值# 运行 benchmark10次测试3次预热 ./run_benchmark.sh 10 3从 run_benchmark.sh 源码可见脚本实际执行的是./gradlew :ppocr-sdk:connectedAndroidTest \ -Pandroid.testInstrumentationRunnerArguments.classcom.paddle.ocr.benchmark.OCRBenchmarkTest#testLatencyBenchmark \ -Pandroid.testInstrumentationRunnerArguments.warmup${WARMUP} \ -Pandroid.testInstrumentationRunnerArguments.iterations${ITERATIONS}即通过-P参数向OCRBenchmarkTest注入预热次数与迭代次数测试完成后从 logcat 中抓取OCRBenchmark标签的结果输出。测试固件与参考图片位于 ppocr-sdk/src/androidTest默认迭代 50 次、预热 30 次脚本内置默认值。输出示例╔═════════════════════════════════════════════════════════════════════════╗ ║ PP-OCRv6 Speed Benchmark Results ║ ╠═════════════════════════════════════════════════════════════════════════╣ ║ Device: GM1900 | OS: Android 9 | Lines: 5 ║ ║ Cold load: 158ms | Warmup: 3 | Measured: 10 ║ ╠═════════════════════════════════════════════════════════════════════════╣ --------------------------------------------------------------------- | Stage | Mean ms | Stdev | P90 | Min ms| --------------------------------------------------------------------- | Total pipeline | 420.40 | 6.37 | 427 | 413 | --------------------------------------------------------------------- | Detection (total) | 348.70 | 4.67 | 356 | 343 | | Preprocess | 33.30 | 2.90 | 36 | 28 | | Inference | 311.00 | 2.93 | 315 | 304 | | Postprocess | 4.40 | 0.49 | 5 | 4 | | Recognition (total) | 66.20 | 3.16 | 68 | 64 | | Preprocess | 3.00 | 0.89 | 4 | 2 | | Inference | 60.60 | 3.14 | 63 | 58 | | Postprocess | 2.60 | 0.92 | 4 | 1 | | Pipeline overhead | 5.50 | 0.50 | 6 | 5 | --------------------------------------------------------------------- ╚═════════════════════════════════════════════════════════════════════════╝上表为文档给出的参考输出特定设备 GM1900 上的实测结果。从数据分布可以明显看出检测推理Inference是整条流水线的主要耗时来源占比约 74%识别推理次之。这为性能优化提供了明确方向——例如通过降低detLimitSideLen缩小检测输入、增大recBatchSize批量识别或调整numThreads来针对性削减热点耗时。Benchmark 输出的每一行都与OCRRunResult中的计时字段一一对应开发者也可以在自己的测试中直接复用这些字段。七、注意事项与常见问题OpenCV 初始化调用PaddleOCR.create()前需先调用OpenCVUtils.init(context)完成 OpenCV 原生库加载否则图像编解码与 Mat 操作会失败。初始化代码位于 OpenCVUtils.ktDemo 中的OCRApplication.kt已示范了标准调用时机。协程调用create()和recognize()都是 suspend 函数需在协程作用域中调用。SDK 内部已切换至Dispatchers.IO因此业务侧可直接在viewModelScope.launch等场景中调用不会阻塞主线程。内存管理不再使用时调用release()释放 ONNX Runtime 会话与 native 资源。检测/识别过程中产生的 OpenCVMat对象图像、裁剪区域均在 finally 块中主动release()见 OCREngine.kt避免 native 内存泄漏。混淆规则开启 R8/ProGuard 时须引入 proguard-rules.pro保留com.paddle.ocr.**与ai.onnxruntime.**类。模型文件缺失若 assets 中未正确放置模型create()会抛出ModelNotFound错误见 ORTSessionManager.kt请检查models/det/与models/rec/目录是否齐全。空检测结果当图片中检测不到文本区域时recognize()返回空results列表且recognitionTimeMs为 0见 OCREngine.kt业务层需对空结果做兜底处理。八、从 Demo 到生产架构与扩展建议从 PaddleOCR.kt 与 OCREngine.kt 的实现可以总结出整套移动端 OCR 流水线的数据流输入Bitmap或图片字节数组 → OpenCV 解码为 BGRMat检测DetPreprocessor缩放归一化 → ONNX Runtime 检测会话推理 →DBPostProcessor后处理得到候选文本框OCRBox并经过BoxSorter按阅读顺序排序裁剪QuadTextCrop按检测框透视裁剪文本区域识别RecPreprocessor批量预处理 → 识别会话推理 →CTCDecoder结合字符表 CTC 解码得到文本与置信度过滤与输出按recScoreThresh过滤低置信度结果汇总各阶段耗时返回OCRRunResult。理解这条数据流后你可以基于 SDK 做以下扩展多语言识别替换models/rec/inference.yml中的字符表与对应识别模型即可切换语言无需改动任何业务代码检测框可视化利用OCRResult.box.points在 Bitmap 上绘制四边形实现类似 Demo 中的框选效果业务化封装将PaddleOCR实例封装为单例并在 Application 层初始化一次避免多次create()带来的冷加载开销性能监控复用OCRRunResult的逐阶段耗时字段接入自有 APM 体系在线上持续观测不同设备的推理表现。九、总结deploy/ppocr-android为 PaddleOCR 在 Android 平台的落地提供了一个开箱即用的完整方案SDK/Demo 分离架构降低了集成门槛ONNX Runtime 保证了推理性能与跨平台性逐阶段计时与 Benchmark 脚本让性能调优有据可依。本文所述的模型放置、Gradle 编译、两种集成方式、API 参数与性能测试方法均可直接迁移到实际项目中。进一步地你可以在 android_deployment.md 获取官方部署文档原文并结合 PP-OCRv6 检测配置、PP-OCRv6 识别配置 中的模型定义理解移动端模型的出处或在 benchmark 目录了解检测模型的训练与评估细节。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考