构建 ONNX Runtime for Android

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

目录

先决条件

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 环境变量指向它。
    • https://www.java.com/en/download/
    • Windows 注意事项：您必须安装 64 位版本 (https://www.java.com/en/download/manual.jsp)，否则 sdkmanager 将只列出 x86 包，而最新的 NDK 仅支持 x64。
  • 为了使 sdkmanager 工作，它需要特定的目录结构。首先创建 Android 基础设施的顶级目录。
    • 在我们的示例中，我们将称之为 .../Android/
  • 从 https://developer.android.com.cn/studio 页面底部“仅命令行工具”部分下载命令行工具。
  • 在您的顶级目录下创建一个名为“cmdline-tools”的目录。
    • 得到 .../Android/cmdline-tools
  • 将命令行工具 zip 文件中的“tools”目录提取到此目录中。
    • 得到 .../Android/cmdline-tools/tools
    • Windows 注意事项：最好使用 7-zip 进行提取。如果使用 Windows 内置的 zip 提取工具，您需要通过将 jar 文件从 tools\lib\_ 移动到 tools\lib 来修复目录结构。
      • 参考 https://stackoverflow.com/questions/27364963/could-not-find-or-load-main-class-com-android-sdkmanager-main
  • 现在您应该能够成功运行 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 Archive (AAR)

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

若要在 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 项目中的 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 执行提供程序

如果您的设备有支持的 Qualcomm Snapdragon 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 包的部分。