microsoft / microsoft/onnxruntime

[Documentation] WebGPU docs show `Conv` supports `11+`, but JS EP only matches opset 11 (Conv‑22 fails)

Open
#27,231 0 comments 0 reactions 0 assignees View on GitHub
documentation ep:WebGPU platform:web
Dominant language
C++
Stars
21.9k
Forks
4.2k
Avg merge
4d 11h
Merged PRs (30d)
184

Description

Hi team — I ran into a mismatch between WebGPU operator docs and actual kernel matching for Conv in onnxruntime‑web.

### What I observed

- The generated docs `js/web/docs/webgpu-operators.md` show:

https://github.com/microsoft/onnxruntime/blob/25a6fdcaab9901c6822aaec64bae9daf24d4fa68/js/web/docs/webgpu-operators.md?plain=1#L32

- But in practice, Conv‑22 nodes fail on WebGPU with “kernel not found” (falls back to CPU execution).
- Re‑exporting the model to opset 21 makes it run (uses Conv-11 which is the version preceding Conv-22).

### Why this happens

The WebGPU docs are generated by `js/web/script/generate-webgpu-operator-md.ts` by parsing kernel registrations in:

- `onnxruntime/core/providers/js/js_execution_provider.cc`
- `onnxruntime/core/providers/js/operators/conv.cc`

In those files, Conv is registered as:

- `1-10` via `ONNX_OPERATOR_VERSIONED_KERNEL_EX`
- `11` via `ONNX_OPERATOR_KERNEL_EX`

In ORT kernel matching, `ONNX_OPERATOR_KERNEL_EX(..., 11, ...)` sets `SinceVersion(11)` **without an end version** (leaving the [default value INT_MAX](https://github.com/microsoft/onnxruntime/blob/25a6fdcaab9901c6822aaec64bae9daf24d4fa68/include/onnxruntime/core/framework/kernel_def_builder.h#L114)), and kernel matching only treats it as **exactly 11**, not “11+”. This is enforced in `onnxruntime/core/framework/kernel_registry.cc`:

https://github.com/microsoft/onnxruntime/blob/25a6fdcaab9901c6822aaec64bae9daf24d4fa68/onnxruntime/core/framework/kernel_registry.cc#L126-L133

So Conv‑22 does not match the “11” kernel and fails.

### Impact

- Docs say `11+`, but the WebGPU EP rejects Conv‑22.
- This is confusing for users and leads to unexpected runtime failures.

### Suggested fixes

Either:
1. Update the docs generator to avoid showing `11+` for `ONNX_OPERATOR_KERNEL_CLASS_NAME(..., 11, ...)` unless a version range is registered, **or**
2. Register Conv explicitly for `11–21` and `22` (matching native WebGPU EP style), so the docs become true.

### Repro

- Any model with opset import 22 and a `Conv` node fails on `onnxruntime-web` WebGPU.
- The same model converted to opset 11 runs.

I’m happy to submit a PR if desired — just confirm the preferred direction (doc fix vs. kernel registration).

Thanks!

### Page / URL

_No response_

Contributor guide

Open the contributing guide

Research direction

Start with js/web/script/generate-webgpu-operator-md.ts and compare its output with the Conv registrations in onnxruntime/core/providers/js/js_execution_provider.cc and onnxruntime/core/providers/js/operators/conv.cc. Read the matching behavior in onnxruntime/core/framework/kernel_registry.cc before choosing between correcting generation and adding explicit registrations. Done means the documented Conv versions match WebGPU behavior and the Conv-22 reproduction is addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, typescript
Domain
documentation, machine-learning, web-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.