构建自定义 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