构建自定义 ONNX Runtime 包

当目标环境的需求需要时，可以自定义 ONNX Runtime 包。

自定义 ONNX Runtime 构建的最常见场景是用于更小 footprint 的部署，例如移动设备和 Web。

自定义构建的最常见机制是减少运行时中支持的运算符集，使其仅包含目标环境中运行的模型或模型中的运算符。

要构建自定义 ONNX Runtime 包，请应用从源代码构建说明，并使用下面指定的一些额外选项。

目录

减少运算符内核

为了减小 ONNX Runtime 的编译二进制文件大小，可以将构建中包含的运算符内核减少到模型所需的最少内核。

包含的运算符在构建时在配置文件中指定，该文件可以从模型或模型集中生成。

将构建减少到所需运算符内核的构建选项

--include_ops_by_config

  • 将 --include_ops_by_config <模型转换期间生成的配置文件> --skip_tests 添加到构建参数。

  • 注意：构建将编辑一些 ONNX Runtime 源文件以排除未使用的内核。

    特别是，此源代码修改将在“update”构建阶段完成，默认情况下启用该阶段，或使用 --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

在此构建中，RTTI 默认情况下被禁用，除非启用了 Python 绑定 (--build_wheel)。

基本最小化构建具有以下限制

  • 不支持 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 运算符，或者没有使用 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。在此处查找它们此处。

示例构建命令

在 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 构建生成 pod，请使用 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. 使用本地 pod。

    例如，更新 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，则还需要在 Podfile 中指定它所依赖的本地 onnxruntime-c pod。

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