‘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 标志用于启用/禁用代理 worker 功能。默认情况下禁用。

启用代理 worker 后，ONNX Runtime Web 将繁重的计算卸载到单独的 Web Worker。使用代理 worker 可以提高 UI 的响应速度，从而改善用户体验，因为计算不会阻塞主线程。

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

但是，使用代理 worker 时存在一些限制

代理 worker 无法与 WebGPU EP 一起使用。这是因为 GPU 缓冲区不可传输。如果要在 Web Worker 中使用 WebGPU EP，可以使用 importScripts() 在 Web Worker 中导入 ONNX Runtime Web 库。
代理 worker 无法在内容安全策略 (CSP) 限制的环境中工作。这是因为代理 worker 使用 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.cn/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