部署 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 代码包通常是由 Webpack、Rollup 或 ESBuild 等打包工具生成的、包含应用程序代码的压缩 JavaScript 文件。根据打包工具的配置，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 的入口加载。

当部署在同源环境中时，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 受限环境中加载。需要提供必要的文件才能使其工作。