性能诊断

ONNX Runtime Web 旨在快速高效，但有许多因素会影响应用程序的性能。本文档提供了一些关于如何诊断 ONNX Runtime Web 中性能问题的指导。

在开始之前，请确保 ONNX Runtime Web 成功加载并运行您的模型。如果遇到任何问题，请先参阅故障排除指南寻求帮助。

目录

• 通用性能提示
  • 使用正确的模型
  • 使用正确的执行提供者
  • 使用诊断功能
• CPU 提示
  • 启用多线程
  • 优先使用 uint8 量化模型
  • 启用代理工作线程
• WebGPU 提示
  • 尝试使用图捕获
  • 尝试使用自由维度覆盖
  • 尝试将张量数据保留在 GPU 上
• 诊断功能
  • 性能分析
    • CPU 性能分析
    • WebGPU 性能分析
  • 追踪
  • 日志级别“verbose”
  • 启用调试模式
• 分析性能分析数据

通用性能提示

以下是一些提高应用程序性能的通用提示

使用正确的模型

选择适合 Web 场景的模型。过大或过于复杂的模型可能无法在性能较低的硬件上高效运行。通常，“tiny”或“small”版本的模型在 Web 应用程序中更常用。这并不意味着您不能使用更大的模型，但您应该意识到由于更长的加载时间和更慢的推理可能对用户体验造成的影响。

使用正确的执行提供者

为您的场景选择正确的执行提供者。

• WebAssembly (wasm)：这是 ONNX Runtime Web 的默认 CPU 执行提供者。适用于非常小的模型或没有 GPU 的环境。

• WebGPU (webgpu)：这是默认的 GPU 执行提供者。当设备具有支持 WebGPU 的良好 GPU 时使用。

• WebNN (webnn)：此选项可以在 Web 上提供接近原生性能的潜力。目前浏览器默认不支持，但您可以在浏览器设置中手动启用 WebNN 功能。

• WebGL (webgl)：此执行提供者设计用于在不支持 WebGPU 的旧设备上使用 GPU 运行模型。

使用诊断功能

使用诊断功能获取模型执行的详细信息。这有助于理解模型的性能特征并识别潜在问题或瓶颈。

CPU 提示

如果您正在使用 WebAssembly (wasm) 执行提供者，您可以使用以下提示来提高应用程序的性能

启用多线程

如果环境支持，请始终启用多线程。多线程可以通过利用多个 CPU 核心显著提高应用程序的性能。

此功能在 ONNX Runtime Web 中默认启用，但仅当启用 crossOriginIsolated 模式时才有效。有关更多信息，请参阅 https://webdev.ac.cn/cross-origin-isolation-guide/。

您还可以使用标志 ort.env.wasm.numThreads 来设置要使用的线程数。

// Set the number of threads to 4
ort.env.wasm.numThreads = 4;

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

// Let ONNX Runtime Web decide the number of threads to use
ort.env.wasm.numThreads = 0;

有关更多详细信息，请参阅 API 参考: env.wasm.numThreads。

优先使用 uint8 量化模型

如果您正在使用量化模型，请优先使用 uint8 量化模型。如果可能，请避免使用 float16 模型，因为 float16 不受 CPU 原生支持，并且会很慢。

启用代理工作线程

代理工作线程是一项功能，允许 ONNX Runtime Web 将繁重计算卸载到单独的 Web Worker。使用代理工作线程不能提高模型的性能，但可以提高 UI 的响应能力以改善用户体验。

如果您没有在 Web Worker 中导入 ONNX Runtime Web，并且模型推理需要一段时间，建议启用代理工作线程。

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

有关更多详细信息，请参阅 API 参考: env.wasm.proxy。

WebGPU 提示

如果您正在使用 WebGPU 执行提供者，您可以使用以下提示来提高应用程序的性能

尝试使用图捕获

有关功能介绍，请参阅 图捕获。

如果您的模型具有静态形状，并且其所有计算内核都在 WebGPU EP 上运行，您可以尝试启用图捕获功能，除非您需要输入动态形状的数据（例如基于 transformer 的解码器模型）。即使是静态形状输入，此功能也并非总是适用于所有模型。您可以尝试一下，看看它是否适用于您的模型。如果它不起作用，模型初始化将失败，您可以为此模型禁用此功能。

尝试使用自由维度覆盖

有关功能介绍，请参阅 自由维度覆盖。

使用自由维度覆盖不一定能提高性能。这很大程度上取决于模型。您可以尝试一下，看看它是否适用于您的模型。如果您看到性能下降或内存使用量增加，可以禁用此功能。

尝试将张量数据保留在 GPU 上

有关功能介绍，请参阅 将张量数据保留在 GPU 上 (I/O 绑定)。

将张量数据保留在 GPU 上可以避免 CPU 和 GPU 之间不必要的数据传输，从而提高性能。尝试找出最适合您模型使用此功能的方法。

使用此功能时，请注意GPU 张量生命周期管理。

诊断功能

性能分析

您可以启用性能分析以获取有关模型执行的详细信息。这有助于理解模型的性能特征并识别潜在瓶颈。

CPU 性能分析

要启用 CPU 性能分析

• 步骤1: 在会话选项中指定 enableProfiling 选项

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

  通过指定此选项，ONNX Runtime Web 将为每次运行收集 CPU 性能分析数据。

• 步骤2: 推理后获取性能分析数据

  mySession.endProfiling();
  

  调用 endProfiling() 后，性能分析数据将输出到控制台。

  有关如何使用性能分析数据，请参阅 代码内性能分析。

WebGPU 性能分析

要启用 WebGPU 性能分析

• 设置 ort.env.webgpu.profiling = { mode: 'default' } 以启用 WebGPU 性能分析。GPU 性能分析数据将以前缀 [profiling] 输出到控制台。
• 或者，您可以将 ort.env.webgpu.profiling 设置为一个函数来处理性能分析数据

   ort.env.webgpu.profiling = {
       mode: 'default',
       ondata: (data) => {
           // handle the profiling data
       }
   };
  

  有关更多详细信息，请参阅 API 参考: env.webgpu.profiling。

追踪

您可以通过指定以下标志来启用追踪

ort.env.trace = true;

此功能使用 console.timeStamp 记录追踪数据。您可以使用浏览器的性能工具来分析追踪数据。

有关更多详细信息，请参阅 API 参考: env.trace。

日志级别“verbose”

您可以将日志级别设置为“verbose”以获取更详细的日志

ort.env.logLevel = 'verbose';

有关更多详细信息，请参阅 API 参考: env.logLevel。

启用调试模式

您可以通过指定以下标志来启用调试模式

ort.env.debug = true;

在调试模式下，ONNX Runtime Web 将记录有关模型执行的详细信息，并应用一些额外的检查。通常您需要使用 verbose 日志级别才能看到调试日志。

有关更多详细信息，请参阅 API 参考: env.debug。

分析性能分析数据

此部分正在建设中。