WebGPU 执行提供程序

WebGPU 执行提供程序通过定位 WebGPU API，能够在各种 GPU 上对 ONNX 模型进行硬件加速推理。在原生平台上，它使用 Dawn（Google 的 WebGPU 实现），该实现会根据平台分派到 D3D12、Vulkan 或 Metal。同一个执行提供程序还可以驱动浏览器中 ONNX Runtime Web 的 webgpu 后端。

与其他 GPU 执行提供程序相比，WebGPU EP 旨在实现跨厂商和跨平台：单一构建即可定位平台原生图形 API 支持的任何 GPU，而无需在最终用户的机器上安装特定厂商的 SDK。

如果您使用的是 ONNX Runtime Web（浏览器中的 JavaScript/TypeScript），请参阅专门的教程 使用 WebGPU 执行提供程序，了解浏览器相关主题，例如 onnxruntime-web/webgpu 导入、Tensor.fromGpuBuffer 和 env.webgpu 标志。本页的其余部分重点介绍原生（C/C++/Python/C#）WebGPU EP。

内容

• 安装
• 要求
• 从源代码构建
  • 构建标志
• 用法
  • Python
  • C# / .NET
  • C++
  • JavaScript / TypeScript (ONNX Runtime Web)
• 配置选项
  • 通用选项
  • WebGPU 上下文选项
  • 缓冲区缓存模式
• 图捕获
• 性能分析与调试
• 备注
  • WebGPU EP 与 JSEP
• 更多资源

安装

原生 WebGPU EP 作为 插件 EP 分发：这是一个共享库，在运行时与兼容的核心 ONNX Runtime 安装一起注册。

• Python: pip install onnxruntime onnxruntime-ep-webgpu
• .NET：将对 Microsoft.ML.OnnxRuntime.EP.WebGpu 的引用与现有的 Microsoft.ML.OnnxRuntime 包一起添加。
• C/C++：直接使用插件 EP 共享库（onnxruntime_providers_webgpu.{dll,so,dylib}）。它随上述 NuGet 包的运行时文件一起提供，也可以从源码构建。

对于 ONNX Runtime Web（浏览器），除了 onnxruntime-web 包之外，不需要单独安装——请参阅 JavaScript 快速入门。

要求

WebGPU EP 需要支持 Dawn 原生后端之一的 GPU 和驱动程序

平台	Dawn 使用的后端
Windows	Direct3D 12, Vulkan
Linux	Vulkan
Android	Vulkan
macOS	Metal
iOS	Metal

在浏览器中，底层浏览器必须实现 WebGPU；有关 ORT Web 的具体信息，请参阅 WebGPU 支持矩阵，有关浏览器可用性，请参阅 webgpu.io/status。

从源码构建

使用带有 --use_webgpu 标志的 tools/ci_build/build.py。有关常规构建工作流，请参阅 BUILD 页面。

# Build WebGPU plugin EP
python tools/ci_build/build.py --build_dir build/webgpu_plugin_ep --config RelWithDebInfo \
    --build_shared_lib --use_webgpu shared_lib

构建标志

标志	描述
--use_webgpu [static_lib\|shared_lib]	启用 WebGPU EP。static_lib（未给定值时的默认值）将 WebGPU EP 构建到主 onnxruntime 库中。shared_lib 将 WebGPU EP 构建为单独的 插件 EP 库（onnxruntime_USE_EP_API_ADAPTERS=ON），并且会生成随 onnxruntime-ep-webgpu / Microsoft.ML.OnnxRuntime.EP.WebGpu 包一起发布的 onnxruntime_providers_webgpu.{dll,so,dylib}。shared_lib 不支持 WebAssembly 构建。将 CMake 标志设置为 onnxruntime_USE_WEBGPU=ON。
--use_external_dawn	链接到外部提供的 Dawn，而不是从源码构建 Dawn。需要 --use_webgpu。设置 onnxruntime_USE_EXTERNAL_DAWN=ON。
--enable_pix_capture	仅限 Windows。使用 PIX GPU 调试器支持进行构建。需要 --use_webgpu。

使用方法

WebGPU EP 通过 插件 EP API 添加到会话中：共享库在运行时通过 register_execution_provider_library / RegisterExecutionProviderLibrary 进行注册，然后将一个或多个 OrtEpDevice 条目附加到 SessionOptions。onnxruntime-ep-webgpu (Python) 和 Microsoft.ML.OnnxRuntime.EP.WebGpu (.NET) 包捆绑了该共享库，并提供了返回其路径和要使用的 EP 名称的辅助函数。

有关常规插件 EP 工作流，请参阅 使用插件执行提供程序库。

Python

import onnxruntime as ort
import onnxruntime_ep_webgpu as webgpu_ep

# Register the plugin EP library with ONNX Runtime
ort.register_execution_provider_library("webgpu_ep_registration", webgpu_ep.get_library_path())

# Discover WebGPU devices
webgpu_devices = [d for d in ort.get_ep_devices() if d.ep_name == webgpu_ep.get_ep_name()]

# Create a session using the WebGPU EP
sess_options = ort.SessionOptions()
sess_options.add_provider_for_devices(webgpu_devices, {
    "preferredLayout": "NHWC",
    "enableGraphCapture": "1",
})
session = ort.InferenceSession("model.onnx", sess_options=sess_options)

C# / .NET

using Microsoft.ML.OnnxRuntime;
using Microsoft.ML.OnnxRuntime.EP.WebGpu;

var env = OrtEnv.Instance();
env.RegisterExecutionProviderLibrary("webgpu_ep_registration", WebGpuEp.GetLibraryPath());

OrtEpDevice? webGpuDevice = null;
foreach (var d in env.GetEpDevices())
{
    if (d.EpName == WebGpuEp.GetEpName())
    {
        webGpuDevice = d;
        break;
    }
}

using var sessionOptions = new SessionOptions();
sessionOptions.AppendExecutionProvider(env, new[] { webGpuDevice },
    new Dictionary<string, string>
    {
        ["preferredLayout"] = "NHWC",
        ["enableGraphCapture"] = "1",
    });

using var session = new InferenceSession("model.onnx", sessionOptions);

C++

C++ 模式是通用的插件 EP 习惯用法——宿主应用程序负责定位 onnxruntime_providers_webgpu.{dll,so,dylib} 共享库（来自 NuGet 包的运行时文件、手动构建等）

#include "onnxruntime_cxx_api.h"

Ort::Env env(ORT_LOGGING_LEVEL_WARNING, "webgpu_sample");
env.RegisterExecutionProviderLibrary("webgpu_ep_registration",
    ORT_TSTR("onnxruntime_providers_webgpu.dll"));

std::vector<Ort::ConstEpDevice> ep_devices = env.GetEpDevices();
std::vector<Ort::ConstEpDevice> selected_ep_devices{};
for (auto ep_device : ep_devices) {
    if (std::strcmp(ep_device.EpName(), "WebGpuExecutionProvider") == 0) {
        selected_ep_devices.push_back(ep_device);
        break;
    }
}

Ort::KeyValuePairs ep_options;
ep_options.Add("preferredLayout",    "NHWC");
ep_options.Add("enableGraphCapture", "1");

Ort::SessionOptions session_options;
session_options.AppendExecutionProvider_V2(env, selected_ep_devices, ep_options);

Ort::Session session(env, ORT_TSTR("model.onnx"), session_options);

JavaScript / TypeScript (ONNX Runtime Web)

对于浏览器使用，导入 onnxruntime-web/webgpu 并在 executionProviders 中列出 'webgpu'。有关完整指南（包括使用 GPU 缓冲区的 IO 绑定），请参阅 使用 WebGPU 执行提供程序。

配置选项

提供程序选项从键前缀为 ep.webgpuexecutionprovider.* 的会话配置条目中读取。将提供程序选项传递给 用法 中显示的插件 EP API 时，请使用下方的简短名称（不带前缀）；前缀会在内部添加。

通用选项

选项	允许的值	描述
preferredLayout	NCHW, NHWC	针对对布局敏感的内核的首选数据布局。
enableGraphCapture	0, 1	为完全在 WebGPU 上运行的静态形状模型启用 图捕获。
enableInt64	0, 1	在 WGSL 内核中启用原生 int64 支持（需要公开匹配功能的设备）。当 enableGraphCapture 为 1 时强制开启，无论此设置如何。
multiRotaryCacheConcatOffset	非负整数	多旋转缓存拼接内核使用的偏移量（高级调优选项）。
forceCpuNodeNames	换行符分隔的列表	强制列出的节点名称在 CPU EP 回退上运行，而不是在 WebGPU 上。每行为一个节点名称；空行将被忽略。
enablePIXCapture	0, 1	启用每次运行的 PIX 捕获。仅在使用 --enable_pix_capture 配置的 Windows 构建中有意义。

WebGPU 上下文选项

这些选项配置在具有相同 deviceId 的会话之间共享的底层 Dawn/WebGPU 实例、适配器和设备。

选项	允许的值	描述
deviceId	整数	选择要使用的 WebGPU 上下文。共享相同 deviceId 的会话共享底层设备和缓冲区缓存。默认为 0。
powerPreference	high-performance, low-power	传递给 requestAdapter 的提示。默认为实现默认值。
webgpuInstance	指针（作为整数）	自带 WGPUInstance。编码为指针值的十进制表示形式。在与宿主应用程序共享 Dawn 实例时使用。
webgpuDevice	指针（作为整数）	自带 WGPUDevice。编码为指针值的十进制表示形式。与 webgpuInstance 一起使用以共享现有设备。
preserveDevice	0, 1	当为 1 时，在拥有上下文的最后一个会话释放后，保持底层 WebGPU 设备处于活动状态。在反复创建和销毁会话时非常有用。
validationMode	disabled, wgpuOnly, basic, full	控制 WGSL/运行时验证。disabled 跳过 ONNX 端的验证，wgpuOnly 依赖 Dawn 的验证，basic 启用轻量级 ONNX 检查，full 启用所有可用的检查。默认为与构建相关的值。
maxStorageBufferBindingSize	整数（字节）	覆盖请求的 maxStorageBufferBindingSize 设备限制。不能超过适配器报告的限制。

指针值选项（webgpuInstance、webgpuDevice）被解析为 10 进制整数——请传入指针值的十进制表示形式。不接受十六进制字面量（例如 0x...）。

缓冲区缓存模式

EP 维护四个池化缓冲区缓存。每个缓存都接受相同的模式集

选项	允许的值
storageBufferCacheMode	disabled, lazyRelease, simple, bucket
uniformBufferCacheMode	disabled, lazyRelease, simple, bucket
queryResolveBufferCacheMode	disabled, lazyRelease, simple, bucket
defaultBufferCacheMode	disabled, lazyRelease, simple, bucket

模式，按缓存积极程度递增排序

• disabled — 缓冲区在释放时立即被销毁；内存占用最低，分配开销最高。
• lazyRelease — 缓冲区在下一次运行结束时释放。
• simple — 以确切大小为键的单个空闲链表。
• bucket — 缓冲区按 2 的幂次大小分桶，以便以有限的浪费进行快速重用。推荐用于具有稳定形状的推理工作负载。

图捕获

当模型具有完全静态的形状且所有内核都在 WebGPU 上运行时，将 enableGraphCapture 设置为 1 会在初始运行期间记录 WebGPU 命令序列，并在后续运行中重播所记录的命令，从而显著降低每次运行的 CPU 开销。

如果任何内核回退到 CPU，或者任何输入形状在运行之间发生变化，图捕获可能会失败或回退到常规执行。在这种情况下，请不要设置 enableGraphCapture 或将其设置为 0。

ORT Web 通过 enableGraphCapture 会话选项公开了相同的功能 — 请参阅 enableGraphCapture。

性能分析与调试

• 通用 ORT 性能分析。 ORT 的内置性能分析器（SessionOptions::EnableProfiling）可与 WebGPU EP 配合使用，并生成每个算子的耗时。
• 原生 PIX 捕获（Windows）。 使用 --use_webgpu --enable_pix_capture 构建，将 PIX 附加到宿主进程，并在会话上将 enablePIXCapture 设置为 1，以捕获单个运行的 WebGPU/D3D12 工作。
• WebGPU 验证。 调整 validationMode 以在开发期间暴露设备端问题；在生产基准测试中将其调低至 disabled 以消除验证开销。
• 浏览器性能分析。 对于 ORT Web，请参阅 WebGPU 性能分析。

注意事项

WebGPU EP 与 JSEP

ONNX Runtime Web 历史上通过 JavaScript 执行提供程序 (JSEP) 来驱动其 webgpu 后端，该提供程序在构建时使用 --use_jsep 启用。原生 WebGPU EP（--use_webgpu）是构建在 Dawn 上的独立的 C++ 端实现。如今，这两个标志可以在同一个构建中启用（过渡状态）；预计未来的更改将使它们互斥。对于原生构建，请使用 --use_webgpu；对于当前 ORT Web 发布的浏览器路径，请使用 WebAssembly+JSEP 构建。

更多资源

• WebGPU 规范 (W3C)
• WGSL — WebGPU 着色语言
• Dawn — Google 的 WebGPU 实现
• 使用 WebGPU 执行提供程序（ORT Web 教程）
• 构建 ONNX Runtime Web