Windows provider di esecuzione WebGPU ml (sperimentale)

Il provider di esecuzione WebGPU (WEBGPU EP) di ML Windows è un provider di esecuzione GPU sperimentale che usa lo standard WebGPU (tramite DirectX 12) per eseguire modelli ONNX in un'ampia gamma di GPU.

In Windows ML, il percorso GPU primario e consigliato è il provider di esecuzione specifico di IHV per l'hardware, ad esempio MIGraphX o VitisAI per AMD, NvTensorRtRtx per NVIDIA o OpenVINO per Intel. DirectML è disponibile come fallback per la compatibilità generale in Windows 11 24H2 e versioni successive, ma è in modalità di manutenzione. WebGPU EP è un'alternativa sperimentale destinata solo agli scenari descritti di seguito in questo momento.

WebGPU EP è compatibile con quasi tutte le GPU con supporto per DirectX 12.

Licenze

WebGPU EP è governato da due licenze:

• WebGPU EP per SDK per app di Windows License, che contiene le Condizioni di licenza software Microsoft che regolano la distribuzione del PACCHETTO WebGPU.
• La licenza di runtime ONNX, che copre i componenti di runtime ONNX inclusi nell'EP WebGPU.

Entrambe le licenze vengono accettate in modo implicito quando i rispettivi pacchetti vengono installati e usati.

Quando usare WebGPU EP

Prendere in considerazione l'abilitazione di WebGPU EP in scenari specifici:

• Ampia copertura tra hardware: WebGPU EP può fornire accelerazione GPU nei dispositivi e versioni Windows in cui gli EP specifici di IHV non sono disponibili, incluso l'hardware meno recente senza un EP dedicato.

• Operatori non supportati: se il modello contiene operatori o funzionalità non ottimizzati in DirectML che causano un fallback della CPU, WebGPU EP potrebbe supportarli. Ciò può potenzialmente evitare il fallback della CPU, migliorando le prestazioni.

• Flussi di lavoro basati su standard o web-first: se si è in linea con gli standard Web (WebGPU) o il bridging di uno scenario browser/nativo, WebGPU EP usa la stessa tecnologia disponibile nei browser moderni. In questo modo è possibile semplificare lo sviluppo e il test di Machine Learning multipiattaforma. Ad esempio, un modello prototipo con ONNX Runtime Web + WebGPU nel browser può usare WebGPU EP in un'app nativa Windows ML per ottenere un comportamento coerente.

Limitations

Prima di abilitare WebGPU EP, tenere presente le limitazioni seguenti:

• Prestazioni: WebGPU EP è un provider in fase iniziale e non è ancora consigliato per carichi di lavoro estremamente critici o ultra ottimizzati per le prestazioni. Le pipeline di inferenza su larga scala che richiedono la velocità effettiva massima devono continuare a usare gli EP del fornitore o DirectML.

• Supporto della precisione: WebGPU EP supporta attualmente l'inferenza FP32/FP16 e la quantizzazione INT4/INT8 per le macchine virtuali. I modelli non LLM INT8 quantizzati non sono supportati nel percorso WebGPU: tali modelli verranno eseguiti con precisione più elevata o potrebbero eseguire il fallback alla CPU, negando i vantaggi delle prestazioni.

• Driver e sistema operativo: WebGPU EP usa il motore Chromium Dawn su Direct3D 12. Richiede una GPU moderna con supporto per DirectX 12 con driver up-to-date. L'uso di WebGPU EP su driver obsoleti o hardware legacy può causare incompatibilità.

• Hardware consigliato: per un'esperienza affidabile, usare GPU recenti, approssimativamente 11th-gen Intel integrated graphics o NVIDIA Turing-class e versioni successive. Questi forniscono il livello di funzionalità DirectX (12_0+) e la maturità del driver prevista da WebGPU EP. Le GPU meno recenti possono essere ancora eseguite, ma potrebbero essere soggette a problemi di compatibilità o driver.

• Compatibilità dei modelli: WebGPU EP è sensibile ai grafici dei modelli e al supporto degli operatori. Se alcuni operatori non sono supportati, ONNX Runtime partizionerà l'esecuzione in modo che le parti non supportate vengano eseguite sulla CPU. Ciò può causare un'esecuzione mista di CPU/GPU e prestazioni imprevedibili. Controllare se l'intero grafo del modello viene eseguito in WebGPU EP usando Windows strumenti di profilatura o log di Machine Learning.

Prerequisiti

Per usare WebGPU EP, è necessario:

• Windows 11 versione 24H2 (build 26100) o successiva. Windows provider di esecuzione ml sono supportati solo su 24H2 e versioni successive.
• Le versioni sperimentali dei pacchetti NuGet Windows ML installati nel progetto.

Abilitare WebGPU EP

Per usare WebGPU EP, enumerare i provider disponibili, installare e registrare in modo esplicito il pacchetto EP WebGPU, associarlo a una sessione e annullarne la registrazione al termine. La chiamata EnsureAndRegisterCertifiedAsync()non installa WebGPU EP, quindi è necessario eseguire manualmente questi passaggi. L'esempio seguente mostra la sequenza completa; I passaggi sono illustrati in Comprendere i passaggi successivi al codice.

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)

Comprendere i passaggi

L'esempio precedente separa le fasi di download, installazione e registrazione richieste da WebGPU EP:

• Enumerazione: FindAllProviders() elenca i provider disponibili nel dispositivo. WebGPU EP viene visualizzato nell'elenco solo quando viene installato il pacchetto sperimentale.
• Scaricare e installare: EnsureReadyAsync() scarica il pacchetto EP se non è già presente e lo installa in locale. Questo è il passaggio che EnsureAndRegisterCertifiedAsync() salta per WebGPU EP, quindi è necessario chiamarlo in modo esplicito.
• Registra: TryRegister() registra la libreria EP installata con ONNX Runtime in modo che una sessione possa selezionarla. Dopo la registrazione, restituisce GetEpDevices() i dispositivi EP disponibili. Un dispositivo EP (OrtEpDevice) rappresenta un provider di esecuzione associato a un dispositivo hardware specifico su cui può essere eseguito. Identifica sia il provider (tramite il relativo EpName) che il dispositivo hardware sottostante, anziché un dispositivo hardware autonomamente. Selezionare il dispositivo EP le cui EpName corrisponde a WebGPU EP, quindi associarlo alle opzioni di sessione.
• Annulla registrazione: UnregisterExecutionProviderLibrary() rimuove la registrazione prima che l'ambiente venga rimosso.

Le opzioni specifiche del provider sono disponibili nella documentazione del provider di esecuzione WEBGPU ONNX. Dopo aver funzionato il ep WebGPU, eseguirne il benchmark delle prestazioni e del comportamento nell'hardware di destinazione. Usare i dati di benchmarking per guidare le decisioni di adozione e rimanere aggiornati man mano che il EP WebGPU aggiunge nuovi miglioramenti nel tempo.

Segnalazione problemi

Risolvere tutti i problemi relativi a WebGPU EP nel repository GitHub ml di Windows. Se il team Windows ML determina che un problema è specifico del runtime ONNX, può trasferirlo nel repository di GitHub del runtime ONNX.

Vedere anche

• Provider di esecuzione di Windows ML
• Accelerare i modelli di intelligenza artificiale
• Selezionare i provider di esecuzione
• Acquisire i log