ContextQMD
Back to Onnxruntime

WebGPU Plugin Execution Provider

plugin-ep-webgpu/README.md

1.29.04.0 KB
Original Source

WebGPU Plugin Execution Provider

Packaging sources for the ONNX Runtime WebGPU plugin Execution Provider (EP), distributed as a standalone artifact that plugs into an existing ONNX Runtime installation rather than being built into the main onnxruntime binary.

For more information about plugin EPs, see the plugin EP libraries documentation.

Contents

  • VERSION_NUMBER — Base plugin EP version consumed by the CI pipeline. The pipeline derives the final package version (release, dev) from this via tools/ci_build/github/azure-pipelines/templates/set-plugin-ep-build-variables-step.yml.
  • MIN_ONNXRUNTIME_VERSION — Minimum compatible core onnxruntime version. Single source of truth shared by all packages built from this directory. The packages do not declare a hard dependency on a specific ONNX Runtime package; instead, this version string is injected into each package's README at build/pack time, and the native plugin EP code validates compatibility at registration time.
  • paths.txt — Specifies directories and paths that are related to the WebGPU EP. These paths are used to filter the commits considered when identifying changes between releases, e.g., for generating release notes.
  • python/ — Sources and build script for the onnxruntime-ep-webgpu Python wheel. See python/README.md for build and test instructions.
  • csharp/ — Sources and packaging script for the Microsoft.ML.OnnxRuntime.EP.WebGpu NuGet package. See csharp/README.md for build and test instructions.

How it fits together

The plugin EP is built as a shared library (onnxruntime_providers_webgpu.{dll,so,dylib}) by the main ONNX Runtime build (--use_webgpu shared_lib). The resulting binaries are then packaged into:

  • Per-platform Python wheels for onnxruntime-ep-webgpu, built from python/.
  • A multi-platform NuGet package Microsoft.ML.OnnxRuntime.EP.WebGpu, built from csharp/.
  • Per-platform zip packages for Foundry Local consumption.

On Windows, the packages also bundle the DirectX Shader Compiler runtime (dxil.dll, dxcompiler.dll) from the DXC GitHub releases; CI fetches these automatically.

Packaging is driven by the WebGPU Plugin EP Packaging Pipeline (plugin-webgpu-pipeline.yml), and post-build smoke tests run in the companion WebGPU Plugin EP Test Pipeline (plugin-webgpu-test-pipeline.yml).

The packaging pipeline only uploads its outputs as Azure DevOps pipeline artifacts — it does not push to PyPI, nuget.org, or the ORT-Nightly feed. Publishing to public feeds is handled by separate release pipelines.

Usage

Once installed, the plugin EP is registered at runtime. Example in Python:

python
import onnxruntime as ort
import onnxruntime_ep_webgpu as webgpu_ep

ort.register_execution_provider_library("webgpu", webgpu_ep.get_library_path())

# The WebGPU EP currently accepts one EP device and selects the physical GPU independently.
webgpu_ep_device = next((d for d in ort.get_ep_devices() if d.ep_name == webgpu_ep.get_ep_name()), None)
if webgpu_ep_device is None:
    raise RuntimeError("No WebGPU EP device found.")

sess_options = ort.SessionOptions()
sess_options.add_provider_for_devices([webgpu_ep_device], {})
session = ort.InferenceSession("model.onnx", sess_options=sess_options)

See the user-facing package READMEs (bundled into the published packages) for full per-language usage: