如何从源码构建MakeACopy:算子裁剪版ONNX Runtime的Android编译与CI发布流程完整指南

原创2026-11-15 15:18:592,174 阅读

如何从源码构建MakeACopy:算子裁剪版ONNX Runtime的Android编译与CI发布流程完整指南

MakeACopy 是一款开源、完全离线的 Android 文档扫描应用,内置 OCR 识别与可搜索 PDF 导出功能。本文带你从源码构建 MakeACopy:详解算子裁剪版 ONNX Runtime 的 Android 编译方法、Gradle 打包步骤,以及 CI 自动签名与发布流程,帮助你完整复现官方 Release 构建。

一、MakeACopy 是什么:离线扫描 + 本地 OCR

MakeACopy 的核心卖点只有四个字:全程离线。它把所有 OCR 语言模型、字体和图像处理组件直接打包进应用内部,不依赖任何云服务,也不收集任何遥测数据。

MakeACopy 开源离线文档扫描应用

主要功能包括:

  • 📷 相机扫描:基于自训练的 DocQuad 角点检测模型(ONNX)自动识别文档边缘,并吸附到页面边缘
  • 🖼️ 透视校正与去畸变:如仓库根目录的去畸变测试样本所示,弯曲的纸面也能被拉直处理
  • ✍️ OCR 识别:PaddleOCR V5 离线识别,支持拉丁、中文、阿拉伯、泰文、希腊文等语言组
  • 📄 导出:生成带隐藏文本层的可搜索 PDF 或高质量 JPEG
  • 📥 Inbox 模式:扫描件自动存入指定文件夹,配合 SambaLite、paperless-ngx 等实现自托管文档流

💡 应用体积约 100 MB(Full 版 arm64 约 108 MB)不是臃肿,而是离线一致性的代价——OCR 模型和字体全部本地内置。

MakeACopy 文档去畸变处理测试样本

二、构建全景:整个仓库只编译一个原生库

这是从源码构建 MakeACopy 最让人意外的一点:项目里唯一的原生组件就是 ONNX Runtime。

  • 图像处理(透视校正、去畸变、黑白增强)全部是纯 Java 实现,不需要 OpenCV
  • ONNX Runtime 是文档角点检测(DocQuad)和 PaddleOCR 推理的唯一运行时
  • 仓库中不存放任何预编译二进制,全部从 external/onnxruntime 子模块(v1.24.1)源码构建——这正是它保持 F-Droid 兼容的关键

MakeACopy 双栏文档 OCR 评测样本页

上图就是仓库内置的双栏评测样本,应用需要正确识别这类版式

什么是"算子裁剪版"ONNX Runtime

完整 ONNX Runtime 包含数百个推理算子,而 MakeACopy 只需要其中很小一部分。构建脚本采用 minimal build(--minimal_build extended) 机制,通过 --include_ops_by_config 只保留应用实际用到的算子:

算子配置来源 文件 说明
DocQuad 角点检测 docquadnet256_trained_opset17.required_operators.config 必需
PaddleOCR V5 paddleocr_v5.required_operators.config 默认可选

两个配置会被脚本用 awk 自动合并成一份"去重后的算子白名单"(相同 domain;opset 的行取并集),从而显著缩小 libonnxruntime.so 的体积和构建时间。

另外,构建默认只启用 CPU 执行提供器。实测数据(Pixel 7a)表明:NNAPI 反而慢约 12 倍、XNNPACK 没有收益,所以默认不编译它们——需要时可加回(见下文环境变量)。

三、环境准备:与 CI 对齐的四个版本

为了保证"本地构建 = CI 构建",所有工具版本都与 build-release.yml 工作流保持一致(CONTRIBUTING.md 也强调了对齐原则):

工具 版本 用途
JDK 21(Temurin) Gradle 构建
Android NDK 28.0.13004108 交叉编译原生库
CMake 3.31.6 与 F-Droid 环境一致
Python 3.11.2 ONNX Runtime 构建脚本的解释器
Android SDK compileSdk 36 / minSdk 29 应用构建

首先克隆仓库(包含子模块):

git clone --recurse-submodules https://gitcode.com/gh_mirrors/mak/makeacopy
cd makeacopy

四、一键编译算子裁剪版 ONNX Runtime

一切交给官方脚本:

./scripts/build_onnxruntime_android.sh

这个 构建脚本 内部做了这些事:

  1. 可复现性准备:固定 SOURCE_DATE_EPOCH=1700000000、TZ=UTC,编译时加上 -fdebug-prefix-map 和 --build-id=none,让不同机器产出字节级一致的产物
  2. 清理并复制源码:把 external/onnxruntime 子模块复制到一个稳定路径(/tmp/onnxruntime-src),并应用 external/onnxruntime_pinned/ 中固定的 Gradle 构建文件与 wrapper 版本
  3. 选择 CMake ≥ 3.28:优先使用 Android SDK 自带版本,找不到则报错提示设置 ORT_CMAKE
  4. 合并算子配置:把 DocQuad + PaddleOCR 两份配置合并为一份,传入 --include_ops_by_config
  5. 逐 ABI 编译(默认 arm64-v8a armeabi-v7a x86 x86_64):C++ 共享库 + Java 绑定,关闭 Python/CSharp/测试等一切无关产物
  6. 拷贝产物到应用工程:
    • app/src/main/jniLibs/<ABI>/libonnxruntime.so
    • app/src/main/jniLibs/<ABI>/libonnxruntime4j_jni.so
    • app/libs/onnxruntime-1.24.1.jar
  7. 用 NDK 的 llvm-strip 剥离开关不需要的调试段

常用环境变量(脚本头部均有注释):

# 只编一个 ABI、安静日志、详细输出
ABIS=arm64-v8a ./scripts/build_onnxruntime_android.sh

# 关闭算子裁剪(全量 ONNX Runtime)
ORT_OPS_CONFIG=none ./scripts/build_onnxruntime_android.sh

# 排除 PaddleOCR 算子;加回 XNNPACK/NNAPI 做性能对比
INCLUDE_PADDLE_OPS=0 ./scripts/build_onnxruntime_android.sh
ORT_USE_XNNPACK=1 ORT_USE_NNAPI=1 ./scripts/build_onnxruntime_android.sh

# 调试
VERBOSE=1 DEBUG=1 ./scripts/build_onnxruntime_android.sh

五、用 Gradle 打包 Full 与 Light 两个版本

原生库就位后,应用本体就是标准 Gradle 构建:

# Full 版(默认,全语言 OCR)
./gradlew :app:assembleRelease -PenableAbiSplits=true

# Light 版(仅拉丁文,约 42 MB)
./gradlew :app:assembleRelease -PenableAbiSplits=true -Pedition=light
版本 OCR 语言 arm64-v8a 体积 应用 ID
Full 全部 PaddleOCR 语言组 ~108 MB de.schliweb.makeacopy
Light 仅拉丁文 ~42 MB de.schliweb.makeacopy.light

两个版本共用同一套 DocQuad 检测模型与算子裁剪版 ONNX Runtime,区别只在打包的 OCR 识别模型。Light 版通过 applicationIdSuffix ".light" 实现与 Full 版并排安装。产物位于 app/build/outputs/apk/release/app-<abi>-release.apk。

六、CI 发布流程拆解:从 push 到正式 Release

所有自动化构建都由 build-release.yml 一个工作流完成,包含 build(Full)与 build-light 两个 job:

触发事件 行为
push / PR 到 main 构建未签名的 Release AAB 与分 ABI APK,作为 workflow artifact 供下载
推送 vX.Y.Z 开头的 tag 解码 keystore → 签名构建 → 验签 → 校验和 → 创建 Release 并附带全部产物

Full build job 的关键步骤(顺序执行):

  1. 递归检出子模块(submodules: recursive)
  2. 安装 JDK 21 Temurin、NDK 28.0.13004108、CMake 3.31.6、Python 3.11.2(含 flatbuffers 依赖)
  3. 写入确定性环境变量:SOURCE_DATE_EPOCH、TZ=UTC、LC_ALL=C、PYTHONHASHSEED=0
  4. 运行 scripts/build_onnxruntime_android.sh 编译原生库
  5. 代码质量检查:compileDebugJavaWithJavac + 单元测试 + Lint
  6. 仅 tag 构建:从 secrets 解码 base64 格式的 keystore 并签名(缺少签名密钥会直接让 tag 构建失败,"tag 不许产出未签名 Release")
  7. 运行 :app:verifyNoTestDataInApk 门禁,防止测试数据混入发布包
  8. 产物统一重命名为 MakeACopy-v<版本>-<abi>-release.apk 与 MakeACopy-v<版本>-release.aab
  9. 用 apksigner verify 验签,并逐个检查每个 ABI 分片里确实包含 libonnxruntime.so
  10. 为每个产物生成 .sha256 校验和文件
  11. 从 fastlane/metadata/android/en-US/changelogs/<versionCode>.txt 读取发布说明,创建 Release 并上传 Full 与 Light 的全部 APK/AAB 及校验和

build-light job 依赖 Full job:直接下载其产出的 native-libs artifact(jniLibs + JAR),省去原生编译,只用 JDK 21 执行 -Pedition=light 打包,产物命名为 MakeACopy-Light-v<版本>-<abi>-release.apk。

关于版本号有个细节:由于按 ABI 拆分 versionCode,规则是 versionCode = 基础值 × 10 + ABI 后缀(如 1.2.0 的基础值 10200 会生成 102001~102004 四个编号,后缀 1~4 分别对应 armeabi-v7a / arm64-v8a / x86 / x86_64)。因此每个 ABI 编号都需要独立的 changelog 文件,详见 fastlane/README.md。

七、质量门禁与合规检查

发布流程之外,还有三道"守门员":

  1. 测试数据泄漏检查::app:verifyNoTestDataInApk 确保像下面这类合成评测数据(位于 app/src/androidTest/assets/)绝不出现在 Release APK 中

MakeACopy OCR 合成多栏测试数据样本

  1. 签名验证:所有官方 Release 均使用固定证书签名,用户可自行核验:

    apksigner verify --print-certs MakeACopy-vX.Y.Z.apk
    
  2. 许可证合规:ort-compliance.yml 在每次 push/PR 时运行 OSS Review Toolkit(固定版本 97.2.0,配置见 ort/config/config.yml)与 ScanCode 双重扫描,报告通过 scripts/run-ort.sh 和 scripts/run-scancode.sh 生成,依赖清单与第三方许可文本见 third_party_licenses/ 和 NOTICE。

八、常见问题与排查

症状 原因与解决
ERROR: CMake < 3.28.0 脚本要求 CMake ≥ 3.28,安装 SDK 自带 CMake 3.31+ 或设置 ORT_CMAKE=/path/to/cmake
ERROR: ANDROID_NDK_HOME not set 安装 NDK 28.0.13004108 并设置 ANDROID_NDK_HOME,脚本也会自动在常见路径探测最新版本
构建太慢 全量 4 个 ABI 编译耗时较长,可设 ABIS=arm64-v8a 只编主架构;JOBS=<n> 控制并行度
想对比执行提供器性能 ORT_USE_XNNPACK=1 ORT_USE_NNAPI=1 重新构建,默认关闭是因为实测无收益
产物不一致 检查是否沿用了脚本内置的 SOURCE_DATE_EPOCH/TZ 等确定性设置,不要手动覆盖

九、关键文件速查

内容 路径
ONNX Runtime 构建脚本 scripts/build_onnxruntime_android.sh
DocQuad 算子白名单 docquadnet256_trained_opset17.required_operators.config
PaddleOCR V5 算子白名单 paddleocr_v5.required_operators.config
固定的 Gradle 构建文件 external/onnxruntime_pinned/
CI 发布工作流 .github/workflows/build-release.yml
许可证合规工作流 .github/workflows/ort-compliance.yml
versionCode 与 changelog 规则 fastlane/README.md
开发环境指南 CONTRIBUTING.md
评测方法说明 training/EVALUATION.md

总结

从源码构建 MakeACopy 的思路可以概括为三步:环境对齐 → 一键编译算子裁剪版 ONNX Runtime → Gradle 打包。整个项目只编译一个原生库,且通过算子白名单、固定工具链版本与可复现构建参数,保证了本地、CI 与 F-Droid 三方产物的一致。理解 build-release.yml 后,你不仅能自己打包,还能清楚知道每一个正式发布 APK 背后的签名、校验和与合规检查是怎么完成的。

登录后查看全文
makeacopy