DirectMLX
DirectMLX 是 DirectML 的 C++ 仅标头帮助程序库,旨在更轻松地将单个运算符组合到图形中。
DirectMLX 为所有 DirectML (DML) 运算符类型以及直观的运算符重载提供了方便的包装器,这使得实例化 DML 运算符并将其链接到复杂图形中的过程变得更加简单。
查找 DirectMLX.h
的位置
DirectMLX.h
在 MIT 许可证下以开源软件的形式分发。 可以在 DirectML GitHub 上找到最新版本。
版本要求
DirectMLX 需要 DirectML 版本 1.4.0 或更高版本(请参阅 DirectML 版本历史记录)。 不支持较旧的 DirectML 版本。
DirectMLX.h 需要支持 C++11 的编译器,包括(但不限于):
- Visual Studio 2017
- Visual Studio 2019
- Clang 10
请注意,我们建议使用 C++17(或更高版本)编译器。 可以针对 C++11 进行编译,但需要使用第三方库(例如 GSL 和 Abseil)来替代缺失的标准库功能。
如果配置无法编译 DirectMLX.h
,请在 GitHub 上提出问题。
基本用法
#include <DirectML.h>
#include <DirectMLX.h>
IDMLDevice* device;
/* ... */
dml::Graph graph(device);
// Input tensor of type FLOAT32 and sizes { 1, 2, 3, 4 }
auto x = dml::InputTensor(graph, 0, dml::TensorDesc(DML_TENSOR_DATA_TYPE_FLOAT32, {1, 2, 3, 4}));
// Create an operator to compute the square root of x
auto y = dml::Sqrt(x);
// Compile a DirectML operator from the graph. When executed, this compiled operator will compute
// the square root of its input.
DML_EXECUTION_FLAGS flags = DML_EXECUTION_FLAG_NONE;
ComPtr<IDMLCompiledOperator> op = graph.Compile(flags, { y });
// Now initialize and dispatch the DML operator as usual
以下是另一个示例,在该例中创建能够计算二次公式的 DirectML 图形。
#include <DirectML.h>
#include <DirectMLX.h>
IDMLDevice* device;
/* ... */
std::pair<dml::Expression, dml::Expression>
QuadraticFormula(dml::Expression a, dml::Expression b, dml::Expression c)
{
// Quadratic formula: given an equation of the form ax^2 + bx + c = 0, x can be found by:
// x = -b +/- sqrt(b^2 - 4ac) / (2a)
// https://en.wikipedia.org/wiki/Quadratic_formula
// Note: DirectMLX provides operator overloads for common mathematical expressions. So for
// example a*c is equivalent to dml::Multiply(a, c).
auto x1 = -b + dml::Sqrt(b*b - 4*a*c) / (2*a);
auto x2 = -b - dml::Sqrt(b*b - 4*a*c) / (2*a);
return { x1, x2 };
}
/* ... */
dml::Graph graph(device);
dml::TensorDimensions inputSizes = {1, 2, 3, 4};
auto a = dml::InputTensor(graph, 0, dml::TensorDesc(DML_TENSOR_DATA_TYPE_FLOAT32, inputSizes));
auto b = dml::InputTensor(graph, 1, dml::TensorDesc(DML_TENSOR_DATA_TYPE_FLOAT32, inputSizes));
auto c = dml::InputTensor(graph, 2, dml::TensorDesc(DML_TENSOR_DATA_TYPE_FLOAT32, inputSizes));
auto [x1, x2] = QuadraticFormula(a, b, c);
// When executed with input tensors a, b, and c, this compiled operator computes the two outputs
// of the quadratic formula, and returns them as two output tensors x1 and x2
DML_EXECUTION_FLAGS flags = DML_EXECUTION_FLAG_NONE;
ComPtr<IDMLCompiledOperator> op = graph.Compile(flags, { x1, x2 });
// Now initialize and dispatch the DML operator as usual
更多示例
可以在 DirectML GitHub 存储库中找到使用 DirectMLX 的完整示例。
编译时选项
DirectMLX 支持使用编译时定义来自定义标头的各个部分。
选项 | 说明 |
---|---|
DMLX_NO_EXCEPTIONS | 如已定义,会导致错误,从而调用 std::abort 而不是引发异常。 如果异常不可用(例如,在编译器选项中禁用了异常),则默认定义此项。 |
DMLX_USE_WIL | 如已定义,则使用 Windows 实现库异常类型引发异常。 否则,将改用标准异常类型(例如 std::runtime_error )。 如果定义了 DMLX_NO_EXCEPTIONS,则此选项不起作用。 |
DMLX_USE_ABSEIL | 如已定义,请使用 Abseil 随时替代 C++11 中不可用的标准库类型。 这些类型包括 absl::optional (替代 std::optional )、absl::Span (替代 std::span )和 absl::InlinedVector 。 |
DMLX_USE_GSL | 控制是否使用 GSL 作为 std::span 的替代项。 如已定义,则在没有本机 std::span 实现的编译器上,使用 gsl::span 替代 std::span 。 否则,会改为提供内联嵌入式实现。 请注意,仅当在不支持 std::span 的 C++20 之前的编译器上进行编译时,以及未使用其他嵌入式标准库替代项(如 Abseil)时,才使用此选项。 |
控制张量布局
对于大多数运算符,DirectMLX 代表你计算运算符的输出张量的属性。 例如,当使用大小为 dml::Reduce
的输入张量跨轴 { 0, 2, 3 }
执行 { 3, 4, 5, 6 }
时,DirectMLX 将自动计算输出张量的属性,包括 { 1, 4, 1, 1 }
的正确形状。
但是,输出张量的其他属性包括 Strides、TotalTensorSizeInBytes 和 GuaranteedBaseOffsetAlignment。 默认情况下,DirectMLX 设置这些属性,使得张量不会产生步幅,没有保证的基本偏移对齐,以及使用 DMLCalcBufferTensorSize 计算的总张量大小(以字节为单位)。
DirectMLX 支持使用称为张量策略的对象自定义这些输出张量属性的功能。 TensorPolicy 是 DirectMLX 调用的可自定义回调,在给定张量计算数据类型、标志和大小的情况下返回输出张量属性。
可以在 dml::Graph 对象上设置张量策略,并将其用于该图形上的所有后续运算符。 还可以在构造 TensorDesc 时直接设置张量策略。
因此,可以通过设置 TensorPolicy 来控制 DirectMLX 生成的张量布局,该 TensorPolicy 会在其张量上设置适当的步幅。
示例 1
// Define a policy, which is a function that returns a TensorProperties given a data type,
// flags, and sizes.
dml::TensorProperties MyCustomPolicy(
DML_TENSOR_DATA_TYPE dataType,
DML_TENSOR_FLAGS flags,
Span<const uint32_t> sizes)
{
// Compute your custom strides, total tensor size in bytes, and guaranteed base
// offset alignment
dml::TensorProperties props;
props.strides = /* ... */;
props.totalTensorSizeInBytes = /* ... */;
props.guaranteedBaseOffsetAlignment = /* ... */;
return props;
};
// Set the policy on the dml::Graph
dml::Graph graph(/* ... */);
graph.SetTensorPolicy(dml::TensorPolicy(&MyCustomPolicy));
示例 2
DirectMLX 还提供内置的备用张量策略。 例如,InterleavedChannel 策略是为了方便而提供的,它可用于生成具有步幅的张量,以便按 NHWC 顺序写入张量。
// Set the InterleavedChannel policy on the dml::Graph
dml::Graph graph(/* ... */);
graph.SetTensorPolicy(dml::TensorPolicy::InterleavedChannel());
// When executed, the tensor `result` will be in NHWC layout (rather than the default NCHW)
auto result = dml::Convolution(/* ... */);