为 Web 构建 ONNX Runtime

构建 ONNX Runtime Web 分为 2 个步骤

• 获取 ONNX Runtime WebAssembly 工件 - 可以通过以下方式完成 -
  • 为 WebAssembly 构建 ONNX Runtime
  • 下载预构建的工件 以下说明
• 构建 onnxruntime-web（NPM 包）
  • 此步骤需要 ONNX Runtime WebAssembly 工件

目录

• 构建 ONNX Runtime Webassembly 工件
• 构建 onnxruntime-web - NPM 包

构建 ONNX Runtime Webassembly 工件

先决条件

• 检出源代码树

  git clone --recursive https://github.com/Microsoft/onnxruntime
  cd onnxruntime
  

• 安装 cmake-3.26 或更高版本。

• 安装 Node.js (16.0+, 推荐 18.0+)

  • （可选）使用 nvm (Windows / Mac/Linux) 安装 Node.js
• Python (3.9+): https://pythonlang.cn/downloads/
  • 应将 python 添加到 PATH 环境变量
• Ninja: https://ninja-build.org/

  pip install ninja
  

• 准备 emsdk：emsdk 应自动安装在 <ORT_ROOT>/cmake/external/emsdk/emsdk。如果文件夹结构不存在，请在 <ORT_ROOT>/ 中运行以下命令以安装 git 子模块

  git submodule sync --recursive
  git submodule update --init --recursive
  

  （如果您使用的是 Windows，则可以跳过此步骤）在 <ORT_ROOT>/cmake/external/emsdk/ 中，运行以下命令以设置 emsdk

  ./emsdk install latest
  ./emsdk activate latest
  source ./emsdk_env.sh
  

构建说明

ONNX Runtime WebAssembly 可以构建为支持或不支持多线程和单指令多数据 (SIMD)。此支持通过在构建命令中附加以下标志来添加/删除，默认构建选项是不支持。

构建标志	用法
--enable_wasm_threads	构建时启用多线程支持
--enable_wasm_simd	构建时启用 SIMD 支持

ONNX Runtime Web 可以通过 JavaScript 执行提供程序 (JSEP) 构建为支持 WebGPU 和 WebNN。要构建支持 JSEP 的版本，请使用标志 --use_jsep。构建 WebNN 支持需要额外的标志 --use_webnn。

ONNX Runtime Web 也可以构建为支持训练 API。要构建包含训练 API 的版本，请使用标志 --enable-training-apis。

完整的 ONNX Runtime Web 构建的 WebAssembly 工件将包含 3 个“.wasm”文件和 3 个“.mjs”文件。应针对每个配置运行以下构建命令。

在 <ORT_ROOT>/ 中，运行以下命令之一来构建 WebAssembly

# In windows, use 'build' to replace './build.sh'
# It's recommended to use '--skip_tests` in Release & Debug + 'debug info' configruations - please review FAQ for more details

# The following command build debug.
./build.sh --build_wasm --enable_wasm_simd --enable_wasm_threads

# The following command build debug with debug info.
./build.sh --build_wasm --enable_wasm_simd --enable_wasm_threads --skip_tests --enable_wasm_debug_info

# The following command build release.
./build.sh --config Release --build_wasm --skip_tests --disable_wasm_exception_catching --disable_rtti

所需构建工件的完整列表

文件名	使用的构建标志
ort-wasm-simd-threaded.wasm	--enable_wasm_simd --enable_wasm_threads
ort-wasm-simd-threaded.mjs	--enable_wasm_simd --enable_wasm_threads
ort-wasm-simd-threaded.jsep.wasm	--use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads
ort-wasm-simd-threaded.jsep.mjs	--use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads
ort-training-wasm-simd.wasm	--enable_wasm_simd --enable_wasm_threads --enable_training_apis
ort-training-wasm-simd.mjs	--enable_wasm_simd --enable_wasm_threads --enable_training_apis

注意

• 自 v1.19.0 起，ONNX Runtime Web 将在未来版本中停止支持非 SIMD 和非线程构建。
• WebGPU 和 WebNN 目前作为 ONNX Runtime Web 的实验性功能提供支持。构建说明可能会更改。请务必参考 webgpu gist 和 webnn gist 中的最新文档，以获取有关 ORT Web WebGPU 和 WebNN 的详细构建/使用说明。

最小构建支持

可以使用标志 --minimal_build 构建 ONNX Runtime WebAssembly。这将生成更小的工件，并减少运行时内存使用量。为了使用此 ONNX Runtime 配置，需要 ORT 格式的模型（而不是 ONNX 格式）。有关更多信息，另请参阅 ORT 格式转换。

常见问题解答

问：Release 构建中的 unittest 失败。

答：unittest 需要 C++ 异常才能正常工作。但是，出于性能考虑，我们在 emscripten 中禁用了异常捕获。因此，请在 Release 构建中指定 --skip_tests。

问：Debug 构建和调试信息中的 unittest 失败。

答：使用调试信息构建将生成非常大的工件（unittest 大于 1GB），并且无法在 Node.js 中加载。因此，请在使用调试信息构建时指定 --skip_tests。

问：我有一个用于 Web 场景的 C++ 项目，该项目使用 ONNX Runtime 运行 ML 模型并生成 WebAssembly 作为输出。ONNX Runtime Web 是否支持静态 WebAssembly 库，以便我的应用程序可以与其链接，并将所有预处理器/后处理器一起编译到 WebAssembly 中？

答：使用 --build_wasm，构建脚本会为 Web 场景生成 .wasm 和 .js 文件，并且中间库未与其他 C/C++ 项目正确链接。当您使用 --build_wasm_static_lib 而不是 --build_wasm 构建 ONNX Runtime Web 时，构建脚本会在输出目录中生成一个名为 libonnxruntime_webassembly.a 的 ONNX Runtime Web 静态库。要运行像 单元测试 这样的简单推理，您需要以下三个头文件和 libonnxruntime_webassembly.a。

• include/onnxruntime/core/session/onnxruntime_c_api.h
• include/onnxruntime/core/session/onnxruntime_cxx_api.h
• include/onnxruntime/core/session/onnxruntime_cxx_inline.h

一个重要的注意事项是，ONNX Runtime 依赖于许多第三方库，例如 protobuf、onnx 等。您可能需要将必要的头文件复制到您的项目中。您还需要注意 ONNX Runtime 和您的项目之间的库版本冲突或 emsdk 版本冲突的情况。

构建 onnxruntime-web - NPM 包

以下各节是有关 onnxruntime-web NPM 包的分步安装指南。这是构建过程的最后阶段，请按顺序遵循各节。

先决条件

• 安装 Node.js (16.0+, 推荐 18.0+)

  • （可选）使用 nvm (Windows/Mac/Linux) 安装 Node.js

• 用于运行测试的 Chrome 或 Edge 浏览器。

安装 NPM 包

1. 在 <ORT_ROOT>/js/ 中，运行 npm ci。
2. 在 <ORT_ROOT>/js/common/ 中，运行 npm ci。
3. 在 <ORT_ROOT>/js/web/ 中，运行 npm ci。

准备 ONNX Runtime WebAssembly 工件

您可以选择使用预构建的工件或自行构建。

• 通过脚本设置。

  在 <ORT_ROOT>/js/web/ 中，运行 npm run pull:wasm 以从 CI 管道中拉取最新主分支的 WebAssembly 工件。使用 npm run pull:wasm help 探索更多用法。

  注意：此脚本将覆盖您的 webaseembly 构建工件。如果您从源代码构建了一部分工件，常见的做法是运行 npm run pull:wasm 以拉取全套预构建工件，然后将您的构建工件（按照以下说明）复制到目标文件夹，这样您就不需要构建 6 次。

• 手动从管道下载工件。

  您可以从 Windows WebAssembly CI 管道 下载预构建的 WebAssembly 工件。选择一个构建，下载工件“Release_wasm”并解压缩。请参阅以下说明，将文件放入目标文件夹。

• 构建 WebAssembly 工件。

  1. 构建 ONNX Runtime WebAssembly

     请按照上面的 说明 构建 ONNX Runtime WebAssembly。

  2. 将以下文件从构建输出文件夹复制到 <ORT_ROOT>/js/web/dist/（如果该文件夹不存在，请创建它）

     • ort-wasm-simd-threaded.wasm（使用标志 --enable_wasm_threads --enable_wasm_simd 构建）
     • ort-wasm-simd-threaded.mjs（使用标志 --enable_wasm_threads --enable_wasm_simd 构建）
     • ort-wasm-simd-threaded.jsep.wasm（使用标志 --use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads 构建）
     • ort-wasm-simd-threaded.jsep.mjs（使用标志 --use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads 构建）
     • ort-training-wasm-simd-threaded.wasm（使用标志 --enable_wasm_simd --enable_wasm_threads --enable_training_apis 构建）
     • ort-training-wasm-simd-threaded.mjs（使用标志 --enable_wasm_simd --enable_wasm_threads --enable_training_apis 构建）

完成 onnxruntime 构建

在文件夹 <ORT_ROOT>/js/web 中使用以下命令进行构建

   npm run build

这将生成最终要使用的 JavaScript 捆绑文件。它们位于文件夹 <ORT_ROOT>/js/web/dist 下。