部署 ONNX Runtime Web

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

目录

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

资产

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

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

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

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

JavaScript 代码包

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

条件导入

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

Worker 加载

ONNX Runtime Web 中有 2 种 Worker 可以在运行时加载：

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

当部署在同源环境中时，Worker 可以直接从脚本 URL 加载。这使得 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（例如 jsdelivr 或 unpkg）的绝对 URL。

// 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 受限环境中加载。需要提供必要的工件才能使其正常工作。