構建自定義 ONNX Runtime 包

當目標環境需要時，ONNX Runtime 包可以進行自定義。

自定義 ONNX Runtime 構建最常見的場景是為了更小佔用空間的部署，例如移動和 Web。

而最常見的自定義構建機制是減少執行時支援的運算子集合，只保留目標環境中模型或模型所需的那些。

要構建自定義 ONNX Runtime 包，從原始碼構建的說明適用，並附帶以下指定的一些額外選項。

目錄

精簡運算子核心

為了減小 ONNX Runtime 編譯二進位制檔案的大小，構建中包含的運算子核心可以精簡到只包含您的模型所需的那些。

包含的運算子在構建時指定，位於可以從一個或一組模型生成的配置檔案中。

精簡構建至所需運算子核心的構建選項

--include_ops_by_config

  • 將 --include_ops_by_config <模型轉換期間生成的配置檔案> --skip_tests 新增到構建引數中。

  • 注意：構建將編輯一些 ONNX Runtime 原始檔以排除未使用的核心。

    特別是，此源修改將在“更新”構建階段完成，該階段預設啟用或透過 --update 構建引數明確啟用。

    ONNX Runtime 1.10 及更早版本： 原始檔被直接修改。如果您希望返回建立完整構建，或者希望更改包含的運算子核心，則必須從本地 ONNX Runtime 倉庫的根目錄執行 git reset --hard 或 git checkout HEAD -- ./onnxruntime/core/providers 以撤消這些更改。

    ONNX Runtime 1.11 及更高版本： 更新版本的原始檔在構建目錄中生成，因此無需撤消原始檔更改。

精簡所需運算子支援的型別的選項

--enable_reduced_operator_type_support

  • 啟用運算子型別精簡。需要 ONNX Runtime 1.7 或更高版本，並且在模型轉換期間已啟用型別精簡。

如果使用 ORT 格式模型建立配置檔案，則在指定 --enable_type_reduction 時可以跟蹤單個運算子所需的輸入/輸出型別。如果在構建 ORT 時指定 --enable_reduced_operator_type_support，這可以進一步減小構建大小。

ONNX 格式模型不保證包含所需的每個節點型別資訊，因此不能與此選項一起使用。

最小構建

ONNX Runtime 可以進一步最小化二進位制檔案大小。這些減小大小的構建被稱為最小構建，下面描述了不同的最小構建級別。

基本

--minimal_build

除非啟用 Python 繫結 (--build_wheel)，否則此構建中預設停用 RTTI。

基本的最小構建有以下限制：

  • 不支援 ONNX 格式模型。模型必須轉換為ORT 格式。
  • 不支援執行時最佳化。最佳化在轉換為 ORT 格式期間執行。
  • 僅支援靜態註冊核心的執行提供程式（例如 ONNX Runtime CPU 執行提供程式）。

擴充套件

--minimal_build extended

擴充套件的最小構建比基本的最小構建支援更多功能：

  • 有限支援執行時分割槽（將模型中的節點分配給特定的執行提供程式）。
  • 額外支援編譯核心的執行提供程式，例如 NNAPI 和 CoreML。
  • ONNX Runtime 1.11 及更高版本：透過儲存的執行時最佳化和一些在執行時啟用的圖最佳化器，有限支援執行時最佳化。

其他自定義

停用異常

--disable_exceptions

  • 任何本應丟擲異常的位置將改為記錄錯誤訊息並呼叫 abort()。
  • 需要 --minimal_build。
  • 注意：如果您需要 Python 繫結 (--build_wheel)，這不是一個有效的選項，因為 Python Wheel 要求啟用異常。
  • 異常僅在 ONNX Runtime 中用於特殊情況。如果您已驗證要使用的輸入，並驗證了模型可以載入，那麼除非存在系統級問題（例如記憶體不足），否則 ORT 不太可能丟擲異常。

停用 ML 運算子支援

--disable_ml_ops

  • 雖然運算子核心精簡指令碼停用了所有未使用的 ML 運算子核心，但透過移除對 ML 特定型別的支援可以實現額外的節省。如果您知道您的模型沒有 ML ops，或者沒有使用 Map 型別的 ML ops，則可以提供此標誌。
  • 如果不確定，請參閱 ONNX ML 運算子的規範。

在 Android 上使用共享 libc++

--android_cpp_shared

  • 使用共享 libc++ 庫而不是預設的靜態 libc++ 庫進行構建，會生成更小的 libonnxruntime.so 庫。
  • 有關更多資訊，請參閱 Android NDK 文件。

構建配置

--config

MinSizeRel 配置將產生最小的二進位制檔案大小。

如果您希望優先考慮效能而不是二進位制檔案大小，也可以使用 Release 配置。

要構建的 ONNX Runtime 版本

除非您需要特定功能，否則請勿使用未釋出的 main 分支。

克隆 ONNX Runtime 倉庫後，簽出其中一個釋出標籤以進行構建。

git clone --recursive https://github.com/microsoft/onnxruntime
cd onnxruntime
git checkout <release tag>

釋出標籤名稱遵循 v<release version> 模式。例如，v1.13.1。在此處查詢。

構建命令示例

在 Windows 上構建，支援精簡運算子，且僅支援 ORT 格式模型

<ONNX Runtime repository root>\build.bat ^
  --config=Release ^
  --cmake_generator="Visual Studio 16 2019" ^
  --build_shared_lib ^
  --minimal_build ^
  --disable_ml_ops --disable_exceptions --disable_rtti ^
  --include_ops_by_config <config file from model conversion> --enable_reduced_operator_type_support ^
  --skip_tests

Linux

<ONNX Runtime repository root>/build.sh \
  --config=Release \
  --build_shared_lib \
  --minimal_build \
  --disable_ml_ops --disable_exceptions --disable_rtti \
  --include_ops_by_config <config file from model conversion> --enable_reduced_operator_type_support \
  --skip_tests

自定義構建包

在本節中，ops.config 是一個配置檔案，指定要包含的操作集、運算子核心和型別。

Web

[本節即將推出]

iOS

要為 iOS 構建生成 pods，請使用 ONNX Runtime 倉庫中的 build_and_assemble_apple_pods.py 指令碼。

  1. 簽出您要使用的 ONNX Runtime 版本。

  2. 執行構建指令碼。

    例如：

     python3 tools/ci_build/github/apple/build_and_assemble_apple_pods.py \
   --staging-dir /path/to/staging/dir \
   --include-ops-by-config /path/to/ops.config \
   --build-settings-file /path/to/build_settings.json

    這將執行自定義構建並在 /path/to/staging/dir 中建立 pod 包檔案。

    構建選項透過提供給 --build-settings-file 選項的檔案指定。請參閱 tools/ci_build/github/apple/default_full_apple_framework_build_settings.json 中預構建包使用的當前構建選項。您可以直接使用此檔案。

    自定義構建中精簡的操作集透過提供給 --include_ops_by_config 選項的配置檔案指定。這是可選的。

    預設包不包含訓練 API。要建立訓練包，請在提供給 --build-settings-file 的構建選項檔案中新增 --enable_training_apis，並在呼叫 build_and_assemble_apple_pods.py 時新增 --variant Training 選項。

    例如：

     # /path/to/build_settings.json is a file that includes the `--enable_training_apis` option
    
 python3 tools/ci_build/github/apple/build_and_assemble_apple_pods.py \
   --staging-dir /path/to/staging/dir \
   --include-ops-by-config /path/to/ops.config \
   --build-settings-file /path/to/build_settings.json \
   --variant Training

  3. 使用本地 pods。

    例如，更新 Podfile 以使用本地 onnxruntime-objc pod 而不是已釋出的 pod

     -  pod 'onnxruntime-objc'
 +  pod 'onnxruntime-objc', :path => "/path/to/staging/dir/onnxruntime-objc"
 +  pod 'onnxruntime-c', :path => "/path/to/staging/dir/onnxruntime-c"

    注意：onnxruntime-objc pod 依賴於 onnxruntime-c pod。如果使用已釋出的 onnxruntime-objc pod，此依賴項會自動處理。但是，如果使用本地 onnxruntime-objc pod，則其依賴的本地 onnxruntime-c pod 也需要在 Podfile 中指定。

Android

要生成 Android AAR 包，請使用 ONNX Runtime 倉庫中的 build_custom_android_package.py 指令碼。

該指令碼可以在倉庫內部或外部使用。將其包含目錄複製到倉庫外部使用。

注意：在以下步驟中，將 <ORT version> 替換為您要使用的 ONNX Runtime 版本，例如 1.13.1。

  1. 執行構建指令碼。

    例如：

     python3 tools/android_custom_build/build_custom_android_package.py \
   --onnxruntime_branch_or_tag v<ORT version> \
   --include_ops_by_config /path/to/ops.config \
   --build_settings /path/to/build_settings.json \
   /path/to/working/dir

    這將執行自定義構建並在 /path/to/working/dir 中建立 Android AAR 包。

    使用 --onnxruntime_branch_or_tag 選項指定您要使用的 ONNX Runtime 版本。該指令碼在 Docker 容器中使用 ONNX Runtime 倉庫的單獨副本，因此這與包含 ONNX Runtime 倉庫的版本無關。

    構建選項透過提供給 --build_settings 選項的檔案指定。請參閱 tools/ci_build/github/android/default_full_aar_build_settings.json 中預構建包使用的當前構建選項。

    自定義構建中精簡的操作集透過提供給 --include_ops_by_config 選項的配置檔案指定。

    --build_settings 和 --include_ops_by_config 選項都是可選的，並將預設為用於構建預構建包的設定。不指定任何一個將導致生成與預構建包相似的包。

  2. 使用本地自定義 Android AAR 包。

    例如，在 Android Studio 專案中：

    a. 將 AAR 檔案從 /path/to/working/dir/output/aar_out/<build config, e.g., Release>/com/microsoft/onnxruntime/onnxruntime-android/<ORT version>/onnxruntime-android-<ORT version>.aar 複製到專案的 <module name, e.g., app>/libs 目錄。

    b. 更新專案的 <module name>/build.gradle 檔案依賴項部分

     -    implementation 'com.microsoft.onnxruntime:onnxruntime-android:latest.release'
 +    implementation files('libs/onnxruntime-android-<ORT version>.aar')

Python

如果您希望在最小構建中使用 ONNX Runtime python 繫結，則必須啟用異常，因為 Python 需要它們。

刪除 --disable_exceptions 並將 --build_wheel 新增到構建命令中，以便使用 ONNX Runtime 繫結構建 Python Wheel。

一個 .whl 檔案將在構建輸出目錄的 <config>/dist 資料夾下生成。

  • 用於 Windows Release 構建的 Python Wheel（使用 build.bat）將位於 <ONNX Runtime repository root>\build\Windows\Release\Release\dist\
  • 用於 Linux Release 構建的 Python Wheel（使用 build.sh）將位於 <ONNX Runtime repository root>/build/Linux/Release/dist/

該 wheel 可以使用 pip 安裝。請根據您的平臺和 whl 檔名調整以下命令。

pip install -U .\build\Windows\Release\Release\dist\onnxruntime-1.7.0-cp37-cp37m-win_amd64.whl