如何在 Windows 上用 D3D12 Agility SDK（--use_dawn_agility_sdk）构建 ONNX Runtime WebGPU

如何在 Windows 上用 D3D12 Agility SDK--use_dawn_agility_sdk构建 ONNX Runtime WebGPU【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime在 Windows 上构建 ONNX Runtime 的 WebGPU EP 时Dawn 的 D3D12 后端默认不链接 D3D12 Agility SDK。如果你希望使用 ONNX Runtime 锁定的 D3D12 Agility SDK preview 包来构建 Dawn 的 D3D12 后端可以打开--use_dawn_agility_sdk选项。这条路径面向本地开发只支持 Windows 桌面 x86、x64 和 ARM64 目标且不支持 Python wheel、C#、NuGet、Java、Node.js 等打包输出这些包不会部署所需的 D3D12 运行时 DLL。操作依据来自仓库文档 docs/BuildWithDawnAgilitySDK.md构建脚本校验逻辑在 tools/ci_build/build.pyCMake 侧的依赖处理在 cmake/external/onnxruntime_external_deps.cmake。构建前检查环境与前置条件锁定的 Agility SDK 对系统有硬性要求构建前先确认Windows 10 1909 或更新版本。对于 1909、2004、20H2 三个版本还有最低 OS build revision 要求Version 1909revision 1350 或更高build 18363.1350Version 2004 与 20H2revision 789 或更高更新版本的 Windows 不需要单独检查 revision。确认系统已带 Agility SDK loader 更新检查%SystemRoot%\System32\D3D12Core.dll是否存在存在即说明系统有 Agility SDK loader。必须启用 Windows Developer Mode。仓库锁定的 SDK 是 preview 版本这是文档明确提出的要求。安装与 Agility SDK 721 preview 兼容的 GPU 驱动具体支持情况以微软的 per-vendor 驱动说明为准功能可用性取决于 GPU 和驱动。仓库锁定的 SDK 包是Microsoft.Direct3D.D3D12的1.721.0-preview版本见 cmake/deps.txt构建时会自动下载不需要你手动获取。主路径用 build.py 构建在仓库根目录的 PowerShell 中执行文档给出的命令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构建输出目录路径可按需修改--no_telemetry禁用遥测--config Release使用 Release 配置--update更新 makefile生成构建系统文件--build执行实际构建--use_webgpu启用 WebGPU EP不带值时默认 static_lib 静态库构建--use_dawn_agility_sdk用锁定的 D3D12 Agility SDK 构建 Dawn 的 D3D12 后端内部映射为 CMake 变量DAWN_USE_AGILITY_SDKON--build_shared_lib构建 ONNX Runtime 的动态库而非静态库--skip_tests跳过所有测试--use_dawn_agility_sdk必须与--use_webgpu一起使用否则构建脚本会直接报错退出Dawn Agility SDK (--use_dawn_agility_sdk) must be enabled with WebGPU (--use_webgpu).替代路径直接配置 CMake如果你不用build.py而是直接驱动 CMake需要同时启用三个变量onnxruntime_USE_WEBGPUonnxruntime_ENABLE_DAWN_BACKEND_D3D12DAWN_USE_AGILITY_SDK注意DAWN_USE_AGILITY_SDK依赖 Dawn 的 D3D12 后端如果onnxruntime_ENABLE_DAWN_BACKEND_D3D12没有打开CMake 会直接报DAWN_USE_AGILITY_SDK requires the Dawn D3D12 backend.。启用后SDK 包会被下载到 ONNX Runtime 管理的 Dawn 源码树内的third_party/agility-sdk目录实际是${FETCHCONTENT_BASE_DIR}/dawn-src/third_party/agility-sdk未设置FETCHCONTENT_BASE_DIR时为${CMAKE_BINARY_DIR}/_deps/dawn-src。配置阶段还会做一次完整性检查若该目录下缺少build/native/include/d3d12.hCMake 会报The Agility SDK package does not contain build/native/include/d3d12.h并中止。运行时加载与激活验证构建成功后验证是否真正激活了 Agility SDK 分两步DLL 部署位置运行时 Dawn 从可执行文件旁边的D3D12目录加载 SDK 的 DLL。也就是说本地运行生成的可执行文件时要确保该D3D12目录随可执行文件一起部署否则加载不到运行时。日志确认在 Dawn 日志中查找[AgilitySDK] active出现该标记即表示 Agility SDK 成功激活。不支持的配置与对应的报错以下限制在 docs/BuildWithDawnAgilitySDK.md 中声明构建脚本和 CMake 都会在配置阶段直接拦截并给出报错信息非 Windows 平台Dawn Agility SDK (--use_dawn_agility_sdk) is only supported on Windows.Windows ARM32 / ARM64EC 目标does not support Windows ARM32 or ARM64EC. Use an x86, x64, or ARM64 target.WebGPU Plugin EP 构建--use_webgpu shared_lib不支持文档说明要用静态库构建--use_webgpu做本地开发。CMake 侧对应onnxruntime_USE_EP_API_ADAPTERSON的检查。打包输出同时使用--build_wheel、--build_csharp、--build_nuget、--build_java、--build_nodejs任一项会被拒绝原因是这些包不会部署所需的 D3D12 运行时 DLL。自定义 Dawn 源码用onnxruntime_CUSTOM_DAWN_SRC_PATH指定自定义 Dawn checkout 时CMake 直接报DAWN_USE_AGILITY_SDK is not supported with onnxruntime_CUSTOM_DAWN_SRC_PATH.WindowsStore/UWPCMake 报DAWN_USE_AGILITY_SDK is not supported for WindowsStore/UWP.小结这条路径的完整闭环是确认系统 revision 和D3D12Core.dll、启用 Developer Mode → 用带--use_dawn_agility_sdk的build.py命令构建 → 运行时把 SDK DLL 放在可执行文件旁的D3D12目录 → 在 Dawn 日志中看到[AgilitySDK] active。它的边界也很明确仅限 Windows 桌面 x86/x64/ARM64 的本地开发构建任何打包或 Plugin EP 形态都不在支持范围内。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考