为 Android 构建 ONNX Runtime

按照以下说明为 Android 构建 ONNX Runtime。

目录

先决条件

SDK 和 NDK 包可以通过 Android Studio 或 sdkmanager 命令行工具安装。

Android Studio 更方便，但安装包较大。命令行工具更小，可以脚本化使用，但设置起来稍微复杂一些。它们还需要可用的 Java 运行时环境。

通常，您会希望使用最新的稳定版 NDK。从现在开始，我们将您使用的版本称为 <NDK version>。

资源

Android Studio

  1. 安装 Android Studio

  2. 如有必要，安装任何额外的 SDK 平台

    • 文件->设置->外观与行为->系统设置->Android SDK 查看当前已安装的内容
    • 请注意，构建 ORT 时需要用作 --android_sdk_path 的 SDK 路径也在此配置页面上
    • 您很可能不需要额外的 SDK 平台包，因为最新的平台可以面向更早的 API 级别。

  3. 安装 NDK 版本

    • 文件->设置->外观与行为->系统设置->Android SDK
    • “SDK 工具”选项卡
      • 勾选底部的“显示包详细信息”复选框以查看特定版本。默认情况下会安装最新版本，这应该没有问题。
    • NDK 路径将是所示 SDK 路径的 ndk/<NDK version> 子目录

命令行工具中的 sdkmanager

  • 如有必要，安装 Java 运行时环境并设置 JAVA_HOME 环境变量指向它
  • 为了使 sdkmanager 工作，它需要特定的目录结构。首先为 Android 基础结构创建顶层目录。
    • 在我们的示例中，我们称之为 .../Android/
  • 从 https://developer.android.com.cn/studio 页面底部的“仅命令行工具”部分下载命令行工具
  • 在您的顶层目录下创建一个名为“cmdline-tools”的目录
    • 即 .../Android/cmdline-tools
  • 将命令行工具 zip 文件中的“tools”目录解压到此目录中
  • 现在您应该能够成功运行 Android/cmdline-tools/bin/sdkmanager[.bat]
    • 如果您看到有关无法保存设置和 sdkmanager 帮助文本的错误，则您的目录结构不正确。
    • 请查看此答案中的最后步骤进行双重检查：https://stackoverflow.com/a/61176718

  • 运行 .../Android/cmdline-tools/bin/sdkmanager --list 以查看可用包

  • 安装 SDK 平台

    • 通常安装最新版本即可。您在编译代码时选择一个 API 级别，最新的平台将支持许多较新的 API 级别，例如：

      sdkmanager --install "platforms;android-29"
    • 这将被安装到我们顶层目录（在我们的示例中为 Android 目录）的“platforms”目录中
    • 构建时用作 --android_sdk_path 的 SDK 路径就是这个顶层目录
  • 安装 NDK
    • 通过运行 sdkmanager --list 查找可用的 NDK 版本
    • 安装
      • 安装所需版本，例如 sdkmanager --install "ndk;<NDK version>"
      • 在我们的示例中，通过此安装，NDK 路径将是 .../Android/ndk/<NDK version>

Android 构建说明

在 Windows 上交叉编译

在 Windows 上构建时需要使用 Ninja 生成器，因为 Visual Studio 生成器不支持 Android。

./build.bat --android --android_sdk_path <android sdk path> --android_ndk_path <android ndk path> --android_abi <android abi, e.g., arm64-v8a (default) or armeabi-v7a> --android_api <android api level, e.g., 27 (default)> --cmake_generator Ninja

例如，使用我们示例中的路径

./build.bat --android --android_sdk_path .../Android --android_ndk_path .../Android/ndk/<NDK version> --android_abi arm64-v8a --android_api 27 --cmake_generator Ninja

在 Linux 和 macOS 上交叉编译

./build.sh --android --android_sdk_path <android sdk path> --android_ndk_path <android ndk path> --android_abi <android abi, e.g., arm64-v8a (default) or armeabi-v7a> --android_api <android api level, e.g., 27 (default)>

构建 Android 归档文件 (AAR)

Android 归档文件 (AAR) 将在 your_build_dir/java/build/android/outputs/aar 中生成，这些文件可以直接导入 Android Studio，通过使用上述构建命令并加上 --build_java。

要在 Windows 上启用 --build_java 进行构建，您还必须

  • 将 JAVA_HOME 设置为您的 JDK 安装路径
    • 这可以是 Android Studio 中的 JDK，也可以是独立的 JDK 安装
    • 例如 Powershell: $env:JAVA_HOME="C:\Program Files\Java\jdk-15" CMD: set JAVA_HOME=C:\Program Files\Java\jdk-15
  • 从管理员窗口运行构建
    • Java 构建需要创建符号链接的权限，这需要管理员窗口

注意：R8 最小化 Android 应用构建所需的 Proguard 规则

对于使用 R8 最小化构建的 Android 库消费者，目前您需要在 Android 项目的 proguard-rules.pro 文件中添加以下行，以使用包 com.microsoft.onnxruntime:onnxruntime-android，从而避免运行时崩溃

-keep class ai.onnxruntime.** { *; }

*类似问题的参考

在 protobuf Github 项目 和 R8 上有类似的开放问题。

Android NNAPI 执行提供程序

如果您想在 Android 上使用 NNAPI 执行提供程序，请参阅NNAPI 执行提供程序。

构建说明

Android NNAPI 执行提供程序可以使用 Android 构建说明中的构建命令并加上 --use_nnapi 进行构建。

QNN 执行提供程序

如果您的设备具有受支持的高通骁龙 SOC，并且您想在 Android 上使用 QNN 执行提供程序，请参阅QNN 执行提供程序。

构建说明

下载并安装 Qualcomm AI Engine Direct SDK。QNN 执行提供程序可以使用 Android 构建说明中的构建命令并加上 --use_qnn static_lib --qnn_home [QNN_SDK path] 进行构建。

使用模拟器测试 Android 更改（不适用于 QNN 执行提供程序）

请参阅使用模拟器测试 Android 更改。

构建自定义 Android 包

请参阅有关自定义构建的文档。特别是，请参阅有关Android 包的部分。