如何从源码构建MakeACopy:算子裁剪版ONNX Runtime的Android编译与CI发布流程完整指南
如何从源码构建MakeACopy:算子裁剪版ONNX Runtime的Android编译与CI发布流程完整指南
MakeACopy 是一款开源、完全离线的 Android 文档扫描应用,内置 OCR 识别与可搜索 PDF 导出功能。本文带你从源码构建 MakeACopy:详解算子裁剪版 ONNX Runtime 的 Android 编译方法、Gradle 打包步骤,以及 CI 自动签名与发布流程,帮助你完整复现官方 Release 构建。
一、MakeACopy 是什么:离线扫描 + 本地 OCR
MakeACopy 的核心卖点只有四个字:全程离线。它把所有 OCR 语言模型、字体和图像处理组件直接打包进应用内部,不依赖任何云服务,也不收集任何遥测数据。
主要功能包括:
- 📷 相机扫描:基于自训练的 DocQuad 角点检测模型(ONNX)自动识别文档边缘,并吸附到页面边缘
- 🖼️ 透视校正与去畸变:如仓库根目录的去畸变测试样本所示,弯曲的纸面也能被拉直处理
- ✍️ OCR 识别:PaddleOCR V5 离线识别,支持拉丁、中文、阿拉伯、泰文、希腊文等语言组
- 📄 导出:生成带隐藏文本层的可搜索 PDF 或高质量 JPEG
- 📥 Inbox 模式:扫描件自动存入指定文件夹,配合 SambaLite、paperless-ngx 等实现自托管文档流
💡 应用体积约 100 MB(Full 版 arm64 约 108 MB)不是臃肿,而是离线一致性的代价——OCR 模型和字体全部本地内置。
二、构建全景:整个仓库只编译一个原生库
这是从源码构建 MakeACopy 最让人意外的一点:项目里唯一的原生组件就是 ONNX Runtime。
- 图像处理(透视校正、去畸变、黑白增强)全部是纯 Java 实现,不需要 OpenCV
- ONNX Runtime 是文档角点检测(DocQuad)和 PaddleOCR 推理的唯一运行时
- 仓库中不存放任何预编译二进制,全部从
external/onnxruntime子模块(v1.24.1)源码构建——这正是它保持 F-Droid 兼容的关键
上图就是仓库内置的双栏评测样本,应用需要正确识别这类版式
什么是"算子裁剪版"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
这个 构建脚本 内部做了这些事:
- 可复现性准备:固定
SOURCE_DATE_EPOCH=1700000000、TZ=UTC,编译时加上-fdebug-prefix-map和--build-id=none,让不同机器产出字节级一致的产物 - 清理并复制源码:把
external/onnxruntime子模块复制到一个稳定路径(/tmp/onnxruntime-src),并应用 external/onnxruntime_pinned/ 中固定的 Gradle 构建文件与 wrapper 版本 - 选择 CMake ≥ 3.28:优先使用 Android SDK 自带版本,找不到则报错提示设置
ORT_CMAKE - 合并算子配置:把 DocQuad + PaddleOCR 两份配置合并为一份,传入
--include_ops_by_config - 逐 ABI 编译(默认
arm64-v8a armeabi-v7a x86 x86_64):C++ 共享库 + Java 绑定,关闭 Python/CSharp/测试等一切无关产物 - 拷贝产物到应用工程:
app/src/main/jniLibs/<ABI>/libonnxruntime.soapp/src/main/jniLibs/<ABI>/libonnxruntime4j_jni.soapp/libs/onnxruntime-1.24.1.jar
- 用 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 的关键步骤(顺序执行):
- 递归检出子模块(
submodules: recursive) - 安装 JDK 21 Temurin、NDK 28.0.13004108、CMake 3.31.6、Python 3.11.2(含
flatbuffers依赖) - 写入确定性环境变量:
SOURCE_DATE_EPOCH、TZ=UTC、LC_ALL=C、PYTHONHASHSEED=0 - 运行
scripts/build_onnxruntime_android.sh编译原生库 - 代码质量检查:
compileDebugJavaWithJavac+ 单元测试 + Lint - 仅 tag 构建:从 secrets 解码 base64 格式的 keystore 并签名(缺少签名密钥会直接让 tag 构建失败,"tag 不许产出未签名 Release")
- 运行
:app:verifyNoTestDataInApk门禁,防止测试数据混入发布包 - 产物统一重命名为
MakeACopy-v<版本>-<abi>-release.apk与MakeACopy-v<版本>-release.aab - 用
apksigner verify验签,并逐个检查每个 ABI 分片里确实包含libonnxruntime.so - 为每个产物生成
.sha256校验和文件 - 从
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。
七、质量门禁与合规检查
发布流程之外,还有三道"守门员":
- 测试数据泄漏检查:
:app:verifyNoTestDataInApk确保像下面这类合成评测数据(位于app/src/androidTest/assets/)绝不出现在 Release APK 中
-
签名验证:所有官方 Release 均使用固定证书签名,用户可自行核验:
apksigner verify --print-certs MakeACopy-vX.Y.Z.apk -
许可证合规: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 背后的签名、校验和与合规检查是怎么完成的。



