企业官网建设流程全解析

ONNX Runtime Web WebNN EP 算子支持指南：覆盖清单、版本区间与底层实现解析

【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime

本指南基于 js/web/docs/webnn-operators.md 展开，系统梳理 ONNX Runtime Web 中WebNN EP（Execution Provider）对 ONNX 算子及 opset 版本的支持范围、每条支持项背后的 WebNN API 映射，以及各算子的实际约束条件。读完本文，你将掌握：如何按表判断一个 ONNX 模型能否在 WebNN EP 上运行、每条支持记录中"版本区间/WebNN API/注释"三列的确切含义，以及 WebNN EP 在 onnxruntime/core/providers/webnn 源码中如何完成从算子注册、能力检查到模型编译的完整流程。

一、WebNN EP 与支持表的使用前提

1.1 什么是 WebNN EP

WebNN EP 是 ONNX Runtime Web 通过 WebNN（Web Neural Network API，W3C 标准，见 webmachinelearning/webnn）将模型推理卸载到浏览器底层硬件加速器（CPU/GPU/NPU）的执行提供程序。它的 C++ 侧实现位于 onnxruntime/core/providers/webnn，而 JS 侧入口在 js/web/lib/wasm/jsep/backend-webnn.ts 与 js/web/lib/wasm/session-options.ts。

WebNN API 目前在 Windows、Linux、macOS、Android 与 ChromeOS 上的最新版 Chrome 和 Edge 中可用（需在浏览器实验特性中开启"Enables WebNN API"标志）。由于不同平台对 WebNN 各算子的实现进度不一，同一算子在不同平台上的支持状态可能有差异，具体实现细节应参考 WebNN status。这也意味着：下面的支持表描述的是 WebNN EP 代码层面允许的算子集合，最终能否在某个平台上成功运行，还取决于该平台浏览器对 WebNN 对应 API 的实现程度。

1.2 支持表三列的含义

支持表每行包含三列，含义如下：

关于 opset 需要特别说明：ONNX Runtime 官方只保证对ai.onnx域中 opset 7 及以上版本标注的模型提供支持（原文档中的 Note）。因此低于 opset 7 的模型即使算子出现在表中，也不能视为受支持。

1.3 从源码看能力检查流程

WebNN EP 的算子支持检查并非运行时逐个硬编码，而是由执行提供程序的GetCapability流程驱动。在 webnn_execution_provider.cc 中可以看到完整链条：

1. 构造MLGraphBuilder（emscripten::val::global("MLGraphBuilder").new_(wnn_context_)）；
2. 调用 helper.cc 中的GetSupportedNodes/IsNodeSupported，按节点类型在算子构建器注册表中查找；
3. 对查到的节点调用IsOpSupported做细粒度检查（含opSupportLimits()返回的 rank 范围校验，见 helper.cc）；
4. 最终通过CreateSupportedPartitions把支持的节点划分成子图并生成 metadef（命名形如WEBNN_<hash>_<id>）。

其中，算子构建器注册表定义在 op_builder_factory.cc，一个 ONNX 算子由对应的*_op_builder.cc实现（如conv_op_builder.cc、gemm_op_builder.cc、gqa_op_builder.cc）。表中有不少算子（如DynamicQuantizeLinear、Einsum、LRN、SimplifiedLayerNormalization）的 WebNN API 列包含多个原语，正是因为它们在 builders/impl 下被分解为若干基础 WebNN 操作的组合。

另外值得注意：在 JS 侧启用 WebNN EP 时，session-options.ts 会自动设置session.disable_quant_qdq与session.disable_qdq_constant_folding两项会话配置，以保证 DQ/Q 节点以独立算子形式保留给 WebNN EP 处理——这正是表中ConvInteger、DequantizeLinear、QuantizeLinear、MatMulInteger、MatMulNBits等量化算子能被识别的前提。

二、完整算子支持表（原文档全量继承）

下表为 WebNN EP 当前支持的 ONNX 算子全集（按算子名排序），含 opset 支持区间、映射的 WebNN API 与关键约束注释。

三、约束条件的规律性解读

表中 Comments 列并非随意罗列，而是体现了 WebNN EP 在算子映射上的几条系统性规律：

1. 常量输入约束（Constant Input Requirement）多个算子要求某个输入必须是常量（constant initializer），原因在于 WebNN 构建图时需要把 shape、axes、split、starts/ends 等元数据在编译期确定下来。典型包括：

• CumSum的axis、Expand的shape、Split的split、Tile的repeats、Trilu的k；
• 全部Reduce*系列算子的axes（如存在）；
• Reshape的shape（且 shape 中不允许出现 0 维）、Resize的scales/sizes、Slice的starts/ends/axes/steps、Squeeze的axes。

这与 helper.cc 中的形状检查逻辑呼应——WebNN 不支持动态形状，动态维度需要用户通过sessionOptions.FreeDimensionOverrides预先固定。

2. 秩（Rank）与 kernel 维度限制

• AveragePool、MaxPool、LpPool仅支持 4-D 输入和 2-Dkernel_shape，且MaxPool要求storage_order != 1、只输出一个张量；
• Conv/ConvInteger/ConvTranspose仅支持 3-D 或 4-D 输入与权重；
• GlobalAveragePool/GlobalMaxPool/GlobalLpPool仅支持 4-D 输入，GlobalLpPool与LpPool的p值必须为 2。

这是因为底层 WebNN API 提供的是 2D 变体（averagePool2d、maxPool2d、conv2d、convTranspose2d），WebNN EP 会把 ONNX 的 N-D 语义收缩到 WebNN 的 2D 语义上，超出范围的秩无法映射。

3. 循环网络（RNN）相关约束GRU与LSTM的限制高度一致：layout必须为 0，不支持clip，激活函数只能是Relu/Tanh/Sigmoid，双向时必须前后向激活一致，sequence_lens若存在须为常量且等于输入X第一维长度。此外LSTM还要求input_forget == 0。这些约束在 gru_op_builder.cc 与 lstm_op_builder.cc 中有对应的属性校验实现。

4. 量化与注意力扩展算子

• 量化系列：ConvInteger、MatMulInteger通过cast+dequantizeLinear+conv2d/matmul组合实现；DequantizeLinear/QuantizeLinear在量化轴（axis）不是最后一维时需配合reshape；MatMulNBits仅支持 bits=4 与 bits=8，权重B与zero_points必须为常量，且不支持g_idx输入；GatherBlockQuantized要求 uint8 打包的 4-bit 数据按 uint4 重新解释，因此quantize_axis必须是最后一维、data与zero_points必须为常量初始化器。
• 注意力系列：MultiHeadAttention不支持bias、key_padding_mask、past_sequence_length、cache_indirection输入及qk输出；GroupQueryAttention要求输入total_sequence_length为常量，且 past kv 的past_sequence_length必须等于 present kv 的present_sequence_length。RotaryEmbedding同时支持ai.onnx(23+)与com.microsoft(1+)两个域。这些算子的构建器分别位于 mha_op_builder.cc、gqa_op_builder.cc 与 rotaryEmbedding_op_builder.cc。

5. 仅支持推理路径的算子Dropout仅支持测试模式（test mode），BatchNormalization仅支持training_mode == 0且只输出一个结果。这与 ONNX Runtime 推理引擎的定位一致，训练相关路径不会被 WebNN EP 接管。

四、算子映射的复合实现：从 ONNX 到 WebNN 原语

支持表的 WebNN API 列值得再展开一层：当某一格出现多个 API 时，说明该 ONNX 算子并非一对一映射，而是在 onnxruntime/core/providers/webnn/builders/impl 中由多个 WebNN 原语拼装而成。从源码结构看，可以归纳出以下模式：

• 一对一直接映射：Abs → abs、Add → add、Relu → relu、MatMul → matmul、Concat → concat等，是最常见的形态，构建器直接在 WebNN builder 上调用同名方法。
• 同构替代：Clip → clamp、Round → roundEven、Reshape/Flatten/Squeeze/Unsqueeze → reshape、Shape → slice、Dropout(测试模式) → identity，ONNX 语义与 WebNN 原语语义一致或 WebNN 侧可用更基础的原语表达。
• 分解组合：LRN需要pad + averagePool2d + transpose + add + mul + pow + div七个原语；SimplifiedLayerNormalization由pow + reduceMean + add + sqrt + div + mul组成；DynamicQuantizeLinear用cast/clamp/div/max/min/quantizeLinear/reduceMax/reduceMin/reshape/roundEven/sub展开。这类算子的实现可以在 lrn_op_builder.cc、normalization_op_builder.cc 与 dynamicQuantizeLinear_op_builder.cc 中逐行验证。

这一设计使 WebNN EP 能用有限的标准 WebNN 原语覆盖远超其原生算子集的 ONNX 算子面，代价是部分复合算子在精度、速度与内存占用上不如原生实现，这也是为何支持表中会为复合算子标注出若干"不支持"的属性组合。

五、在 ONNX Runtime Web 中启用 WebNN EP 的配置方式

支持表是"能不能跑"的判据，而"怎么让它跑"涉及执行提供程序的注册参数。在 webnn_provider_factory.cc 中，WebNNProviderFactoryCreator::Create从 ProviderOptions 中读取deviceType；在 helper.cc 中，DeviceTypeFromString支持"gpu"、"cpu"、"npu"三种取值，非法值会抛出Unknown WebNN deviceType.。

在 JS 侧（如 js/web/lib/wasm/session-options.ts 所示），通过executionProviders传入webnn并可选指定deviceType：

import * as ort from 'onnxruntime-web'; const session = await ort.InferenceSession.create('./model.onnx', { executionProviders: [{ name: 'webnn', deviceType: 'gpu', // 可选：'gpu' | 'cpu' | 'npu' }], });

要点：

• 选择webnnEP 时，ORT 会自动追加session.disable_quant_qdq=1与session.disable_qdq_constant_folding=1，以保留 DQ/Q 节点供 WebNN EP 处理（见 session-options.ts）。
• deviceType会以会话配置的形式传递到 C++ 层，最终由WebNNExecutionProvider解析；在 webnn_execution_provider.cc 中，provider 还会调用 WebNN 的opSupportLimits()获取当前实现对各算子的支持上限，用于更精确的能力判定。
• 如果模型含有动态维度，需要预先通过sessionOptions.freeDimensionOverrides固定形状，否则对应节点可能无法被 WebNN EP 接受（参考 helper.cc 中的日志提示）。

六、使用支持表的实操建议

1. 先对照 opset，再对照算子：模型导出的 opset 版本决定了检查哪一行。例如 opset 13 的模型，Reshape使用ai.onnx(13, 14-18, 19-20, 21+)段；opset 12 及以下则需检查对应旧段。低于 7 的 opset 不在官方保证范围内。
2. 逐条核对 Comments 列：即使算子名与 opset 命中，仍需检查属性与输入形态是否满足注释中的约束（如Conv的 3-D/4-D 输入、GatherND的batch_dims == 0、Pad不支持wrap模式、ScatterElements/ScatterND仅支持reduction == 'none'）。
3. 结合平台差异评估：表内支持不等于当前浏览器可运行。Chrome/Edge 各平台对 WebNN 的实现进度不同，最终以浏览器实际行为为准；排查失败时留意 WebNN 侧的opSupportLimits()返回值（WebNN EP 已在代码中用它做 rank 范围预检）。
4. 关注com.microsoft扩展域：GatherBlockQuantized、GroupQueryAttention、MatMulNBits、MultiHeadAttention、RotaryEmbedding、SkipLayerNormalization、SkipSimplifiedLayerNormalization来自 Microsoft 扩展域（com.microsoft(1+)），只有包含这些扩展算子的模型（多为 LLM/Transformer 结构）才会用到，普通 CNN 模型通常不涉及。

七、小结

WebNN EP 的算子支持表本质上回答了三个问题：哪些 ONNX 算子能被 WebNN 接管（Operator）、哪些 opset 版本区间可用（Opset）、底层用什么 WebNN API 实现（WebNN API）。配合 op_builder_factory.cc 的注册表、helper.cc 的能力检查逻辑，以及 builders/impl 下的逐算子实现，开发者可以在模型落地前准确预判兼容性，并在遇到节点下沉失败时快速定位是哪一类约束（常量输入、秩、属性、平台实现）导致的拒绝。需要继续深入算子级细节时，建议以 js/web/docs/webnn-operators.md 为总览，配合 WebNN status 与各*_op_builder.cc源文件交叉验证。

【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime