为 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 环境变量设置为指向它
    • 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"
    • 这将安装到我们顶级目录的“platforms”目录中，即我们示例中的 Android 目录
    • 在构建时用作 --android_sdk_path 的 SDK 路径是此顶级目录
  • 安装 NDK
    • 通过运行 sdkmanager --list 查找可用的 NDK 版本
    • 安装
      • 安装所需的版本，例如，sdkmanager --install "ndk;<NDK version>"
      • 在我们示例中，使用此安装的 NDK 路径将是 .../Android/ndk/<NDK version>

Android 构建说明

在 Windows 上交叉编译

需要使用 Ninja 生成器在 Windows 上进行构建，因为 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)

通过使用上述构建命令和 --build_java，Android 归档文件 (AAR) 文件（可以直接在 Android Studio 中导入）将在 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 使用者，目前您需要在 Android 项目内的 proguard-rules.pro 文件中添加以下行以使用软件包 com.microsoft.onnxruntime:onnxruntime-android，以避免运行时崩溃

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

*类似问题的参考

在 protobuf Github 项目和 R8 上有类似的未解决问题。

Android NNAPI 执行提供程序

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

构建说明

可以使用 Android 构建说明中的构建命令和 --use_nnapi 构建 Android 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 包的部分。