构建自定义 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 以进一步最小化二进制文件大小。这些缩小尺寸的构建称为最小构建，下文描述了不同的最小构建级别。

基本 (Basic)

--minimal_build

除非启用 Python 绑定 (--build_wheel)，否则此构建默认禁用 RTTI。

基本最小构建有以下限制

  • 不支持 ONNX 格式模型。模型必须转换为 ORT 格式。
  • 不支持运行时优化。优化在转换为 ORT 格式期间执行。
  • 仅支持静态注册内核的执行提供者（例如 ONNX Runtime CPU 执行提供者）。

扩展 (Extended)

--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 算子，或没有使用 Map 类型的 ML 算子，则可以提供此标志。
  • 如果不确定，请参阅 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<发布版本> 模式。例如，v1.13.1。在这里找到它们：here。

构建命令示例

在 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 是一个配置文件，用于指定要包含的 opsets、算子内核和类型。

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/<构建配置，例如 Release>/com/microsoft/onnxruntime/onnxruntime-android/<ORT 版本>/onnxruntime-android-<ORT 版本>.aar 复制到项目的 <模块名称，例如 app>/libs 目录。

    b. 更新项目的 <模块名称>/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 文件夹下生成。

  • 使用 build.bat 进行 Windows Release 构建生成的 Python Wheel 位于 <ONNX Runtime 仓库根目录>\build\Windows\Release\Release\dist\
  • 使用 build.sh 进行 Linux Release 构建生成的 Python Wheel 位于 <ONNX Runtime 仓库根目录>/build/Linux/Release/dist/

可以使用 pip 安装 wheel 文件。根据您的平台和 .whl 文件名调整以下命令。

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