ONNX Runtime 使用 Dawn D3D12 Agility SDK 构建 WebGPU 后端的完整指南

ONNX Runtime 使用 Dawn D3D12 Agility SDK 构建 WebGPU 后端的完整指南【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime导读本文档面向希望在 Windows 桌面环境下通过 ONNX Runtime 官方构建脚本或直接 CMake 配置将 WebGPU 执行提供程序Execution Provider的 D3D12 后端与 Dawn 内置的预览版 D3D12 Agility SDK 绑定构建的开发者。读完本文你将掌握--use_dawn_agility_sdk的完整构建命令与参数语义、平台与产物支持边界、Windows 系统版本与驱动前置要求、运行时 SDK DLL 部署与激活验证方法以及对应的 CMake 参数与底层依赖下载机制从而在自己的本地开发环境中稳定复现这一构建流程。背景为什么 WebGPU 后端需要 Agility SDKONNX Runtime 的 WebGPU EP 依赖 Google Dawn 作为 WebGPU 实现。在 Windows 平台上Dawn 的 D3D12 后端需要调用 Direct3D 12 运行时接口而预览版本的 Agility SDKMicrosoft.Direct3D.D3D12可以向前提供比操作系统自带 D3D12 运行时更新的特性与修复。ONNX Runtime 在仓库中固定pin了一个预览版本的 Agility SDK并通过--use_dawn_agility_sdk构建选项将其与 Dawn 的 D3D12 后端一起编译链接。该选项主要面向本地开发场景而非生产发布流程。从依赖清单 cmake/deps.txt 可以看到ONNX Runtime 当前固定了两条相关依赖dawn;https://github.com/google/dawn/archive/refs/tags/v20260818.211311.zip;10e42c94f70fc222ecbafebbd1cfbb5482593d59 dawn_agility_sdk;https://www.nuget.org/api/v2/package/Microsoft.Direct3D.D3D12/1.721.0-preview;fbeb58268d47626027ab670928817cbb955755db即当前仓库锁定的是Dawn v20260818.211311与Agility SDK 1.721.0-previewNuGet 包Microsoft.Direct3D.D3D121.721.0-preview两条依赖均带 SHA1 校验保证构建可复现。使用构建脚本启用 Agility SDK推荐方式ONNX Runtime 官方推荐的入口是tools/ci_build/build.py。在 Windows PowerShell 中执行以下命令即可构建带有 Dawn Agility SDK 的 WebGPU 后端python tools\ci_build\build.py --build_dir build\Windows --no_telemetry --config Release --update --build --use_webgpu --use_dawn_agility_sdk --build_shared_lib --skip_tests各参数语义如下参数说明--build_dir build\Windows指定 CMake 构建输出目录--no_telemetry关闭构建过程的遥测上报--config Release选择 Release 配置本地开发也可改用 Debug--update --build先更新/拉取依赖再执行构建--use_webgpu启用 WebGPU 执行提供程序静态库构建形式--use_dawn_agility_sdk启用 Dawn 的 D3D12 Agility SDK 支持与--use_webgpu配套--build_shared_lib同时构建共享库onnxruntime.dll--skip_tests跳过单元测试构建加速本地迭代平台与产物支持边界该选项并非全平台通用构建脚本在 tools/ci_build/build.py 中通过显式的参数校验强制约束了使用边界任何不满足条件的组合都会在配置阶段直接抛出BuildError而不是等到编译期才失败支持Windows 桌面平台的x86、x64、ARM64三种目标架构不支持 Windows ARM32 与 ARM64EC脚本在检测到args.arm或args.arm64ec时直接报错提示改用 x86/x64/ARM64不支持 WindowsStore/UWP 目标必须与 WebGPU 同时启用单独使用--use_dawn_agility_sdk而不用--use_webgpu会报错见 tools/ci_build/build.py不支持 WebGPU Plugin EP 共享库构建即--use_webgpu shared_lib形式发布版 plugin EP 包走的是 shared_lib 配置而 Agility SDK 仅允许静态库形式的本地开发构建见 tools/ci_build/build.py不支持 Python wheels、C#、NuGet、Java、Node.js 打包因为这些产物不会部署运行所需的 D3D12 运行时 DLL脚本在检测到--build_wheel、--build_csharp、--build_nuget、--build_java、--build_nodejs时同样直接报错不支持自定义 Dawn 源码路径通过onnxruntime_CUSTOM_DAWN_SRC_PATH指定自定义 Dawn checkout 的组合不在支持范围内。因此这一选项的典型定位是Windows 桌面 静态 WebGPU EP 本地开发验证。系统前置要求由于固定的 SDK 是预览版本且要求较新的 D3D12 运行时需要满足以下系统条件Windows 版本与构建修订号固定的 Agility SDK 要求Windows 10 版本 1909 或更新。对于较早的 1909、2004、20H2 三个版本还存在最低构建修订号要求Windows 版本最低构建修订号1909revision 1350 或更新即 build 18363.13502004 / 20H2revision 789 或更新更晚的 Windows 版本如 21H1 及之后无需单独的修订号检查。确认 Agility SDK loader 已就绪%SystemRoot%\System32\D3D12Core.dll文件的存在与否可以用来确认系统是否已安装 Agility SDK loader 更新。如果该文件不存在需要先通过 Windows Update 安装对应的系统更新。开发者模式与 GPU 驱动因为固定的 SDK 是preview 版本Windows开发者模式Developer Mode必须开启否则加载会被系统拒绝。同时需要安装与预览版 SDK 兼容的 GPU 驱动不同厂商NVIDIA、AMD、Intel的预览驱动链接与 Shader Model 6.10 等特性支持表会随预览版公告更新功能可用性取决于具体的 GPU 型号与驱动版本请以对应厂商驱动发布页为准。运行时部署与激活验证构建完成后运行时行为有两个关键点SDK DLL 加载位置Dawn 在运行时从可执行文件同级的D3D12子目录加载 Agility SDK 的 DLL例如D3D12Core.dll、d3d12SDKLayers.dll等。因此运行前需要确保该目录下存在对应 DLL或将它们部署到可执行文件旁边的D3D12目录。激活日志查看 Dawn 的日志输出如果出现[AgilitySDK] active字样即表示 Agility SDK 已成功激活并被 D3D12 后端使用。若日志中没有该标记则说明加载失败或未生效应回到前置条件检查系统版本、D3D12Core.dll、开发者模式、驱动。直接使用 CMake 配置如果不走build.py也可以直接对 CMake 进行配置等价地启用同一套能力。需要同时打开三个开关onnxruntime_USE_WEBGPUON启用 WebGPU 执行提供程序onnxruntime_ENABLE_DAWN_BACKEND_D3D12ON启用 Dawn 的 D3D12 后端Windows 平台条件DAWN_USE_AGILITY_SDKON让 Dawn 使用 ONNX Runtime 固定的预览版 Agility SDK。三个开关缺一不可DAWN_USE_AGILITY_SDK只在onnxruntime_USE_WEBGPU分支内生效而 D3D12 后端开关还决定了运行时 D3D12 相关 DLL 的复制逻辑详见下文源码分析。源码级实现原理1. 构建脚本的参数映射build.py会把--use_dawn_agility_sdk直接映射为 CMake 变量DAWN_USE_AGILITY_SDK与onnxruntime_USE_WEBGPU一起透传给 CMake见 tools/ci_build/build.py-Donnxruntime_USE_WEBGPU (ON if args.use_webgpu else OFF), -Donnxruntime_USE_EXTERNAL_DAWN (ON if args.use_external_dawn else OFF), -DDAWN_USE_AGILITY_SDK (ON if args.use_dawn_agility_sdk else OFF),2. 依赖下载与目录布局在 CMake 侧当DAWN_USE_AGILITY_SDK开启时cmake/external/onnxruntime_external_deps.cmake 会做三件事将 Agility SDK 的期望目录设置为 Dawn 源码树下的third_party/agility-sdk${ONNXRUNTIME_DAWN_SRC_DIR}/third_party/agility-sdk以符合 Dawn 预期的 Chromium CIPD 目录布局通过onnxruntime_fetchcontent_declareonnxruntime_fetchcontent_makeavailable从cmake/deps.txt指定的 NuGet 地址下载Microsoft.Direct3D.D3D12/1.721.0-preview包并用 SHA1 校验完整性校验包内存在build/native/include/d3d12.h若缺失则直接FATAL_ERROR防止在缺少头文件的情况下继续编译。3. D3D12 相关 DLL 的构建期复制当WIN32且启用了onnxruntime_ENABLE_DAWN_BACKEND_D3D12时cmake/onnxruntime_providers_webgpu.cmake 会通过add_dependencies将dxil.dll与dxcompiler.dll复制到输出目录并把这些 DLL 追加进 WebGPU provider 的部署依赖列表确保运行目录中同时具备 DXIL 编译器与 Agility SDK 运行组件。这解释了为什么支持范围内只包含可自行携带运行 DLL 的本地可执行文件场景而 Python/C#/NuGet/Java/Node.js 等打包产物因为无法部署这些 DLL 而不被支持。常见问题排查现象排查方向配置阶段报BuildError提示 Agility SDK 必须与 WebGPU 一起启用检查是否同时传了--use_webgpu报错提示仅支持 Windows确认构建主机是 Windows且未在 Linux/macOS 上误用该选项报错提示不支持 ARM32/ARM64EC改用 x86、x64 或 ARM64 目标架构报错提示不支持 shared_lib/plugin EP将--use_webgpu shared_lib改回静态库形式--use_webgpu报错提示不支持 Python/C#/NuGet/Java/Node.js 打包去掉对应的--build_*打包参数仅做本地开发构建运行时日志中没有[AgilitySDK] active依次检查系统是否 1909 且满足最低修订号、%SystemRoot%\System32\D3D12Core.dll是否存在、开发者模式是否开启、GPU 驱动是否兼容以及可执行文件旁的D3D12目录是否包含 SDK DLL小结--use_dawn_agility_sdk是 ONNX Runtime 为 Windows 本地开发提供的、把 Dawn D3D12 后端与预览版 Agility SDK 绑定构建的开关。它的核心价值在于让开发者无需等待操作系统更新即可使用更新的 D3D12 特性调试 WebGPU EP代价是支持范围被严格限定在 Windows 桌面 x86/x64/ARM64 的静态 WebGPU 构建。构建前请务必核对 Windows 版本与修订号、开启开发者模式、安装兼容驱动并在运行时通过D3D12目录部署与[AgilitySDK] active日志完成端到端验证。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考