‘env’ 标志和会话选项

本文档解释了如何使用以下方法配置 ONNX Runtime Web

• ‘env’ 标志
• 会话选项

两者之间最大的区别在于，‘env’ 标志是影响整个 ONNX Runtime Web 环境的全局设置，而会话选项是特定于单个推理会话的设置。

目录

• 环境变量标志（‘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`
• 会话选项
  • 摘要
  • `executionProviders`
  • `externalData`
  • `freeDimensionOverrides`
  • `enableGraphCapture`
  • `optimizedModelFilePath`
  • `preferredOutputLocation`

环境变量标志（‘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.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 二进制文件来自同一个构建版本。否则，ONNX Runtime Web 将因 JavaScript 代码包和 WebAssembly 二进制文件之间最小化函数名不匹配而无法初始化。这意味着你不能使用此功能加载不同版本的 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 上（I/O 绑定）。

更多信息请参阅 API 参考：preferredOutputLocation。