Repository navigation
[WebGPU] Add enableFeatures and disableFeatures for EP feature management - #33481
Jianhui Dai (daijh) wants to merge 3 commits into
Conversation
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
There was a problem hiding this comment.
🟡 Changes recommended
The Node.js parser rejects the newly exposed option, breaking the documented Node.js usage.
1 open issue
What changed in this PR
Adds a WebGPU provider option to disable subgroup matrix kernels and use fallbacks, including with externally supplied devices.
Changes:
- Exposes the option in shared JavaScript types and forwards it through WebAssembly.
- Adds native parsing, feature filtering, and first-context-wins warnings.
- Tests invalid values, shared contexts, and external devices.
| File | Description |
|---|---|
| onnxruntime/test/providers/webgpu/webgpu_context_test.cc | Tests option validation and feature masking. |
| onnxruntime/core/providers/webgpu/webgpu_provider_options.h | Defines option keys and values. |
| onnxruntime/core/providers/webgpu/webgpu_provider_factory.cc | Parses the boolean option. |
| onnxruntime/core/providers/webgpu/webgpu_context.h | Stores configuration and context state. |
| onnxruntime/core/providers/webgpu/webgpu_context.cc | Filters features and warns on conflicting settings. |
| js/web/lib/wasm/session-options.ts | Forwards the option to native WebGPU. |
| js/common/lib/inference-session.ts | Declares and documents the JavaScript option. |
Review effort: Balanced
0e89b82 to
74db9f0
Compare
Add a WebGPU EP option to disable subgroup matrix kernels and use their
fallbacks, including with an externally supplied device. The option is
first-context-wins: a later conflicting or omitted value on an existing
context logs a warning, matching enableRobustness.
Usage:
onnxruntime-web / onnxruntime-node (JS):
const session = await ort.InferenceSession.create(model, {
executionProviders: [{ name: 'webgpu', disableSubgroupMatrix: true }],
});
With a custom GPU device:
executionProviders: [{ name: 'webgpu', device, disableSubgroupMatrix: true }]
C++ provider options / session config entry (accepts "0" or "1"):
session_options.AddConfigEntry(
"ep.webgpuexecutionprovider.disableSubgroupMatrix", "1");
The shared InferenceSession type exposes disableSubgroupMatrix, but the
Node parser rejected it as an unrecognized WebGPU EP option. Validate it
as a boolean and forward it as "1"/"0", like enableRobustness, and add a
regression test.
Usage (onnxruntime-node):
const session = await ort.InferenceSession.create(model, {
executionProviders: [{ name: 'webgpu', disableSubgroupMatrix: true }],
});
74db9f0 to
66cb95b
Compare
|
I like the overall idea, which will make the tests easier and applications more flexible. Could we consider introducing generic enableFeatures / disableFeatures options for the WebGPU EP? As we add more boolean feature switches, dedicated properties like disableSubgroupMatrix will keep expanding the options interface and require corresponding parsing changes across the native, browser, and Node bindings. For example: executionProviders: [{ A shared feature registry could define supported names, defaults, and validation, while the bindings forward the lists generically. Unknown or conflicting entries should be rejected, and enabling a feature should still respect hardware capabilities. We would also need to document each feature’s scope: this option is first-context-wins, whereas others may be per-session or device-creation-only. Numeric and enum settings could remain explicit typed options. subgroupMatrix seems like a good first entry for this mechanism. Would this be a reasonable direction before adding another dedicated boolean option? |
That is an quite good suggestion. Let's hold this PR a few days to allow time for additional feedback. |
…tures
Replace the boolean disableSubgroupMatrix option with generic
enableFeatures and disableFeatures lists of named WebGPU EP features.
"subgroupMatrix" is the only feature today. The feature registry is
independent of WebGPU device features; the context maps each feature to
the device capabilities it gates, including on externally supplied
devices.
Settings are first-context-wins: a conflicting explicit request on an
existing context logs a warning and is ignored. Unknown names,
duplicates, names in both lists, and empty names are rejected. Native
lists are comma-separated with surrounding whitespace trimmed.
Usage:
JS (onnxruntime-web / onnxruntime-node):
executionProviders: [{ name: 'webgpu', disableFeatures: ['subgroupMatrix'] }]
C++ provider options / session config entry:
session_options.AddConfigEntry(
"ep.webgpuexecutionprovider.disableFeatures", "subgroupMatrix");
Jianhui Dai (daijh)
changed the title
|
Add |
Description
Introduce generic
enableFeaturesanddisableFeatureslists for named WebGPU EP features, initially supportingsubgroupMatrix.The feature registry is independent of WebGPU device features. The context maps each feature to the specific device capabilities it gates, including on externally supplied devices.
This allows disabling subgroup matrix kernels to force fallbacks, following a first-context-wins policy where later conflicting or omitted values log a warning similar to
enableRobustness.Usage:
JS (onnxruntime-web / onnxruntime-node):
C++ provider options / session config entry:
Motivation and Context
See above.