部署 ONNX Runtime Web

本文档提供了一些关于如何在生产环境中部署 ONNX Runtime Web 的指南。

目录

• 资源
  • JavaScript 代码包
    • 条件导入
    • Worker 加载
  • WebAssembly 二进制文件
    • 确保正确提供 WebAssembly 二进制文件
    • 覆盖 WebAssembly 文件路径
  • 模型文件
• 文件大小注意事项
  • 自定义构建
• 安全注意事项
  • 安全上下文
  • 内容安全策略 (CSP) 限制的环境

资源

在生产环境中部署 ONNX Runtime Web 时，需要以下资源

• JavaScript 代码包：JavaScript 代码包，其中包含应用程序代码，也可能包含 ONNX Runtime Web JavaScript 代码，具体取决于应用程序的构建方式。

• WebAssembly 二进制文件：ONNX Runtime Web 库的 WebAssembly 二进制文件。

• 模型文件：您想在浏览器中运行的 ONNX 模型文件。

JavaScript 代码包

JavaScript 代码包通常是一个缩小的 JavaScript 文件，其中包含应用程序代码，由 bundler（例如 Webpack、Rollup 或 ESBuild）生成。 根据 bundler 的配置，ONNX Runtime Web JavaScript 代码可能包含在代码包中，也可能不包含（如果指定为外部依赖项）。

条件导入

为了减小 JavaScript 代码包的大小，您可以使用条件导入，仅导入 ONNX Runtime Web 库的必要部分。 例如，如果您仅使用 WebAssembly 执行提供程序，则可以导入 onnxruntime-web/wasm，这可以减小 JavaScript 代码包的大小。

Worker 加载

ONNX Runtime Web 中有两个 worker 可以在运行时加载

1. 用于代理功能的 Web worker。ONNX Runtime Web JavaScript 代码可以作为代理功能的 Web worker 的入口加载。
2. 用于 WebAssembly 多线程功能的 Web worker。Emscripten 生成的 JavaScript 文件可以作为 WebAssembly 多线程功能的 Web worker 的入口加载。

当部署在同源环境中时，可以直接从脚本 URL 加载 worker。 这使得 worker 能够在内容安全策略 (CSP) 限制的环境中加载。 当部署在跨域环境中时，例如，从 CDN 加载 worker，由于同源策略，worker 无法直接从脚本 URL 加载。 在这种情况下，将执行 fetch，并且 worker 将在从 fetch 的响应创建的对象 URL 上加载。

WebAssembly 二进制文件

标准 ONNX Runtime Web 库包括以下 WebAssembly 二进制文件

文件	SIMD	多线程	JSEP	训练
ort-wasm-simd-threaded.wasm	✔️	✔️	❌	❌
ort-wasm-simd-threaded.jsep.wasm	✔️	✔️	✔️	❌
ort-training-wasm-simd-threaded.wasm	✔️	✔️	❌	✔️

列指示 WebAssembly 工件是否支持该功能。

• SIMD：是否支持单指令多数据 (SIMD) 功能。
• 多线程：是否支持 WebAssembly 多线程功能。
• JSEP：是否启用 JavaScript 执行提供程序 (JSEP) 功能。 此功能为 WebGPU 和 WebNN 执行提供程序提供支持。
• 训练：是否启用训练功能。

在生产环境中部署 ONNX Runtime Web 时，您应该考虑在应用程序中包含哪些 WebAssembly 二进制文件。 以下是一些注意事项

• 当使用训练功能时，将使用 ort-training-wasm-simd-threaded.wasm 文件。
• 当使用 WebGPU 或 WebNN 执行提供程序时，将使用 ort-wasm-simd-threaded.jsep.wasm 文件。
• 否则，将使用 ort-wasm-simd-threaded.wasm 文件。

确保正确提供 WebAssembly 二进制文件

您应确保在服务器上正确提供 WebAssembly 二进制文件。 如果您在构建应用程序时没有复制必要的 WebAssembly 二进制文件，或者 WebAssembly 二进制文件不在预期路径中，ONNX Runtime Web 将无法初始化。

覆盖 WebAssembly 文件路径

ONNX Runtime Web 尝试使用 JavaScript 代码包的相对路径来定位 WebAssembly 二进制文件。 如果 WebAssembly 二进制文件与 JavaScript 代码包不在同一目录中，则可以通过设置 ort.env.wasm.wasmPaths 的值来覆盖文件路径。

如果您使用的是 ONNX Runtime Web 的发布版本，您还可以将 ort.env.wasm.wasmPaths 设置为指向公共 CDN 的绝对 URL，例如 jsdelivr 或 unpkg

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

// Set the WebAssembly binary file path to unpkg CDN for latest dev version
ort.env.wasm.wasmPaths = 'https://unpkg.com/onnxruntime-web@dev/dist/';

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

模型文件

如果您的 ONNX 模型文件很大并且需要一些时间才能下载，您可以考虑使用 IndexedDB 来缓存模型文件，以避免每次刷新页面时都加载模型。

如果模型包含外部数据，则需要将外部数据信息传递给 ONNX Runtime Web。 有关更多详细信息，请参阅外部数据。

文件大小注意事项

当在生产环境中部署 ONNX Runtime Web 时，工件的大小是一个重要的考虑因素。 减小文件大小可以缩短应用程序的加载时间，并减少客户端设备上的内存消耗。

要减小部署大小，您可以考虑以下选项

• 使用条件导入，仅导入 ONNX Runtime Web 库的必要部分。
• 仅提供必要的 WebAssembly 二进制文件，或使用 ort.env.wasm.wasmPaths 将 WebAssembly 二进制文件路径设置为公共 CDN。

如果您想要完全控制工件的大小，您还可以执行 ONNX Runtime Web 的自定义构建。

自定义构建

通过使用 ONNX Runtime Web 的自定义构建，您可以构建仅包含模型所需内核的 ONNX Runtime Web，这可以显着减小 WebAssembly 二进制文件的大小。 但是，这些步骤更加复杂，并且需要一些 ONNX Runtime Web 构建系统的知识。

此部分的内容正在建设中。

安全注意事项

安全上下文

WebGPU 仅在安全上下文中可访问。 简而言之，使用 HTTPS 加载的页面或使用来自 localhost/127.0.0.1 的 HTTP 加载的页面被认为是安全上下文。

有关更多详细信息，请参阅 安全上下文 和 WebGPU：故障排除提示和修复。

内容安全策略 (CSP) 限制的环境

自 ONNX Runtime Web v1.19 起，WebAssembly 二进制文件和 worker 可以在 CSP 限制的环境中加载。 需要提供必要的工件才能使其工作。