‘env’ 標誌和會話選項

本文件解釋瞭如何使用以下方法配置 ONNX Runtime Web

‘env’ 標誌
會話選項

兩者之間最大的區別在於，‘env’ 標誌是影響整個 ONNX Runtime Web 環境的全域性設定，而會話選項是特定於單個推理會話的設定。

環境變數標誌 (‘env’)

概述

環境變數標誌是一組全域性標誌，可用於配置 ONNX Runtime Web 的行為。它們可透過 ort.env 物件訪問。

import * as ort from 'onnxruntime-web';

// get the 'env' object
const env = ort.env;

這些標誌通常需要在建立任何推理會話之前設定。

有關更多資訊，請參閱API 參考：介面 Env。

`env.debug`

env.debug 標誌用於啟用/停用除錯模式。啟用後，ONNX Runtime Web 將執行額外的檢查和日誌記錄以幫助診斷問題。預設情況下停用此功能。

// enable the debug mode
ort.env.debug = true;

有關更多資訊，請參閱API 參考：env.debug。

`env.logLevel`

env.logLevel 標誌用於設定日誌級別。它可以設定為 "error" | "verbose" | "info" | "warning" | "fatal" 中的一個。預設值為 "warning"。

// set the log level to 'verbose'
ort.env.logLevel = 'verbose';

有關更多資訊，請參閱API 參考：env.logLevel。

`env.wasm`

env.wasm 物件包含用於配置 WebAssembly 例項行為的標誌。

有關更多資訊，請參閱API 參考：介面 WebAssemblyFlags。

`env.wasm.numThreads`

env.wasm.numThreads 標誌用於設定 ONNX Runtime Web 用於模型推理的執行緒數。此值包含主執行緒。

預設值為 0，這意味著它將由 ONNX Runtime Web 根據環境確定。在瀏覽器中，它將設定為 navigator.hardwareConcurrency 的一半或 4，取兩者中較小的一個。

將其設定為 1 將強制停用多執行緒。否則，ONNX Runtime Web 將檢查環境是否支援多執行緒。只有當瀏覽器支援 WebAssembly 多執行緒並啟用 crossOriginIsolated 模式時，才會啟用多執行緒。有關更多資訊，請參閱跨域隔離指南。

// Disable multi-threading
ort.env.wasm.numThreads = 1;

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

`env.wasm.proxy`

env.wasm.proxy 標誌用於啟用/停用代理工作器功能。預設情況下停用此功能。

啟用代理工作器後，ONNX Runtime Web 將把繁重的計算解除安裝到單獨的 Web Worker。使用代理工作器可以提高 UI 的響應速度，從而改善使用者體驗，因為計算不會阻塞主執行緒。

// Enable proxy worker
ort.env.wasm.proxy = true;

然而，使用代理工作器存在一些限制

代理工作器不能與 WebGPU EP 一起使用。這是因為 GPU 緩衝區不可傳輸。如果要在 Web Worker 中使用 WebGPU EP，可以使用 importScripts() 在 Web Worker 中匯入 ONNX Runtime Web 庫。
代理工作器無法在內容安全策略 (CSP) 受限環境中工作。這是因為代理工作器使用 Blob 建立 Web Worker，而 CSP 可能會阻止 Web Worker 的建立。

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

`env.wasm.wasmPaths`

env.wasm.wasmPaths 標誌用於覆蓋 WebAssembly 二進位制檔案路徑。它可以透過兩種方式使用

將 env.wasm.wasmPaths 設定為字串作為路徑字首。

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

將 env.wasm.wasmPaths 設定為一個物件，其中鍵是 WebAssembly 二進位制檔名，值是 WebAssembly 二進位制檔案的路徑。

// Set separate WebAssembly binary file paths
ort.env.wasm.wasmPaths = {
  'ort-wasm-simd.jsep.wasm': 'https://example.com/path/to/ort-wasm-simd.jsep.wasm'
  'ort-wasm-simd-threaded.jsep.wasm': 'https://example.com/path/to/ort-wasm-simd-threaded.jsep.wasm',
};

當 WebAssembly 二進位制檔案與 JavaScript 程式碼包不在同一目錄下時，此標誌很有用。當您想使用公共 CDN 提供 WebAssembly 二進位制檔案時，它也很有用。

注意：請確保 JavaScript 程式碼包和 WebAssembly 二進位制檔案來自相同的構建版本。否則，由於 JavaScript 程式碼包和 WebAssembly 二進位制檔案之間的最小化函式名不匹配，ONNX Runtime Web 將無法初始化。這意味著您不能使用此功能載入不同版本的 WebAssembly 二進位制檔案。

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

`env.webgpu`

env.webgpu 物件包含用於配置 WebGPU EP 行為的標誌。

有關更多資訊，請參閱API 參考：介面 WebGpuFlags。

`env.webgpu.device` 和 `env.webgpu.adapter`

這兩個標誌用於在建立 WebGPU 推理會話後獲取 WebGPU 裝置和介面卡。

env.webgpu.adapter 標誌還可用於在建立第一個 WebGPU 推理會話之前設定 WebGPU EP 將使用的介面卡。當您想使用特定介面卡時，此功能很有用。

有關更多資訊，請參閱API 參考：env.webgpu.device 和 API 參考：env.webgpu.adapter。

`env.webgpu.powerPreference` 和 `env.webgpu.forceFallbackAdapter`

這兩個標誌用於設定 WebGPU EP 的電源偏好和強制回退介面卡。當 WebGPU EP 在沒有透過 env.webgpu.adapter 設定任何預配置介面卡的情況下進行初始化時，將使用它們。

有關更多資訊，請參閱API 參考：env.webgpu.powerPreference 和 API 參考：env.webgpu.forceFallbackAdapter。

`env.webgpu.profiling`

env.webgpu.profiling 標誌用於啟用 WebGPU 效能分析。

有關更多詳細資訊，請參閱WebGPU 效能分析。

有關更多資訊，請參閱API 參考：env.webgpu.profiling。

會話選項

概述

會話選項用於配置單個推理會話的行為。它們作為引數傳遞給 InferenceSession.create() 方法。

有關更多資訊，請參閱API 參考：介面 InferenceSession.SessionOptions。

`executionProviders`

executionProviders 選項用於指定推理會話將使用的一系列執行提供者。

ONNX Runtime Web 中可用的執行提供者如下：

'wasm'：預設的 CPU 執行提供者。
'webgpu'：WebGPU 執行提供者。有關更多詳細資訊，請參閱WebGPU EP。
'webnn'：WebNN 執行提供者。有關更多詳細資訊，請參閱WebNN EP。
'webgl'：WebGL 執行提供者。

const mySession = await ort.InferenceSession.create(modelUrl, {
    ...,
    // specify the EP list
    executionProviders: ['webgpu', 'wasm']
});

有關更多資訊，請參閱API 參考：executionProviders。

`externalData`

externalData 選項用於將外部資料資訊傳遞給 ONNX Runtime Web。當模型的權重儲存在外部資料檔案中時，您需要將外部資料資訊傳遞給 ONNX Runtime Web。有關更多詳細資訊，請參閱外部資料。

有關更多資訊，請參閱API 參考：externalData。

`freeDimensionOverrides`

freeDimensionOverrides 選項用於覆蓋模型的自由維度。

ONNX 模型可能有一些自由維度，這意味著模型可以在該維度上接受任何大小的輸入。例如，一個影像模型可能會將其輸入形狀定義為 [batch, 3, height, width]，這意味著只要通道數為 3，模型就可以接受任意數量、任意大小的影像。但是，如果您的應用程式始終使用特定大小的影像，您可以將自由維度覆蓋為特定大小，這有助於最佳化模型效能。例如，如果您的 Web 應用始終使用 224x224 的單張影像，您可以透過在會話選項中指定以下配置將自由維度覆蓋為 [1, 3, 224, 224]

const mySessionOptions = {
  ...,
  freeDimensionOverrides: {
    batch: 1,
    height: 224,
    width: 224
  }
};

有關更多資訊，請參閱API 參考：freeDimensionOverrides。

`enableGraphCapture`

enableGraphCapture 選項用於啟用圖捕獲功能。目前，此功能僅適用於 WebGPU EP。

如果 ONNX Runtime 確定模型具有靜態形狀，並且其所有計算核心都在註冊的 EP 上執行，則可以在第一次執行時捕獲核心執行，並在後續執行中重播它們。當 CPU 有時是準備命令的瓶頸時，這可以帶來更好的效能。

const mySessionOptions = {
  ...,
  enableGraphCapture: true
};

並非所有模型都適合圖捕獲。一些具有動態輸入形狀的模型可以與自由維度覆蓋一起使用此功能。有些模型則無法使用此功能。您可以嘗試一下，看看它是否適用於您的模型。如果不起作用，模型初始化將失敗，您可以停用此模型的功能。

有關更多詳細資訊，請參閱API 參考：enableGraphCapture。

`optimizedModelFilePath`

optimizedModelFilePath 選項用於指定最佳化模型的檔案路徑。在瀏覽器中，此選項的值將被忽略。取而代之的是，會開啟一個新標籤頁，其中包含最佳化模型的內容作為 blob，允許使用者下載並儲存最佳化模型。

const mySessionOptions = {
  ...,
  // specify this option to allow downloading the optimized model
  optimizedModelFilePath: 'optimized_model.onnx'
};

注意：此功能預設不可用。它需要使用 --cmake_extra_defines onnxruntime_ENABLE_WEBASSEMBLY_OUTPUT_OPTIMIZED_MODEL=1 命令列選項重新構建 ONNX Runtime Web。

有關更多資訊，請參閱API 參考：optimizedModelFilePath。

`preferredOutputLocation`

preferredOutputLocation 選項用於指定輸出資料的首選位置。它可用於將輸出資料保留在 GPU 上以供進一步處理。有關更多詳細資訊，請參閱在 GPU 上保留張量資料 (IO 繫結)。

有關更多資訊，請參閱API 參考：preferredOutputLocation。

‘env’ 標誌和會話選項

目錄

環境變數標誌 (‘env’)

概述

env.debug

env.logLevel

env.wasm

env.wasm.numThreads

env.wasm.proxy

env.wasm.wasmPaths

env.webgpu

env.webgpu.device 和 env.webgpu.adapter

env.webgpu.powerPreference 和 env.webgpu.forceFallbackAdapter

env.webgpu.profiling