為 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/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 包的部分。