[WebGPU] Refactor MatMul algorithm selection

[Jiajia Qin (qjia7)]

Description

• Introduce explicit WebGPU MatMul algorithm enums for subgroup matrix, naive, Intel subgroup, packed, and packed Split-K implementations.
• Add a MatMul scheduler with this priority: forced test algorithm, zero-K correctness guard, vendor policy, then a private common fallback.
• Allow vendor schedulers to choose any algorithm with vendor-specific thresholds and independently tune the selected algorithm's execution configuration.
• Represent algorithm and typed configuration together in a MatMulExecutionPlan. Packed tuning includes workgroup size, elements per thread, inner tile size, and Split-K size.
• Move the existing Intel Split-K architecture profiles and measured threshold tables under vendor/intel while keeping eligibility evaluation in the generic SplitKConfig.
• Route adapter-specific Split-K profiles through a generic factory owned by WebGpuContext, so GEMM and MatMul share the same immutable policy.
• Keep forced-algorithm tests on the real vendor tuning path through the test-only ep.webgpuexecutionprovider.forceMatmulAlgorithm session option.
• Route MatMul, pointwise Conv, and contrib Attention through MatMulComputeDispatcher, dispatch directly from the selected enum, and validate algorithm prerequisites and packed tuning before execution.
• Document the architecture in docs/design/webgpu_matmul_algorithm_scheduler.md.

Motivation and Context

WebGPU MatMul chooses among several implementations using shape, capability, and vendor-specific conditions. Keeping these choices as distributed conditionals made individual implementations difficult to force in tests and made vendor thresholds difficult to evolve.

This refactor separates immutable problem facts, algorithm policy, execution tuning, and dispatch. A vendor can override performance boundaries, supply a Split-K profile, or tune execution parameters without changing MatMulComputeDispatcher, while returning no selection or configuration delegates to the common defaults.

Behavior and Compatibility

• The common scheduler retains the existing subgroup-matrix, small-matrix naive, Split-K, and packed rules as its fallback.
• Intel preserves its original priority: subgroup matrix, Intel subgroup, then common fallback.
• Intel's existing legacy, discrete/Lunar Lake, Xe3, and default Split-K boundaries are unchanged.
• Automatic selection always uses the Naive path when K is zero before consulting vendor policy. Forced algorithms still take precedence, and the dispatcher rejects forced algorithms whose hard prerequisites exclude zero-K inputs.
• Existing subgroup-matrix vendor tiling remains in its dedicated selector.
• NVIDIA Split-K policy from [WebGPU] Enable Split-K on reported-Pascal NVIDIA adapters #32333 is intentionally not included; this PR only provides the extension point it can use.
• The PR does not change WebGPU build configuration or dependency configuration.

Validation

• Built the static and plugin-adapter onnxruntime_provider_test targets on Windows.
• All 37 targeted scheduler, Split-K profile, prerequisite, forced-algorithm, zero-K, and MatMul execution tests passed with the Vulkan WebGPU build.
• Forced FP16 subgroup-matrix execution passed on Intel Arc 140V with Vulkan cooperative-matrix support.
• Hardware-backed MatMul tests use the build's default WebGPU backend and inspect the selected adapter before running capability-specific algorithms.
• Added regression coverage for vendor-first selection, vendor tuning of forced algorithms, independent Split-K thresholds, Intel profile routing and boundaries, packed Z-axis invariants, Split-K tile alignment, overflow-safe dispatch arithmetic, and per-invocation reselection for dynamic shapes.

[Copilot]

🟡 Changes recommended

Intel eligibility misses a shape constraint, and hardware-specific tests do not skip unsupported adapters.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Centralizes WebGPU MatMul algorithm selection and enables explicit path testing.

Changes:

• Adds enum-based common and Intel-specific scheduling.
• Adds forced-algorithm configuration and coverage.
• Supports Vulkan-only Dawn builds on Windows.

File summaries

File	Description
onnxruntime/test/providers/webgpu/matmul_large_test.cc	Adds forced-path integration tests.
onnxruntime/test/providers/webgpu/matmul_algorithm_scheduler_test.cc	Tests parsing, scheduling, and prerequisites.
onnxruntime/core/providers/webgpu/webgpu_provider_options.h	Declares the forcing option.
onnxruntime/core/providers/webgpu/webgpu_provider_factory.cc	Parses and validates the option.
onnxruntime/core/providers/webgpu/webgpu_execution_provider.h	Stores forced selection state.
onnxruntime/core/providers/webgpu/webgpu_execution_provider.cc	Initializes forced selection state.
onnxruntime/core/providers/webgpu/vendor/intel/math/matmul.h	Exposes Intel capability detection.
onnxruntime/core/providers/webgpu/vendor/intel/math/matmul.cc	Separates capability from heuristics.
onnxruntime/core/providers/webgpu/vendor/intel/math/matmul_algorithm_scheduler.h	Implements Intel scheduling policy.
onnxruntime/core/providers/webgpu/math/subgroup_matrix_matmul.cc	Separates applicability from execution.
onnxruntime/core/providers/webgpu/math/matmul.h	Extends implementation and scheduler caches.
onnxruntime/core/providers/webgpu/math/matmul.cc	Implements scheduling and direct dispatch.
onnxruntime/core/providers/webgpu/math/matmul_algorithm.h	Defines algorithm identities and conversion.
onnxruntime/core/providers/webgpu/math/matmul_algorithm_scheduler.h	Defines common scheduling and prerequisites.
onnxruntime/core/providers/webgpu/compute_context.h	Exposes forced selection to kernels.
docs/superpowers/specs/2026-09-16-webgpu-matmul-algorithm-scheduler-design.md	Documents the design.
docs/superpowers/plans/2026-09-16-webgpu-matmul-algorithm-scheduler.md	Records the implementation plan.
cmake/external/onnxruntime_external_deps.cmake	Configures Vulkan-only Windows Dawn builds.

Review details

• Files reviewed: 15/18 changed files
• Comments generated: 1
• Review effort level: Balanced (auto)

Note

Copilot is running an experiment and ran this review at Balanced.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Forced Intel dispatch can accept small shapes that violate the subgroup kernel’s vec4-load invariant.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 15/18 changed files
• Comments generated: 2
• Review effort level: Balanced (auto)

Note

Copilot is running an experiment and ran this review at Balanced.

[Copilot]

Copilot review overview

🟡 Changes recommended

Forced Packed zero-K inputs and low-M Intel execution expose unsupported shader paths.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Forced packed MatMul mishandles zero-contraction dimensions · New
• Forced Intel subgroup is accepted with only vendor and feature checks, but the kernel still has a…
• This branch now explicitly supports Vulkan-only Windows builds, so the adjacent statement that the…

[Copilot]

Copilot review overview

🟡 Changes recommended

Forced Intel subgroup dispatch mishandles zero-K inputs, and the new zero-K test invokes undefined pointer arithmetic.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Reject zero-K MatMul when forcing intel_subgroup · New
• Avoid forming input pointers for zero-K expected results · New

Resolved since last review (3)

• Forced packed MatMul mishandles zero-contraction dimensions
• Forced Intel subgroup is accepted with only vendor and feature checks, but the kernel still has a…
• This branch now explicitly supports Vulkan-only Windows builds, so the adjacent statement that the…

Previously missed (1)

In code that hasn't changed since last review

Align PR description with implemented Vulkan build changes

docs/​design/​webgpu_matmul_algorithm_scheduler.md:62

The PR description still claims this change adds Vulkan-only Windows Dawn/system-Vulkan build support, but this diff changes no build or dependency files; this line only records a validation configuration, and forcing dawnBackendType=Vulkan requires that backend to already be built. Remove that feature claim from the PR description (or restore the corresponding build implementation) so the stated scope matches the changes.

[Copilot]

Copilot review overview

🟡 Changes recommended

The subgroup-matrix capability probe can run an expected-success test when the runtime implementation remains unavailable.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Skip probe when SubgroupSizeControl is unavailable · New
• Document Naive selection when K equals zero · New

Resolved since last review (2)

• Reject zero-K MatMul when forcing intel_subgroup
• Avoid forming input pointers for zero-K expected results

[Copilot]

Copilot review overview

🟡 Changes recommended

Zero-contraction MatMul dispatch can bind null buffers, and one new test fails when the plugin EP is unavailable.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Handle zero-contraction MatMul without binding null buffers · New

Resolved since last review (2)

• Skip probe when SubgroupSizeControl is unavailable
• Document Naive selection when K equals zero

Previously missed (1)

In code that hasn't changed since last review

Skip WebGPU invalid-option test when provider is unavailable

onnxruntime/​test/​providers/​webgpu/​matmul_large_test.cc:233

In ORT_USE_EP_API_ADAPTERS builds, WebGpuExecutionProviderWithOptions returns nullptr before parsing options when the dynamic plugin is uninitialized (test/util/default_providers.cc:379-388). Consequently this EXPECT_THROW observes no exception and fails in configurations where WebGPU is legitimately unavailable. Probe provider availability with a valid configuration and GTEST_SKIP() before asserting that the invalid option throws.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Hardware-specific GPU dispatch and capability handling merit final maintainer review despite comprehensive focused coverage.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Handle zero-contraction MatMul without binding null buffers

[Copilot]

Copilot review overview

🔵 Needs a closer look

The hardware-dependent dispatch refactor spans multiple kernels and requires final maintainer validation across supported GPU backends.

Review effort: Balanced
Findings: 1

Open (1)

• Disallow copy and move operations for MatMulAlgorithmScheduler · New

[Jiajia Qin (qjia7)]

Review frame

• Problem/feature validity: Validated. Before this PR, ComputeMatMul selected subgroup-matrix, naive, Intel subgroup, Split-K, and packed implementations through distributed conditionals, which prevented a test from selecting one implementation independently and coupled vendor thresholds to dispatch. The diff centralizes that policy while preserving the existing automatic order and keeps execution-specific validation at the dispatch boundary.
• Risk/scope: Deep. This changes algorithm selection for MatMul and the pointwise-Conv caller, exposes a test-only provider option, changes subgroup-matrix applicability/dispatch, and threads packed tuning into shader generation and cache keys across Metal, D3D12, and Vulkan.
• Direction gate: Pass. As the owner solution, I would keep immutable problem facts, vendor policy, hard prerequisites, typed execution configuration, and final dispatch separate. The PR now follows that boundary: vendor policy can decline to the private common fallback, forced selection still uses real vendor tuning, and unsupported forced paths fail rather than silently changing algorithms.

Confirmed findings

T1: Skip the invalid-option test when the plugin EP is unavailable

onnxruntime/test/providers/webgpu/matmul_large_test.cc:233-236

This test assumes WebGpuExecutionProviderWithOptions() reaches WebGPU option parsing. In an ORT_USE_EP_API_ADAPTERS Windows build where the dynamic plugin has not been initialized, however, onnxruntime/test/util/default_providers.cc:366-389 returns nullptr before forwarding any configuration to the plugin. EXPECT_THROW therefore observes a normal null return and fails even though WebGPU is legitimately unavailable. This PR introduces that failure in a supported build configuration, and the plugin build check does not execute this provider test.

Please first construct the provider with a valid configuration and GTEST_SKIP() when that returns null, then run the invalid-option assertion. That preserves parser coverage when the plugin is present without turning provider unavailability into a test failure.

Q1: Disable copy and move on the new polymorphic scheduler

onnxruntime/core/providers/webgpu/math/matmul_algorithm_scheduler.h:150-153

MatMulAlgorithmScheduler is a new polymorphic base class but remains implicitly copyable and movable. Repository guidance requires new classes to use ORT_DISALLOW_COPY_ASSIGNMENT_AND_MOVE until those operations are shown to be necessary. Applying the macro to this base class also covers the Intel and test subclasses and prevents accidental value copies or slicing as more vendor schedulers are added.

Clarifications

None.

Test coverage

The device-independent tests cover parser behavior, selection precedence, common thresholds, typed packed configuration, Split-K prerequisites, overflow-safe dispatch arithmetic, and Intel low-M vec4 eligibility. Hardware tests compare deterministic results with a CPU reference and gate Intel subgroup, Split-K, and subgroup-matrix success cases on the selected adapter's actual capabilities. The automatic zero-K execution test also exercises the new no-input-binding shader path.

At the reviewed head, the macOS-arm64 WebGPU Release legs passed and the Linux WebGPU build passed; several unrelated or additional matrix jobs, including macOS WebGPU Debug and Windows plugin/build variants, were still pending. Linux WebGPU remains build-only, so it is not execution evidence. T1 remains uncovered because the plugin build leg does not run this test.

Verdict

The feature is valid and the scheduler/typed-plan direction is appropriate. T1 blocks merge because the new test fails in a supported plugin configuration. There are no remaining clarification requests. Q1 is mechanical cleanup required by the repository's new-class convention and does not change runtime behavior.

[github-actions]

You can commit the suggested changes from lintrunner.

[Jiajia Qin (qjia7)]

Jie Chen (@jchen10) Yang Gu (@gyagp), please take a look, thanks.

[Jie Chen (jchen10)]

IntelSubgroup is slightly weird here. Can we use Subgroup instead?

[Jie Chen (jchen10)]

algorithm, scheduler, and dispatcher headers all use inline. It seems unusual.

[Jie Chen (jchen10)]

A brief comment may improve readability for classes of new concept, like scheduler, plan, configuration, prerequisite, etc.

[Jie Chen (jchen10)]

What about making the scheduler not return a valid plan if configuration is not compatible or prerequisites are not met?