ONNX2WebNN

ONNX2WebNN  是一个命令行工具，可将 ONNX 模型转换为 WebNN JavaScript 文件，使用 WebNN API 在网页浏览器中进行机器学习推理。

概述

该工具会生成两个主要输出：

• 一个 JavaScript 文件（.js），包含 WebNN 模型定义
• 一个二进制文件（.bin），包含模型权重

隐私和安全

🔒 仅客户端处理

所有模型转换和 WebNN JavaScript 文件生成操作都只在你的本地环境中运行。任何模型数据、权重或知识产权都不会传输到任何外部服务器，也不会存储在外部服务器上。这使得该工具适用于：

• 专有模型
• 敏感的知识产权
• 具有严格数据治理要求的企业环境
• 任何需要完全数据隐私的场景

安装

使用 pip 安装所需的依赖项：

pip install -U onnx protobuf numpy

命令行接口

语法

python onnx2webnn.py -if INPUT_ONNX_FILE_PATH -oj OUTPUT_JS_PATH [OPTIONS]

必需参数

可选参数

基本使用方法

步骤 1：准备 ONNX 模型

转换之前，请使用 onnxruntime_perf_test  工具覆盖 ONNX 模型中的所有自由维度：

onnxruntime_perf_test -I -r 1 -u mobilenetv2-12-static.onnx -f batch_size:1 -o 1 mobilenetv2-12.onnx

步骤 2：创建输出目录

mkdir mobilenet

步骤 3：转换模型

python onnx2webnn.py -if ../sample_models/mobilenetv2-12-static.onnx -oj mobilenet/mobilenet.js

此命令会在 mobilenet 目录中生成以下文件：

• mobilenet.js - WebNN 模型实现
• mobilenet.bin - 模型权重
• mobilenet.json - 模型元数据（可选）
• index.html - WebNN 模型的测试页面

步骤 4：测试模型

通过 Node.js 启动本地 HTTP 服务器 ，并导航到测试页面：

http-server

在网页浏览器中打开 http://localhost:8080/。

NHWC 布局支持

概述

ONNX 模型默认使用 NCHW（批次、通道、高度、宽度）布局。然而，一些 WebNN 后端（例如用于 CPU 和 GPU 的 TensorFlow Lite）在使用 NHWC（批次、高度、宽度、通道）布局时性能更佳。

生成 NHWC 模型

添加 -nhwc 标志，以生成针对 NHWC 布局优化的模型：

python onnx2webnn.py -if ../sample_models/mobilenetv2-12-static.onnx -oj mobilenet_nhwc/mobilenet_nhwc.js -nhwc

动态布局选择

使用 WebNN API 检测后端偏好的布局，并加载相应的模型：

const deviceType = 'gpu'; // or 'cpu', 'npu', the option of the generated model
const context = await navigator.ml.createContext({ powerPreference: 'high-performance' });
const layout = context.opSupportLimits().preferredInputLayout;
 
let webnnModel;
if (layout === 'nhwc') {
    webnnModel = new MobilenetNhwc();
} else {
    webnnModel = new Mobilenet();
}
 
// 初始化模型
await webnnModel.build({deviceType});

deviceType 选项已从 WebNN 规范的 MLContextOptions 中移除，因此当前的浏览器会忽略它。请改用 powerPreference 和 accelerated 提示，参见 Migrating from deviceType。

生成 QDQ WebNN 模型

此工具可将 QDQ（Quantize-Dequantize）  ONNX 模型转换为 WebNN 模型。

前提条件

QDQ 模型转换需要正确的张量形状信息，以便按照 WebNN quantizeLinear 和 dequantizeLinear 规范 处理 scale 和 zero-point 张量的重塑。WebNN 规范可能要求根据输入张量的秩和 axis 参数对这些张量进行重塑。

准备你的 ONNX 模型

转换之前，请使用 onnx-simplifier  确保你的 ONNX 模型包含每个输出张量的形状信息：

1. 安装 onnx-simplifier：

   pip3 install onnxsim

2. 简化你的模型：

   onnxsim input_model.onnx output_model_simplified.onnx

   示例：

   onnxsim ../sample_models/mobilenetv2-12-qdq-static.onnx ../sample_models/mobilenetv2-12-qdq-static-simplified.onnx

转换为 WebNN

基本转换（NCHW 布局）

python onnx2webnn.py -if input_model.onnx -oj output_directory/output_model.js

示例：

python onnx2webnn.py -if ../sample_models/mobilenetv2-12-qdq-static-simplified.onnx -oj mobilenet_qdq/mobilenet_qdq.js

NHWC 布局转换

对于需要 NHWC 数据布局的模型，请添加 -nhwc 标志：

python onnx2webnn.py -if input_model.onnx -oj output_directory/output_model.js -nhwc

示例：

python onnx2webnn.py -if ../sample_models/mobilenetv2-12-qdq-static-simplified.onnx -oj mobilenet_qdq_nhwc/mobilenet_qdq_nhwc.js -nhwc

参数

使用 JSON 导出进行调试

将模型结构导出为 JSON，以便调试和分析：

python onnx2webnn.py -if ../sample_models/mobilenetv2-12-static.onnx -oj mobilenet/mobilenet.js -json

这会额外创建一个包含完整模型结构的 JSON 文件，可用于：

• 调试转换问题
• 理解模型架构
• 验证算子映射

最佳实践

1. 模型准备：转换之前，务必解决 ONNX 模型中的自由维度
2. 布局选择：使用动态布局检测，以在不同后端上优化性能
3. 测试：集成之前，使用生成的 index.html 文件验证模型功能
4. 性能：考虑同时生成 NCHW 和 NHWC 版本，以获得最佳的跨平台性能

相关 API

• WebNN API Specification 
• MLInputOperandLayout - MLContext.opSupportLimits()