DirectML

---

⚠️ DirectML 处于维护模式 ⚠️

• 如果您的电脑运行的是 Windows 11 版本 24H2（内部版本 26100）或更高版本，请考虑使用 Windows ML 来加速机器学习模型的执行。
• DirectML 将继续在之前的 Windows 版本上得到支持（参见 发行历史），并会随未来版本的 Windows 一起发布。然而，不再计划推出新的功能或特性更新。
• DirectML 将继续接收与安全和合规相关的问题修复。有关安全问题的报告，请参阅 SECURITY.md。
• 此仓库中的问题和示例将不再更新。

---

DirectML 是一个高性能、硬件加速的 DirectX 12 库，专为机器学习设计。它可在广泛的受支持硬件和驱动程序上为常见的机器学习任务提供 GPU 加速，包括来自 AMD、Intel、NVIDIA 和 Qualcomm 等厂商的所有支持 DirectX 12 的 GPU。

单独使用时，DirectML API 是一个低级别的 DirectX 12 库，适用于高性能、低延迟的应用场景，例如框架、游戏以及其他实时应用。DirectML 与 Direct3D 12 的无缝互操作性，以及其低开销和跨硬件的一致性，使其成为在需要高性能的同时，又必须确保跨硬件结果可靠性和可预测性的机器学习加速的理想选择。

有关 DirectML 的更多信息，请参阅 DirectML 简介。

• 开始使用 DirectML
  • 硬件要求
  • 面向应用开发者
  • 面向用户、数据科学家和研究人员
• DirectML 示例
• DxDispatch 工具
• 基于 DirectML 的 Windows ML
• 基于 DirectML 的 ONNX Runtime
• PyTorch 结合 DirectML
• TensorFlow 结合 DirectML
• 反馈
• 外部链接
  • 文档
  • 更多信息
• 贡献

访问 DirectX 登陆页 获取更多针对 DirectX 开发者的资源。

开始使用 DirectML

DirectML 作为 Windows 10 的系统组件分发，并自 Windows 10 版本 1903（10.0；内部版本 18362）及更高版本起，已包含在 Windows 10 操作系统中。

从 DirectML 版本 1.4.0 开始，DirectML 也以独立的可再分发包形式提供（参见 Microsoft.AI.DirectML），这对于希望使用固定版本 DirectML 的应用程序，或在较旧版本的 Windows 10 上运行的应用程序非常有用。

硬件要求

DirectML 需要一台支持 DirectX 12 的设备。过去几年内发布的几乎所有市售显卡都支持 DirectX 12。兼容硬件的例子包括：

• AMD GCN 第一代（Radeon HD 7000 系列）及以上
• Intel Haswell（第四代 Core）集成显卡及以上
• NVIDIA Kepler（GTX 600 系列）及以上
• Qualcomm Adreno 600 及以上

面向应用开发者

DirectML 提供原生 C++ DirectX 12 API。头文件和库（DirectML.h/DirectML.lib）既包含在 可再分发的 NuGet 包 中，也包含在 Windows 10 SDK 版本 10.0.18362 或更高版本中。

• 可从 Windows 开发者中心 下载 Windows 10 SDK
• NuGet 目录上的 Microsoft.AI.DirectML
• DirectML 编程指南
• DirectML API 参考

面向用户、数据科学家和研究人员

DirectML 内置为多个框架的后端，例如 Windows ML、ONNX Runtime 和 TensorFlow。

更多信息请参阅以下章节：

• 基于 DirectML 的 Windows ML
• 基于 DirectML 的 ONNX Runtime
• TensorFlow 结合 DirectML
• PyTorch 结合 DirectML

DirectML 示例

DirectML 的 C++ 示例代码可在 Samples 目录下找到。

• HelloDirectML：一个极简的“Hello World”应用程序，仅执行一个 DirectML 算子。
• DirectMLNpuInference：展示如何使用 NPU 硬件与 DirectML 配合的示例。
• DirectMLSuperResolution：利用 DirectML 执行一个基础的超分辨率模型，将 540p 视频实时上采样至 1080p 的示例。
• yolov4：YOLOv4 是一种目标检测模型，能够识别图像中的多达 80 类物体。该示例包含使用 DirectML 完整实现的端到端模型，并且能够在用户提供的视频流上实时运行。

DirectML 的 Python 示例代码可在 Python/samples 目录下找到。这些示例需要 PyDirectML，这是一个用于 DirectML 的开源 Python 投影库，可以从 Python/src 构建并安装到 Python 执行环境中。更多详细信息请参阅 Python/README.md 文件。

• MobileNet：改编自 ONNX MobileNet 模型。MobileNet 可将图像分类为 1000 个不同类别，其速度和体积都非常高效，非常适合移动应用。
• MNIST：改编自 ONNX MNIST 模型。MNIST 使用卷积神经网络预测手写数字。
• SqueezeNet：基于 ONNX SqueezeNet 模型。SqueezeNet 在 ImageNet 数据集上训练的图像分类任务中表现出色，效率极高且准确率良好。
• FNS-Candy：改编自 Windows ML 风格迁移模型 示例，FNS-Candy 可以将特定的艺术风格重新应用于普通图像。
• Super Resolution：改编自 ONNX 超分辨率模型，该模型可对输入图像进行上采样和锐化，从而细化细节并提升图像质量。

DxDispatch 工具

DxDispatch 是一个简单的命令行可执行文件，用于在无需编写所有 C++ 模板代码的情况下启动 DirectX 12 计算程序（包括 DirectML 算子）。

Windows ML on DirectML

Windows ML (WinML) 是一个高性能、可靠的 API，用于在 Windows 设备上部署硬件加速的机器学习推理。DirectML 为 Windows ML 提供 GPU 后端支持。

通过使用 LearningModelDevice，结合任意一种 DirectX DeviceKinds，可以在 Windows ML 中启用 DirectML 加速。

有关更多信息，请参阅 开始使用 Windows ML。

• Windows 机器学习概述 (docs.microsoft.com)
• Windows 机器学习 GitHub 仓库
• WinMLRunner，一个使用 WinML 和 DirectML 执行 ONNX 模型的工具

ONNX Runtime on DirectML

ONNX Runtime 是一个跨平台的推理和训练加速器，兼容多种流行的机器学习/DNN 框架，包括 PyTorch、TensorFlow/Keras、scikit-learn 等。

DirectML 可作为 ONNX Runtime 的可选 执行提供者，在 Windows 10 上运行时提供硬件加速功能。

有关入门的更多信息，请参阅 使用 DirectML 执行提供者。

• ONNX Runtime 主页
• ONNX Runtime GitHub 仓库
• DirectML 执行提供者说明文档

PyTorch with DirectML

PyToch 与 DirectML 结合，可在广泛的 DirectX 12 兼容硬件上进行复杂机器学习模型的训练和推理。这是通过 torch-directml 这一 PyTorch 插件实现的。

PyTorch 与 DirectML 同时支持最新的 Windows 版本以及 Windows Subsystem for Linux，并且可以作为 PyPI 包下载。有关如何开始使用 torch-directml 的更多信息，请参阅我们在 Microsoft Learn 上提供的 Windows 或 WSL 2 指南。

• torch-directml PyPI 项目
• PyTorch 与 DirectML 示例
• PyTorch 主页

TensorFlow with DirectML

TensorFlow 是一个广受欢迎的开源机器学习平台，也是训练机器学习模型的领先框架。

适用于 TensorFlow 1.15 的 DirectML 加速目前处于公开预览阶段。TensorFlow on DirectML 使复杂的机器学习模型能够在广泛的 DirectX 12 兼容硬件上进行训练和推理。

TensorFlow on DirectML 同时支持最新的 Windows 10 版本以及 Windows 子系统 for Linux，并且可以作为 PyPI 包下载。有关入门的更多信息，请参阅 GPU 加速的机器学习训练 (docs.microsoft.com)。

• TensorFlow on DirectML GitHub 仓库
• TensorFlow on DirectML 示例
• tensorflow-directml PyPI 项目
• TensorFlow GitHub | 关于 TensorFlow on DirectML 的 RFC
• TensorFlow 主页

反馈

我们期待您的反馈！

• 如遇 TensorFlow 与 DirectML 相关的问题、漏洞或反馈，或关于 DirectML 的一般性问题与反馈，请在 GitHub 上提交 issue 或直接发送邮件至 askdirectml@microsoft.com。

• 如遇 PyTorch 与 DirectML 相关的问题、漏洞或反馈，或关于 DirectML 的一般性问题与反馈，请在 GitHub 上提交 issue 或直接发送邮件至 askdirectml@microsoft.com。

• 如遇 Windows ML 相关的问题，请在 microsoft/Windows-Machine-Learning 提交 GitHub issue，或直接发送邮件至 askwindowsml@microsoft.com。

• 如遇 ONNX Runtime 相关的问题，请在 microsoft/onnxruntime 提交 issue。

外部链接

文档

DirectML 编程指南
DirectML API 参考

更多信息

介绍 DirectML（2019 年游戏开发者大会）
利用 DirectML 和 DirectX 12 加速 GPU 推理（2018 年 SIGGRAPH）
Windows AI：Windows 设备上的硬件加速机器学习（2020 年 Microsoft Build）
使用 Windows ML 进行游戏开发（DirectX 开发者博客）
DirectML 在 GDC 2019 上的亮相（DirectX 开发者博客）
DirectX ❤ Linux（DirectX 开发者博客）

贡献

本项目欢迎各类贡献和建议。大多数贡献都需要您签署贡献者许可协议（CLA），以声明您有权并将您的贡献权利授予我们使用。有关详情，请访问 https://cla.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地为 PR 添加标记或评论。请按照机器人提供的指示操作即可。对于所有使用我们 CLA 的仓库，您只需完成一次此流程。

本项目已采纳 Microsoft 开源行为准则。如需更多信息，请参阅 行为准则常见问题解答，或如有任何其他问题或意见，请联系 opencode@microsoft.com。

DirectML 快速上手指南

⚠️ 重要提示：维护模式 DirectML 目前处于维护模式。

• 如果您使用的是 Windows 11 24H2 (Build 26100) 或更高版本，建议迁移至 Windows ML 以获得更好的支持。
• DirectML 将继续在旧版 Windows 上受支持，并提供安全修复，但不再计划新增功能。
• 本仓库中的示例代码和 Issue 将不再更新。

DirectML 是一个高性能、硬件加速的 DirectX 12 机器学习库。它支持所有兼容 DirectX 12 的 GPU（包括 AMD、Intel、NVIDIA 和 Qualcomm），无需特定厂商驱动即可实现跨硬件的机器学习加速。

1. 环境准备

系统要求

• 操作系统：
  • Windows 10 版本 1903 (Build 18362) 或更高版本（系统内置）。
  • 或通过独立包支持更早的 Windows 10 版本。
• 硬件：必须拥有支持 DirectX 12 的显卡。
  • AMD: GCN 1st Gen (Radeon HD 7000 系列) 及以上
  • Intel: Haswell (第 4 代酷睿) 集成显卡及以上
  • NVIDIA: Kepler (GTX 600 系列) 及以上
  • Qualcomm: Adreno 600 及以上

前置依赖

• 对于应用开发者 (C++)：
  • 安装 Windows 10 SDK (版本 10.0.18362 或更新)。
• 对于数据科学家/研究者 (Python)：
  • 安装 Python 环境。
  • 根据使用的框架安装对应的 DirectML 插件（见下文安装步骤）。

---

2. 安装步骤

根据您的使用场景选择以下一种安装方式：

方案 A：Python 数据科学与模型推理 (推荐)

DirectML 可作为后端加速 ONNX Runtime、PyTorch 或 TensorFlow。

1. 使用 ONNX Runtime (通用推理)

适用于运行导出的 ONNX 模型，支持 PyTorch/TensorFlow 等训练出的模型。

pip install onnxruntime-directml

2. 使用 PyTorch

通过 torch-directml 插件在 Windows 或 WSL2 上启用 DirectML 加速。

pip install torch-directml

3. 使用 TensorFlow

适用于 TensorFlow 1.15 版本的加速（公共预览版）。

pip install tensorflow-directml

注：国内用户若下载缓慢，可添加国内镜像源参数，例如： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <包名>

方案 B：C++ 应用开发

方式 1：使用 NuGet 包（推荐，可固定版本）

在 Visual Studio 的项目目录中打开命令行，或使用 .csproj/.vcxproj 管理：

Install-Package Microsoft.AI.DirectML

方式 2：使用 Windows SDK

确保已安装 Windows 10 SDK (10.0.18362+)，在 C++ 项目中直接包含头文件并链接库：

• 头文件：#include <DirectML.h>
• 库文件：DirectML.lib (SDK 自动包含)

---

3. 基本使用

场景一：Python 中使用 PyTorch + DirectML

安装 torch-directml 后，只需将设备指定为 "dml" 即可利用 GPU 加速。

import torch
import torch_directml

# 检查 DirectML 是否可用
if torch_directml.is_available():
    print("DirectML is available!")
    
    # 创建 DirectML 设备
    device = torch_directml.device()
    
    # 将模型和数据移动到 DirectML 设备
    model = MyModel().to(device)
    data = torch.randn(32, 3, 224, 224).to(device)
    
    # 执行推理或训练
    output = model(data)
    print(output.shape)
else:
    print("DirectML not available on this system.")

场景二：Python 中使用 ONNX Runtime + DirectML

加载 ONNX 模型并指定 execution_provider 为 DmlExecutionProvider。

import onnxruntime as ort

# 定义会话选项，启用 DirectML
sess_options = ort.SessionOptions()
sess_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL

# 创建推理会话，优先使用 DirectML
providers = ['DmlExecutionProvider', 'CPUExecutionProvider']
session = ort.InferenceSession("model.onnx", sess_options, providers=providers)

# 运行推理
input_name = session.get_inputs()[0].name
output_name = session.get_outputs()[0].name
result = session.run([output_name], {input_name: input_data})

场景三：C++ 最小化示例 (HelloDirectML)

以下是使用原生 C++ API 初始化设备并创建命令列表的核心逻辑片段：

#include <DirectML.h>
#include <wrl/client.h>
#include <dxgi1_4.h>
#include <d3d12.h>

// 假设已初始化 D3D12 设备和命令队列 (device, commandQueue)
Microsoft::WRL::ComPtr<IDMLDevice> dmlDevice;
DMLCreateDevice(d3d12Device.Get(), DML_CREATE_DEVICE_FLAG_NONE, IID_PPV_ARGS(&dmlDevice));

// 创建命令记录器
Microsoft::WRL::ComPtr<IDMLCommandRecorder> commandRecorder;
dmlDevice->CreateCommandRecorder(IID_PPV_ARGS(&commandRecorder));

// 后续可在此绑定算子 (Operators) 并执行...

更多完整的 C++ 和 Python 示例代码请参考项目源码中的 Samples 和 Python/samples 目录。