DirectML 디버그 계층 사용

DirectML 디버그 계층은 DirectML 코드를 디버깅하는 데 도움이 되는 선택적 개발 시간 구성 요소입니다. 사용하도록 설정하면 DirectML 디버그 계층이 DirectML API 호출을 래핑하고 개발자로서 추가 유효성 검사 및 메시지를 제공합니다. 디버그 계층은 런타임 시 핵심 런타임 라이브러리 DirectML.Debug.dll에 의해 조건부로 로드되는 별도의 라이브러리에 구현됩니다 DirectML.dll.

잘못된 API 사용 시 귀중한 정보를 제공할 수 있으므로 DirectML을 사용하여 애플리케이션을 개발하는 동안 디버그 계층을 사용하도록 설정하는 것이 좋습니다.

디버그 계층 메시지 개요

아래 코드 예제에서는 디버그 계층이 잘못된 API 사용을 진단하는 데 어떻게 도움이 되는지 보여 줍니다. 이 코드는 DirectML ID 작업을 생성하려고 합니다. 따라서 입력 및 출력 텐서의 모양과 데이터 형식이 같아야 합니다. 그러나 이 예제에서는 출력 텐서 매개 변수의 실수를 보여 줍니다.

uint32_t sizes[] = { 1 };

DML_BUFFER_TENSOR_DESC inputBufferDesc = {};
inputBufferDesc.DataType = DML_TENSOR_DATA_TYPE_FLOAT32;
inputBufferDesc.DimensionCount = ARRAYSIZE(sizes);
inputBufferDesc.Sizes = sizes;
inputBufferDesc.TotalTensorSizeInBytes = 256;

DML_BUFFER_TENSOR_DESC outputBufferDesc = {};
outputBufferDesc.DataType = DML_TENSOR_DATA_TYPE_FLOAT16; // Invalid: doesn't match input type!
outputBufferDesc.DimensionCount = ARRAYSIZE(sizes);
outputBufferDesc.Sizes = sizes;
outputBufferDesc.TotalTensorSizeInBytes = 256;

DML_TENSOR_DESC inputDesc = { DML_TENSOR_TYPE_BUFFER, &inputBufferDesc };
DML_TENSOR_DESC outputDesc = { DML_TENSOR_TYPE_BUFFER, &outputBufferDesc };

DML_ELEMENT_WISE_IDENTITY_OPERATOR_DESC identityDesc = {};
identityDesc.InputTensor = &inputDesc;
identityDesc.OutputTensor = &outputDesc;

DML_OPERATOR_DESC opDesc = { DML_OPERATOR_ELEMENT_WISE_IDENTITY, &identityDesc };

Microsoft::WRL::ComPtr<IDMLOperator> op;
THROW_IF_FAILED(dmlDevice->CreateOperator(&opDesc, IID_PPV_ARGS(&op)));

DirectML 디버그 계층이 없으면 연산자를 만드는 마지막 줄이 실패하고 반환 E_INVALIDARG 됩니다(0x80070057). THROW_IF_FAILED 매크로(자세한 내용은 WIL 참조)는 해당 오류 코드를 "매개 변수가 잘못되었습니다"라는 일반 메시지로 변환하고 디버거 출력 창에 출력합니다.

TensorValidator.h(203)\DirectML.dll!00007FF83D25ADC9: (caller: 00007FF83D267523) Exception(1) tid(3b54) 80070057 The parameter is incorrect.

그러나 DirectML 디버그 계층 을 사용하도록 설정하면 원인을 좁히기 위한 추가 정보가 표시됩니다.

D3D12 ERROR: Mismatched tensor data types. Tensor 'Output' has DataType of DML_TENSOR_DATA_TYPE_FLOAT16, while tensor 'Input' has DataType of DML_TENSOR_DATA_TYPE_FLOAT32. Both tensors are expected to have the same DataType. [ UNKNOWN ERROR #1: STRING_FROM_APPLICATION]

TensorValidator.h(203)\DirectML.Debug.dll!00007FF86DF66ADA: (caller: 00007FF86DF81646) Exception(1) tid(9f34) 80070057 The parameter is incorrect.

확장 정보가 D3D12 ERROR로 시작하는 방법을 확인합니다. DirectML 디버그 계층이 문제를 검색하는 경우 DirectML 디바이스를 만드는 동안 전달된 ID3D12Device와 연결된 ID3D12InfoQueue에 오류 메시지를 항상 보내는 것이 좋습니다. 정보 큐의 오류 메시지는 위와 같이 항상 D3D12 ERROR 접두사로 지정됩니다. Direct3D 12 디버그 계층 메시지 콜백을 사용하여 프로그래밍 방식으로 액세스할 수도 있습니다(블로그 게시물 D3D12 디버그 계층 메시지 콜백 참조).

ID3D12InfoQueue는 ID3D12Debug::EnableDebugLayer를 사용하여 Direct3D 12 디버그 계층을 사용하도록 설정한 경우에만 사용할 수 있습니다. Direct3D 12 및 DirectML 디버그 계층을 함께 사용하거나 사용하지 않도록 설정하는 것이 항상 바람직하지만, 최신 버전의 DirectML은 Direct3D 12 디버그 계층 없이 기본 매개 변수 유효성 검사를 지원합니다. Direct3D 12 디버그 계층이 활성화되지 않은 동안 DML_CREATE_DEVICE_FLAG_DEBUG 있는 DirectML 디바이스를 만드는 경우 OutputDebugStringA를 사용하여 오류 메시지가 인쇄됩니다.

[DIRECTML WARNING]: enable the D3D debug layer for enhanced validation with DML_CREATE_DEVICE_FLAG_DEBUG.

[DIRECTML ERROR]: Mismatched tensor data types. Tensor 'Output' has DataType of DML_TENSOR_DATA_TYPE_FLOAT16, while tensor 'Input' has DataType of DML_TENSOR_DATA_TYPE_FLOAT32. Both tensors are expected to have the same DataType.

TensorValidator.h(218)\DirectML.Debug.dll!00007FF820C43AFB: (caller: 00007FF820C01CD1) Exception(1) tid(5df8) 80070057 The parameter is incorrect.

경고 메시지에서 알 수 있듯이 DirectML 디버그 계층을 사용할 때 Direct3D 12 디버그 계층을 사용하도록 설정하는 것이 가장 좋습니다. 일부 유형의 유효성 검사는 두 디버그 계층이 모두 사용하도록 설정된 경우에만 가능합니다.

DirectML 및 Direct3D 12 디버그 계층 설치(시스템 구성 요소)

DirectML을 시스템 구성 요소로 사용하는 경우( DirectML 버전 기록 참조) 디버그 계층은 FOD(주문형 기능 참조)로 배포되는 별도의 그래픽 도구 패키지 의 일부입니다. DirectML의 시스템 버전에서 디버그 계층을 사용하려면 그래픽 도구 FOD를 시스템에 추가해야 합니다. 또한 FOD에는 Direct3D 12 디버그 계층이 포함되어 있으며 DirectML 애플리케이션 디버깅에도 유용하지만 필요하지는 않습니다.

선택적 그래픽 도구 FOD 패키지를 추가하려면 관리자 Powershell 프롬프트에서 다음 명령을 실행합니다.

Add-WindowsCapability -Online -Name "Tools.Graphics.DirectX~~~~0.0.1.0"

또는 Windows 설정 내에서 그래픽 도구 패키지를 추가할 수 있습니다. Windows 10 22H2 및 Windows 11에서 설정>시스템>선택적 기능>으로 이동하여선택적 기능을 추가한 다음 그래픽 도구를 검색합니다. Windows 10 22H2 이전 버전에서 설정>앱>앱 및 기능>으로 이동하여 대신> 추가합니다.

DirectML 디버그 계층 설치(독립 실행형 재배포 가능)

DirectML을 독립 실행형 재배포 가능 라이브러리( Microsoft.AI.DirectML 참조)로 사용하는 경우 DirectML 디버그 계층은 핵심 런타임 라이브러리와 함께 패키지에 제공됩니다. 애플리케이션의 실행 파일 옆에 둘 다 DirectML.Debug.dllDirectML.dll 배치합니다.

Visual Studio를 사용하여 NuGet 패키지 종속성으로 추가하는 Microsoft.AI.DirectML 경우 프로젝트는 핵심 런타임 및 디버그 계층 라이브러리 복사를 복사하거나 건너뛰는 옵션을 프로젝트 구성 페이지에 표시합니다. 기본적으로 DirectML NuGet 패키지는 항상 두 DLL을 프로젝트 출력 폴더에 복사하도록 구성됩니다. 그러나 디버그 계층이 사용되지 않는 경우 릴리스 빌드에서 디버그 계층 복사를 건너뛸 수 있습니다.

Visual Studio의 재배포 가능 디버그 계층

Direct3D 12 디버그 계층 사용

Direct3D 12(d3d12sdklayers.dll)의 디버그 계층은 DirectML 디버그 계층(DirectML.Debug.dll)과 독립적입니다. DirectML 디버그 계층은 DirectML API 사용에 대해 향상된 유효성 검사를 제공하고 Direct3D 12 디버그 계층은 Direct3D 12 API 사용을 포함합니다. 그러나 실제로는 DirectML 애플리케이션을 개발할 때 두 디버그 계층을 모두 사용하도록 설정하는 것이 가장 좋습니다. Direct3D 12 디버그 계층은 위에서 설명한 그래픽 도구 FOD의 일부로 설치됩니다. Direct3D 12 디버그 계층을 활성화하는 방법에 대한 예제는 ID3D12Debug::EnableDebugLayer 를 참조하세요.

중요합니다

먼저 Direct3D 12 디버그 계층을 사용하도록 설정해야 합니다. 그런 다음DMLCreateDevice를 호출하여 DirectML 디버그 계층을 사용하도록 설정합니다.