ONNX Runtime WebGPU Plugin EP：C/.NET 下 GPU 加速推理的 NuGet 包集成与完整实操指南

ONNX Runtime WebGPU Plugin EPC#/.NET 下 GPU 加速推理的 NuGet 包集成与完整实操指南【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime本文基于 ONNX Runtime 仓库中 WebGPU 插件 Execution ProviderEP的 C# 包文档 README.md系统讲解Microsoft.ML.OnnxRuntime.EP.WebGpuNuGet 包的定位、平台支持、安装方式与完整接入代码并结合 WebGpuEp.cs、打包脚本 pack_nuget.py 与 测试工程 的源码深入解析原生库定位、EP 注册与设备发现机制。读完本文你能够在 .NET 8 项目中正确引入该包、注册 WebGPU 插件 EP、创建推理会话并掌握常见报错设备缺失、运行时版本不兼容的排查方法。1. 什么是 WebGPU 插件 EP这个 NuGet 包解决什么问题ONNX Runtime 的插件 EP 是一种独立于主程序构建分发的执行提供程序它以共享库onnxruntime_providers_webgpu.dll/.so/.dylib的形式存在不内置于主onnxruntime二进制而是在运行时通过注册接口动态加载。根据 plugin-ep-webgpu 根目录 README 的说明该共享库由 ONNX Runtime 主构建以--use_webgpu shared_lib方式产出随后被封装为三种交付物Python wheelonnxruntime-ep-webgpu、多平台 NuGet 包即本文主题Microsoft.ML.OnnxRuntime.EP.WebGpu以及面向 Foundry Local 的 zip 包。这个 C# 包的核心定位与原文档保持一致只提供 WebGPU 插件 EP 本身不捆绑 ONNX Runtime 核心项目必须单独引用一个 ONNX Runtime 核心包如Microsoft.ML.OnnxRuntime且版本必须不低于最低兼容版本。从 MIN_ONNXRUNTIME_VERSION 文件看当前仓库锁定的最低核心版本为1.24.4原文档中的min_onnxruntime_version是打包期模板占位符pack_nuget.py 在 pack 阶段读取 MIN_ONNXRUNTIME_VERSION 并注入 README见脚本中的render_readme函数因此正式发布包内的文档会显示具体版本号包与核心包之间不声明硬依赖。这一点在 测试工程 csproj 中有明确注释“The plugin EP package does not declare a hard dependency on a core ORT package, so reference one explicitly here”因此测试工程显式引用了核心包。兼容性校验前移到运行期原生插件代码在注册时校验所链接的 ORT 版本若核心包过旧会在注册 EP 库时报错原文档 Troubleshooting 一节描述的版本错误即来源于此机制。2. 支持的平台RID与前置条件2.1 支持的运行时标识符Runtime Identifier (RID)win-x64win-arm64linux-x64linux-arm64osx-arm64该列表与包工程文件 Microsoft.ML.OnnxRuntime.EP.WebGpu.csproj 完全对应csproj 中每个ItemGroup按runtimes\win-x64\native、runtimes\win-arm64\native、runtimes\linux-x64\native、runtimes\linux-arm64\native、runtimes\osx-arm64\native五个标准 NuGet 布局条件性打包原生文件ConditionExists(...)保证从源码树构建时不会因缺失二进制而失败。2.2 各平台原生库构成从 pack_nuget.py 的PLATFORMS映射源码 38–44 行可确认每个 RID 实际携带的原生文件win-x64 / win-arm64onnxruntime_providers_webgpu.dlldxil.dlldxcompiler.dll。Windows 包额外捆绑 DirectX Shader Compiler 运行时DXC这是 HLSL 着色器编译的依赖CI 会从 DXC 官方发布物自动获取linux-x64 / linux-arm64libonnxruntime_providers_webgpu.soosx-arm64libonnxruntime_providers_webgpu.dylib。2.3 Linux 运行时前置条件原文档明确要求在 Linux 上系统必须安装并可在运行时访问 Vulkan 加载器libvulkan.so.1WebGPU 实现经由 Vulkan 后端运行这一点可参考 cmake 外部依赖清单 中 Dawn 相关依赖的定位。缺少它时插件 EP 会加载成功但发现不到设备具体排查见第 6 节。3. 安装方式标准安装命令继承原文档最低核心版本按当前仓库取1.24.4dotnet add package Microsoft.ML.OnnxRuntime --version 1.24.4 dotnet add package Microsoft.ML.OnnxRuntime.EP.WebGpu两条命令的分工第一条引入 ONNX Runtime 核心提供OrtEnv、InferenceSession等 API 与托管层 P/Invoke 绑定第二条引入本文主角的 WebGPU 插件 EP 包提供WebGpuEp辅助类与各平台原生库。由于插件 EP 包不硬依赖核心包两条缺一不可若核心包版本低于1.24.4注册时会触发版本错误见第 6 节。包工程本身的目标框架为netstandard2.0见 csproj因此可被 .NET 5 的所有现代框架及 .NET Framework 4.6.1 消费仓库配套的测试工程则使用net8.0。4. 完整接入代码与 API 解析原文档给出的最小完整用法如下共三步注册插件库 → 发现 EP 设备 → 创建会话。// Note: Error handling is omitted for brevity, except for the device-discovery check below. using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.EP.WebGpu; // Register the WebGPU EP plugin library var env OrtEnv.Instance(); env.RegisterExecutionProviderLibrary(webgpu_ep, WebGpuEp.GetLibraryPath()); // Find the WebGPU EP device OrtEpDevice? webGpuDevice null; foreach (var d in env.GetEpDevices()) { if (d.EpName WebGpuEp.GetEpName()) { webGpuDevice d; break; } } if (webGpuDevice is null) { throw new InvalidOperationException(No WebGPU device found.); } // Create a session with the WebGPU EP using var sessionOptions new SessionOptions(); sessionOptions.AppendExecutionProvider(env, new[] { webGpuDevice }, new Dictionarystring, string()); using var session new InferenceSession(model.onnx, sessionOptions);下面结合源码逐步拆解每一步在做什么。4.1WebGpuEp.GetLibraryPath()原生库如何被定位WebGpuEp.cs 中的GetLibraryPath()依次探测两个候选路径源码 22–45 行runtimes/rid/native/libname—— 标准 NuGet 布局RID 由RuntimeInformation动态拼出如win-x64、linux-arm64文件名按平台选择.dll/.so/.dylib程序基目录直下的libname—— 兜底路径覆盖单文件发布等原生资产直接落在托管程序集旁的布局。两个候选都不存在时抛出FileNotFoundException异常信息中会列出已探测的完整路径便于诊断部署问题。这解释了为什么第 2.1 节的 RID 列表同时出现在 README 与 csproj 中——它们共同约束了运行时库解析的可能位置。4.2RegisterExecutionProviderLibrary注册名的含义OrtEnv.RegisterExecutionProviderLibrary(string registrationName, string libraryPath)是核心包的公开 API托管实现见 OrtEnv.shared.cs它将注册名与库路径编码后透传给原生 C APIOrtRegisterExecutionProviderLibraryP/Invoke 绑定见 NativeMethods.shared.cs。需要注意注册名是调用方自定义的逻辑键不具特殊语义。README 示例用webgpu_ep而 测试程序 用webgpu_ep_registration两者均有效。它的主要用途是事后反注册测试程序在finally块中调用env.UnregisterExecutionProviderLibrary(epRegistrationName)释放插件。真正标识 EP 身份的是设备名WebGpuExecutionProvider由WebGpuEp.GetEpName()返回见 WebGpuEp.cs。4.3 设备发现与AppendExecutionProvider注册库后OR T 会实例化插件 EP 并枚举其设备。env.GetEpDevices()返回所有已注册 EP 的设备代码按EpName WebGpuEp.GetEpName()筛出 WebGPU 设备。根目录 README 对这一行为有明确说明WebGPU EP 目前只接受一个 EP 设备且自行选择物理 GPU因此找到第一个匹配设备即可。sessionOptions.AppendExecutionProvider(env, new[] { webGpuDevice }, new Dictionarystring, string())将该设备绑定到会话第三个参数为 EP 选项字典此处传空表示使用默认选项。4.4 端到端验证仓库自带测试程序WebGpuEpNuGetTest/Program.cs 是一个可直接复用的端到端验证模板在 README 示例之上还多两点实战细节创建会话前追加sessionOptions.AddSessionConfigEntry(session.disable_cpu_ep_fallback, 1)关闭 CPU 回退——这样若模型无法在 WebGPU 上执行会直接失败而不是静默落到 CPU便于在调试期确认 EP 真正生效用 generate_mul_model.py 生成的mul.onnx两个[2, 3]float32 张量做逐元素Mulopset 13跑一次推理逐元素比对输出容差1e-5f成功后打印PASSED: All outputs match expected values.并以 0 退出。其核心流程与原文档完全一致var env OrtEnv.Instance(); env.RegisterExecutionProviderLibrary(epRegistrationName, epLibPath); // ... 按 EpName 查找 OrtEpDevice ... using var sessionOptions new SessionOptions(); sessionOptions.AppendExecutionProvider(env, new[] { epDevice }, new Dictionarystring, string()); using var session new InferenceSession(inputModelPath, sessionOptions);如需本地复现该测试按 csharp/README.md 的说明先用python test/WebGpuEpNuGetTest/generate_mul_model.py需onnx包重新生成模型将测试工程nuget.config指向本地 pack 输出目录再执行dotnet run --project test/WebGpuEpNuGetTest/WebGpuEpNuGetTest.csproj --configuration Release。5. 包内构建过程pack_nuget.py如何产出 .nupkg理解打包链路有助于排查包里没有某平台原生库的问题。pack_nuget.py 的工作流为Staging暂存把包工程源码排除bin/obj、仓库根目录的LICENSE与ThirdPartyNotices.txt复制到暂存目录不修改源码树注入最低版本读取 MIN_ONNXRUNTIME_VERSION 并将min_onnxruntime_version模板变量替换进暂存 READMEStaging 原生二进制按PLATFORMS映射把各平台二进制拷入runtimes/rid/native/Windows 平台额外要求dxil.dll与dxcompiler.dll存在任一缺失即抛PackErrordotnet pack以-p:Versionx.y.z覆盖 csproj 中的哨兵版本0.0.0-dev产出.nupkg与.snupkgcsproj 中IncludeSymbols已启用符号包。常用调用方式继承 csharp/README.md# 本地单平台打包 python pack_nuget.py --version 0.1.0-dev --binary-dir-win-x64 path-to-win-x64-binaries # 多平台打包各 --binary-dir-* 指向该平台已构建的原生二进制目录 python pack_nuget.py --version 0.1.0-dev --binary-dir-win-x64 win-x64 --binary-dir-win-arm64 win-arm64 --binary-dir-linux-x64 linux-x64 --binary-dir-macos-arm64 macos-arm64 # 从 CI 下载的 artifacts 根目录打包每个平台一个子目录 python pack_nuget.py --version 0.1.0-dev --artifacts-dir path-to-artifacts-root未提供二进制目录的平台会被跳过仅告警式跳过因此本地通常只打自己有产物的平台--required-platforms可强制要求某些平台必须成功。6. 故障排查Troubleshooting原文档列出的两类典型错误及仓库证据补充6.1No WebGPU device found含义插件 EP 库加载成功了但没有发现兼容的图形适配器。按平台区分Linux通常是 Vulkan 加载器libvulkan.so.1未安装。用发行版包管理器安装如vulkan-loader类包即可对应第 2.3 节的前置条件Windows可能是 GPU 驱动缺失或过旧升级显卡驱动后重试。注意区分注册失败与无设备注册阶段的错误信息通常指向库加载或版本不兼容设备缺失发生在GetEpDevices()之后。6.2ORT runtime version ... is below the minimum required version 1.24.4含义所引用的Microsoft.ML.OnnxRuntime核心包版本低于插件 EP 要求的最低版本。这是第 1 节所述注册期兼容性校验机制的直接体现——包内 README 中该错误信息里的版本号即打包时从 MIN_ONNXRUNTIME_VERSION 注入的1.24.4。修复升级核心包dotnet add package Microsoft.ML.OnnxRuntime --version 1.24.4若插件 EP 后续版本提高了最低要求以发布包 README 中实际显示的版本为准。7. 小结与延伸阅读Microsoft.ML.OnnxRuntime.EP.WebGpu的价值在于让 .NET 应用以纯 NuGet 依赖的方式获得 WebGPU GPU 加速推理能力而无需自行编译 ONNX Runtime 或管理原生库WebGpuEp.GetLibraryPath()处理库定位OrtEnv.RegisterExecutionProviderLibrary完成动态注册GetEpDevices()AppendExecutionProvider完成设备级绑定全程约 10 行代码。接入时请牢记三个关键约束核心包最低版本1.24.4MIN_ONNXRUNTIME_VERSION、Linux 需libvulkan.so.1、支持 RID 为 win-x64 / win-arm64 / linux-x64 / linux-arm64 / osx-arm64。仓库内可继续深入的材料Python 侧对应包与用法plugin-ep-webgpu/python/onnxruntime_ep_webgpu/README.md、测试脚本插件 EP 整体打包与 CI 设计plugin-ep-webgpu/README.md、发布说明托管层 EP 注册 API 实现csharp/src/Microsoft.ML.OnnxRuntime/OrtEnv.shared.cs包构建与本地验证全流程plugin-ep-webgpu/csharp/README.md、pack_nuget.py。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考