部署 ONNX Runtime Web

本文件提供了一些關於如何在生產環境中部署 ONNX Runtime Web 的指導。

目錄

• 資產
  • JavaScript 程式碼包
    • 條件匯入
    • Worker 載入
  • WebAssembly 二進位制檔案
    • 確保 WebAssembly 二進位制檔案已正確提供
    • 覆蓋 WebAssembly 檔案路徑
  • 模型檔案
• 檔案大小考量
  • 自定義構建
• 安全考量
  • 安全上下文
  • 內容安全策略 (CSP) 受限環境

資產

在生產環境中部署 ONNX Runtime Web 時，需要以下資產：

• JavaScript 程式碼包：包含應用程式程式碼，並且可能包含 ONNX Runtime Web JavaScript 程式碼的 JavaScript 程式碼包，具體取決於應用程式的構建方式。

• WebAssembly 二進位制檔案：ONNX Runtime Web 庫的 WebAssembly 二進位制檔案。

• 模型檔案：您希望在瀏覽器中執行的 ONNX 模型檔案。

JavaScript 程式碼包

JavaScript 程式碼包通常是一個經過壓縮的 JavaScript 檔案，其中包含應用程式程式碼，由 Webpack、Rollup 或 ESBuild 等打包工具生成。根據打包工具的配置，ONNX Runtime Web JavaScript 程式碼可能包含在包中，也可能不包含（如果指定為外部依賴項）。

條件匯入

為了減小 JavaScript 程式碼包的大小，您可以使用 條件匯入 來僅匯入 ONNX Runtime Web 庫中必需的部分。例如，如果您只使用 WebAssembly 執行提供程式，則可以匯入 onnxruntime-web/wasm，這可以減小 JavaScript 程式碼包的大小。

Worker 載入

ONNX Runtime Web 中有 2 種 Worker 可以在執行時載入：

1. 用於代理功能的 Web Worker。ONNX Runtime Web JavaScript 程式碼可以作為代理功能 Web Worker 的入口載入。
2. 用於 WebAssembly 多執行緒功能的 Web Worker。Emscripten 生成的 JavaScript 檔案可以作為 WebAssembly 多執行緒功能 Web Worker 的入口載入。

當部署在同源環境中時，Worker 可以直接從指令碼 URL 載入。這使得 Worker 能夠在內容安全策略 (CSP) 受限環境中載入。當部署在跨域環境中時，例如從 CDN 載入 Worker，由於同源策略，Worker 無法直接從指令碼 URL 載入。在這種情況下，將執行 fetch 操作，Worker 將載入到從 fetch 響應建立的物件 URL 上。

WebAssembly 二進位制檔案

標準 ONNX Runtime Web 庫包含以下 WebAssembly 二進位制檔案：

檔案	SIMD	多執行緒	JSEP	訓練
ort-wasm-simd-threaded.wasm	✔️	✔️	❌	❌
ort-wasm-simd-threaded.jsep.wasm	✔️	✔️	✔️	❌
ort-training-wasm-simd-threaded.wasm	✔️	✔️	❌	✔️

列指示 WebAssembly 檔案是否支援該功能。

• SIMD：是否支援單指令多資料 (SIMD) 功能。
• 多執行緒：是否支援 WebAssembly 多執行緒功能。
• JSEP：是否啟用 JavaScript 執行提供程式 (JSEP) 功能。此功能為 WebGPU 和 WebNN 執行提供程式提供支援。
• 訓練：是否啟用訓練功能。

在生產環境中部署 ONNX Runtime Web 時，您應該考慮在應用程式中包含哪些 WebAssembly 二進位制檔案。以下是一些注意事項：

• 使用訓練功能時，使用 ort-training-wasm-simd-threaded.wasm 檔案。
• 使用 WebGPU 或 WebNN 執行提供程式時，使用 ort-wasm-simd-threaded.jsep.wasm 檔案。
• 否則，使用 ort-wasm-simd-threaded.wasm 檔案。

確保 WebAssembly 二進位制檔案已正確提供

您應確保 WebAssembly 二進位制檔案在伺服器上已正確提供。如果您在構建應用程式時沒有複製必要的 WebAssembly 二進位制檔案，或者 WebAssembly 二進位制檔案不在預期路徑中，ONNX Runtime Web 將無法初始化。

覆蓋 WebAssembly 檔案路徑

ONNX Runtime Web 會嘗試使用 JavaScript 程式碼包的相對路徑來查詢 WebAssembly 二進位制檔案。如果 WebAssembly 二進位制檔案不在 JavaScript 程式碼包的同一目錄中，您可以透過設定 ort.env.wasm.wasmPaths 的值來覆蓋檔案路徑。

如果您使用的是 ONNX Runtime Web 的釋出版本，您還可以將 ort.env.wasm.wasmPaths 設定為公共 CDN（例如 jsdelivr 或 unpkg）的絕對 URL。

// Set the WebAssembly binary file path to jsdelivr CDN for latest dev version
ort.env.wasm.wasmPaths = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@dev/dist/';

// Set the WebAssembly binary file path to unpkg CDN for latest dev version
ort.env.wasm.wasmPaths = 'https://unpkg.com/onnxruntime-web@dev/dist/';

有關更多詳細資訊，請參閱 API 參考：env.wasm.wasmPaths。

模型檔案

如果您的 ONNX 模型檔案較大且需要一些時間下載，您可以考慮使用 IndexedDB 快取模型檔案，以避免每次重新整理頁面時都載入模型。

如果模型包含外部資料，您需要將外部資料資訊傳遞給 ONNX Runtime Web。有關更多詳細資訊，請參閱 外部資料。

檔案大小考量

在生產環境中部署 ONNX Runtime Web 時，工件的大小是一個重要的考量因素。減小檔案大小可以改善應用程式的載入時間，並減少客戶端裝置的記憶體消耗。

為減小部署大小，您可以考慮以下選項：

• 使用 條件匯入 來僅匯入 ONNX Runtime Web 庫中必需的部分。
• 僅提供必要的 WebAssembly 二進位制檔案，或者使用 ort.env.wasm.wasmPaths 將 WebAssembly 二進位制檔案路徑設定為公共 CDN。

如果您想對工件大小進行終極控制，您還可以執行 ONNX Runtime Web 的自定義構建。

自定義構建

透過使用 ONNX Runtime Web 的自定義構建，您可以僅使用模型所需的核心來構建 ONNX Runtime Web，這可以顯著減小 WebAssembly 二進位制檔案的大小。然而，這些步驟更為複雜，需要對 ONNX Runtime Web 構建系統有一定了解。

此部分內容正在建設中。

安全考量

安全上下文

WebGPU 僅在安全上下文中可訪問。簡而言之，使用 HTTPS 載入的頁面或從 localhost/127.0.0.1 使用 HTTP 載入的頁面被視為安全上下文。

有關更多詳細資訊，請參閱 安全上下文 和 WebGPU：故障排除提示和修復。

內容安全策略 (CSP) 受限環境

自 ONNX Runtime Web v1.19 起，WebAssembly 二進位制檔案和 Worker 可以在 CSP 受限環境中載入。需要提供必要的工件才能使其正常工作。