為 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://python.club.tw/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 中的最新文件，以獲取 ONNX Runtime Web 的 WebGPU 和 WebNN 詳細構建/使用說明。

最小構建支援

ONNX Runtime WebAssembly 可以使用標誌 --minimal_build 進行構建。這將生成更小的工件，並減少執行時記憶體使用。為了使用此 ONNX Runtime 配置，需要 ORT 格式模型（而不是 ONNX 格式）。更多資訊請參閱 ORT 格式轉換。

常見問題

問：在 Release 構建中，單元測試失敗。

答：單元測試需要 C++ 異常才能正常工作。然而，出於效能考慮，我們停用了 emscripten 中的異常捕獲。因此，請在 Release 構建中指定 --skip_tests。

問：在包含除錯資訊的 Debug 構建中，單元測試失敗。

答：使用除錯資訊進行構建會生成非常大的工件（單元測試超過 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 以探索更多用法。

  注意：此指令碼將覆蓋您的 WebAssembly 構建工件。如果您從原始碼構建部分工件，常見做法是執行 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 資料夾下。