性能诊断

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

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

目录

• 一般性能技巧
  • 使用正确的模型
  • 使用正确的执行提供程序
  • 使用诊断功能
• CPU 技巧
  • 启用多线程
  • 优先选择 uint8 量化模型
  • 启用代理 Worker
• 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 原生支持，速度会很慢。

启用代理 Worker

代理 Worker 是一项功能，允许 ONNX Runtime Web 将繁重计算卸载到单独的 Web Worker。使用代理 Worker 无法提高模型的性能，但可以提高 UI 的响应速度，从而改善用户体验。

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

// 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。

分析性能分析数据

此部分正在建设中。