Windows ML WebGPU-Ausführungsanbieter (experimentell)

Der Windows ML WebGPU-Ausführungsanbieter (WebGPU EP) ist ein experimenteller GPU-Ausführungsanbieter, der den WebGPU-Standard (über DirectX 12) zum Ausführen von ONNX-Modellen über eine vielzahl von GPUs verwendet.

In Windows ML ist der primäre und empfohlene GPU-Pfad der IHV-spezifische Ausführungsanbieter für die jeweilige Hardware, z. B. MIGraphX oder VitisAI für AMD, NvTensorRtRtx für NVIDIA oder OpenVINO für Intel. DirectML ist als Fallback für die umfassende Kompatibilität auf Windows 11 24H2 und höher verfügbar, befindet sich jedoch im Wartungsmodus. WebGPU EP ist eine experimentelle Alternative, die nur für die nachstehend beschriebenen Szenarien vorgesehen ist.

WebGPU EP ist mit fast allen DirectX 12-fähigen GPUs kompatibel.

Licenses

WebGPU EP unterliegt zwei Lizenzen:

• Die WebGPU-EP-Lizenz für das Windows App SDK, die die Microsoft-Softwarelizenzbestimmungen enthält, welche die Verteilung des WebGPU-EP regeln.
• Die ONNX-Runtime-Lizenz, die die ONNX-Runtime-Komponenten umfasst, die in der WebGPU-EP enthalten sind.

Beide Lizenzen werden implizit akzeptiert, wenn die jeweiligen Pakete installiert und verwendet werden.

Wann soll WebGPU EP verwendet werden?

Erwägen Sie die Aktivierung von WebGPU EP in bestimmten Szenarien:

• Umfassende hardwareübergreifende Abdeckung: WebGPU EP kann GPU-Beschleunigung auf Geräten und Windows Versionen bereitstellen, in denen IHV-spezifische EPs nicht verfügbar sind, einschließlich älterer Hardware ohne dedizierte EP.

• Nicht unterstützte Operatoren: Wenn Ihr Modell Operatoren oder Features enthält, die in DirectML nicht optimiert sind, die zu einem CPU-Fallback führen, unterstützt WebGPU EP sie möglicherweise. Dies kann einen CPU-Fallback vermeiden und die Leistung verbessern.

• Standardsbasierte oder weborientierte Workflows: Wenn Sie sich an Webstandards (WebGPU) orientieren oder eine Brücke zwischen Browser- und nativen Szenarien schlagen, nutzt WebGPU EP dieselbe Technologie, die in modernen Browsern verfügbar ist. Dies kann die plattformübergreifende ML-Entwicklung und -Tests vereinfachen. Beispielsweise kann ein Modell, das mit ONNX Runtime Web + WebGPU im Browser prototypiert ist, WebGPU EP in einer nativen Windows ML-App verwenden, um ein konsistentes Verhalten zu erzielen.

Einschränkungen

Beachten Sie vor dem Aktivieren von WebGPU EP die folgenden Einschränkungen:

• Leistung: WebGPU EP ist ein Early-Stage-Anbieter und wird noch nicht für leistungskritische oder ultraoptimierte Workloads empfohlen. Groß angelegte Inferenz-Pipelines, die einen maximalen Durchsatz erfordern, sollten weiterhin herstellerspezifische EPs oder DirectML verwenden.

• Präzisionsunterstützung: WebGPU EP unterstützt derzeit die FP32/FP16-Inferencing- und INT4/INT8-Quantisierung für LLMs. Quantisierte Nicht-LLM-INT8-Modelle werden auf dem WebGPU-Pfad nicht unterstützt: Solche Modelle werden in höherer Präzision ausgeführt oder können auf die CPU zurückfallen, wodurch die Leistungsvorteile zunichtegemacht werden.

• Treiber und Betriebssystem: WebGPU EP verwendet das Chromium Dawn-Modul über Direct3D 12. Erforderlich ist eine moderne DirectX 12-fähige GPU mit aktuellen Treibern. Die Verwendung von WebGPU EP auf veralteten Treibern oder Legacyhardware kann zu Inkompatibilität führen.

• Empfohlene Hardware: Verwenden Sie für eine zuverlässige Erfahrung aktuelle GPUs, ungefähr 11. Generation Intel integrierte Grafiken oder NVIDIA Turing-Klasse und neuer. Diese bieten die DirectX-Featureebene (12_0+) und die Treiberreife, die WebGPU EP erwartet. Ältere GPUs können weiterhin ausgeführt werden, können aber Treiber- oder Kompatibilitätsprobleme haben.

• Modellkompatibilität: WebGPU EP reagiert empfindlich auf Modellgraphen und die Unterstützung von Operatoren. Wenn bestimmte Operatoren nicht unterstützt werden, partitioniert DIE ONNX-Runtime die Ausführung, sodass nicht unterstützte Teile auf der CPU ausgeführt werden. Dies kann zu gemischter CPU/GPU-Ausführung und unvorhersehbarer Leistung führen. Überprüfen Sie mithilfe von Windows ML-Protokollen oder Profilingtools, ob der gesamte Graph Ihres Modells mit dem WebGPU EP ausgeführt wird.

Voraussetzungen

Um WebGPU EP zu verwenden, benötigen Sie Folgendes:

• Windows 11, Version 24H2 (Build 26100) oder höher. Windows ML-Ausführungsanbieter werden nur auf 24H2 und höher unterstützt.
• Die experimentellen Versionen der Windows ML NuGet-Pakete, die in Ihrem Projekt installiert sind.

WebGPU EP aktivieren

Um WebGPU EP zu verwenden, müssen Sie die verfügbaren Anbieter aufzählen, WebGPU EP explizit installieren und registrieren, es an eine Sitzung binden und die Registrierung aufheben, wenn Sie fertig sind. Der Aufruf von EnsureAndRegisterCertifiedAsync()installiert WebGPU EP nicht, daher müssen Sie diese Schritte selbst durchführen. Das folgende Beispiel zeigt die vollständige Sequenz; die Schritte werden unter "Grundlegendes zu den Schritten nach dem Code" erläutert.

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.ML.OnnxRuntime;
using Microsoft.Windows.AI.MachineLearning;

const string WebGpuEpName = "WebGpuExecutionProvider";

// 1. Enumerate providers and find the WebGPU EP by name.
var catalog = ExecutionProviderCatalog.GetDefault();
var webGpuProvider = catalog.FindAllProviders()
    .FirstOrDefault(p => p.Name == WebGpuEpName);

if (webGpuProvider is null)
{
    Console.WriteLine("WebGPU EP is not available on this device.");
    return;
}

// 2. Install (downloads if needed) and register the EP with ONNX Runtime.
var result = await webGpuProvider.EnsureReadyAsync();
if (result.Status != ExecutionProviderReadyResultState.Success || !webGpuProvider.TryRegister())
{
    Console.WriteLine("Failed to install or register WebGPU EP.");
    return;
}

// 3. Select the WebGPU EP device and create a session bound to it.
var env = OrtEnv.Instance();
var webGpuEpDevice = env.GetEpDevices().FirstOrDefault(d => d.EpName == WebGpuEpName);
if (webGpuEpDevice is null)
{
    Console.WriteLine("WebGPU EP is not available on this device.");
    return;
}

using (var sessionOptions = new SessionOptions())
{
    sessionOptions.AppendExecutionProvider(env, new[] { webGpuEpDevice }, new Dictionary<string, string>());

    using var session = new InferenceSession("model.onnx", sessionOptions);
    // Run inference...
}

// 4. Unregister the EP library before the environment is torn down.
env.UnregisterExecutionProviderLibrary(WebGpuEpName);

#include <winrt/Microsoft.Windows.AI.MachineLearning.h>
#include <winml/onnxruntime_cxx_api.h>

using namespace winrt::Microsoft::Windows::AI::MachineLearning;

const std::string webGpuEpName = "WebGpuExecutionProvider";

// 1. Enumerate providers and find the WebGPU EP by name.
auto catalog = ExecutionProviderCatalog::GetDefault();
ExecutionProvider webGpuProvider{ nullptr };
for (auto const& provider : catalog.FindAllProviders())
{
    if (winrt::to_string(provider.Name()) == webGpuEpName)
    {
        webGpuProvider = provider;
        break;
    }
}

if (!webGpuProvider)
{
    // WebGPU EP is not available on this device.
    return;
}

// 2. Install (downloads if needed) and register the EP with ONNX Runtime.
auto result = webGpuProvider.EnsureReadyAsync().get();
if (result.Status() != ExecutionProviderReadyResultState::Success || !webGpuProvider.TryRegister())
{
    // Failed to install or register WebGPU EP.
    return;
}

// 3. Select the WebGPU EP device and create a session bound to it.
Ort::Env env;
std::vector<Ort::ConstEpDevice> selectedEpDevices;
for (auto const& epDevice : env.GetEpDevices())
{
    if (epDevice.EpName() && webGpuEpName == epDevice.EpName())
    {
        selectedEpDevices.push_back(epDevice);
        break;
    }
}

if (selectedEpDevices.empty())
{
    // WebGPU EP is not available on this device.
    return;
}

Ort::SessionOptions sessionOptions;
sessionOptions.AppendExecutionProvider_V2(env, selectedEpDevices, Ort::KeyValuePairs{});

{
    Ort::Session session(env, L"model.onnx", sessionOptions);
    // Run inference...
}

// 4. Unregister the EP library after the session is destroyed, before the
//    environment is torn down.
env.UnregisterExecutionProviderLibrary(webGpuEpName.c_str());

import onnxruntime as ort
import windowsml as winml

WEBGPU_EP_NAME = "WebGpuExecutionProvider"

# 1. Enumerate providers and find the WebGPU EP by name.
catalog = winml.EpCatalog()
web_gpu = next(
    (p for p in catalog.find_all_providers() if p.name == WEBGPU_EP_NAME), None
)
if web_gpu is None:
    raise SystemExit("WebGPU EP is not available on this device.")

# 2. Install (downloads if needed) and register the EP with ONNX Runtime.
web_gpu.ensure_ready()
ort.register_execution_provider_library(WEBGPU_EP_NAME, web_gpu.library_path)

# 3. Select the WebGPU EP device and create a session bound to it.
ep_devices = [d for d in ort.get_ep_devices() if d.ep_name == WEBGPU_EP_NAME]
if not ep_devices:
    raise SystemExit("WebGPU EP is not available on this device.")

session_options = ort.SessionOptions()
session_options.add_provider_for_devices(ep_devices, {})

session = ort.InferenceSession("model.onnx", session_options)
# Run inference...

# 4. Unregister the EP library before the process exits.
del session
ort.unregister_execution_provider_library(WEBGPU_EP_NAME)

Grundlegendes zu den Schritten

Im vorherigen Beispiel werden die Download-, Installations- und Registrierungsphasen getrennt, die WebGPU EP erfordert:

• Aufzählen: FindAllProviders() Listet die anbieter auf, die auf dem Gerät verfügbar sind. WebGPU EP wird nur in der Liste angezeigt, wenn das experimentelle Paket installiert ist.
• Herunterladen und Installieren: EnsureReadyAsync() lädt das EP-Paket herunter, wenn es noch nicht vorhanden ist, und installiert es lokal. Dies ist der Schritt, den EnsureAndRegisterCertifiedAsync() bei WebGPU EP überspringt, daher müssen Sie ihn explizit aufrufen.
• Register: TryRegister() registriert die installierte EP-Bibliothek mit ONNX-Runtime, damit eine Sitzung sie auswählen kann. GetEpDevices() gibt nach der Registrierung die verfügbaren EP-Geräte zurück. Ein EP-Gerät (OrtEpDevice) stellt einen Ausführungsanbieter dar, der mit einem bestimmten Hardwaregerät gekoppelt ist, auf dem es ausgeführt werden kann. Er identifiziert sowohl den Anbieter (über sein EpName) als auch das zugrunde liegende Hardwaregerät, anstatt ein Hardwaregerät selbst. Wählen Sie das EP-Gerät aus, dessen EpName Übereinstimmungen mit WebGPU EP übereinstimmen, und binden Sie es dann an Ihre Sitzungsoptionen.
• Registrierung aufheben: UnregisterExecutionProviderLibrary() Entfernt die Registrierung, bevor die Umgebung heruntergerissen wird.

Anbieterspezifische Optionen finden Sie in der ONNX WebGPU Execution Provider-Dokumentation. Nachdem Sie die WebGPU-EP zum Laufen gebracht haben, bewerten Sie ihre Leistung und ihr Verhalten auf Ihrer Zielhardware. Verwenden Sie Ihre Benchmarking-Daten, um Entscheidungen bei der Einführung zu leiten, und bleiben Sie auf dem neuesten Stand, da das WebGPU EP im Laufe der Zeit neue Verbesserungen hinzufügt.

Melden von Problemen

Alle Probleme mit WebGPU EP im Windows ML GitHub Repository ablegen. Wenn das Windows ML-Team feststellt, dass ein Problem für DIE ONNX-Runtime spezifisch ist, kann es in das ONNX-Runtime-GitHub-Repository übertragen werden.

Siehe auch

• Windows ML-Ausführungsanbieter
• Beschleunigen von KI-Modellen
• Auswählen von Ausführungsanbietern
• Erfassen von Protokollen