Important
Windows ML 런타임 API는 현재 실험적이며 프로덕션 환경에서의 사용은 지원되지 않습니다. 이 API를 시도하는 앱은 Microsoft Store에 게시해서는 안 됩니다.
Important
Windows ML 런타임 API는 현재 C++ 및 Python에서 사용할 수 있으며, C#은 현재 지원되지 않습니다. C#에서 이러한 API를 사용하는 데 관심이 있다면 Windows ML GitHub 리포지토리에 문제를 게시하여 알려주세요.
Windows ML 런타임 API는 Windows용으로 특별히 빌드된 네이티브 C/C++ 로컬 AI 추론 프레임워크입니다. Windows ML 런타임 API를 사용하면 모델을 로드하고, CPU, GPU 또는 NPU 실행 대상(특정 DXCore 어댑터 또는 D3D12 디바이스 포함)을 선택하고, 해당 대상에 텐서를 바인딩하고, 모델 및 프로세서 단계를 파이프라인으로 작성하고, 파이프라인을 컴파일하고, 실행하여 출력 텐서를 생성할 수 있습니다.
선택적 텍스트 생성 및 음성 인식 API는 앱에서 제공하는 모델을 통해 이러한 동일한 런타임 개체를 상위 수준 워크플로로 구성합니다. Windows ML을 사용하여 사용자 고유의 언어 모델로 텍스트 생성 및 Windows ML을 사용하여 사용자 고유의 Whisper 모델로 음성 인식 참조
런타임 API 및 ONNX 런타임
앱이 Windows만 대상으로 하고 현재 실험적인 API를 사용하려는 경우 런타임 API를 사용하세요. 하드웨어 선택(특정 DXCore 어댑터 또는 D3D12 디바이스 포함), 텐서 상주, 다단계 파이프라인 배치 및 컴파일을 명시적으로 제어할 수 있습니다.
그렇지 않은 경우 앱이 다른 플랫폼에서 실행되어야 하거나 이미 플랫폼 간 ONNX 런타임 세션 코드가 작동하는 경우 Windows ML에 포함된 ONNX 런타임 API를 대신 사용합니다.
핵심 개체 모델
| Concept | 기본 API | Description |
|---|---|---|
| Runtime | IWinMLRuntime |
WinMLCreateRuntime에서 반환되는 인터페이스는 모델 파일을 로드하고, 실행 대상을 만들고, 파이프라인 빌더를 만듭니다. |
| 모델 | IWinMLModel |
파일 또는 버퍼에서 로드된 변경할 수 없는 불투명 모델 아티팩트입니다.
IWinMLModelSchema를 통해 선언된 스키마를 반영합니다. |
| 실행 대상 | IWinMLExecutionTarget |
단계를 빌드하고 텐서를 만드는 데 사용되는 CPU, GPU 또는 NPU 배치 토큰입니다. |
| 파이프라인 빌더 | IWinMLPipelineBuilder |
모델 및 프로세서 단계를 추가하고, 연결하고, 준비된 파이프라인을 빌드합니다. |
| Pipeline | IWinMLPipeline |
바인딩된 텐서를 실행하고 출력 텐서를 생성하는 즉시 실행 가능한 준비된 그래프입니다. |
| 단계 | IWinMLStage |
위치 입력 및 출력 바인딩 및 확정된 실행 대상을 소유하는 파이프라인의 단계입니다. |
| 텐서 | IWinMLTensor |
스테이지 입력 및 출력에 바인딩된 형식화된 다차원 데이터입니다. |
| 텍스트 생성/음성 인식 | Windows ML 텍스트 생성 및 음성 인식 API | 형식화된 세션, 스트림 및 결과를 사용하여 호출자 소유 Runtime 객체 위에 구성된 상위 수준 워크플로입니다. |
백 엔드 및 실행 대상 선택
LoadModelFromFile 는 모델 아티팩트의 파일 확장자에서 백 엔드를 선택합니다.
앱은 파일을 로드하는 백 엔드에 관계없이 모델, 실행 대상, 파이프라인 작성기, 스테이지, 바인딩 및 Run 같은 동일한 런타임 개체를 사용합니다.
| 모델 파일 | Backend | 하드웨어 가속 |
|---|---|---|
.onnx, .ort |
ONNX 런타임 | Windows ML EP 카탈로그를 통해 Windows가 설치하고 최신 상태로 유지하는 실행 공급자(EP) |
.gguf |
llama.cpp | 앱 로컬 CPU 모듈과 앱과 함께 배포하는 NVIDIA GPU용 선택적 CUDA 모듈 CPU 및 CUDA는 Windows ML이 이번 릴리스에서 유효성을 검증하는 유일한 llama.cpp 백엔드입니다. |
실행 대상은 IWinMLRuntime로 생성된 하드웨어 클래스(CPU, GPU 또는 NPU)를 나타내는 것입니다. 대상을 다시 사용하여 스테이지를 빌드하고 텐서를 만듭니다. 한 대상을 다시 사용하면 동일 대상 친화성을 나타내고, 고유 대상을 사용하면 대상 간 전이 경계가 명시적으로 지정됩니다. 파이프라인 작성기의 Build 메서드가 실행되면 런타임은 대상에 대한 실행 백 엔드에 각 단계를 배치하고 대상 및 백 엔드 호환성을 확정합니다.
디바이스를 직접 열거하지 않는 하드웨어 클래스의 경우, 통합 GPU와 외장 GPU처럼 해당 클래스의 후보 순위를 지정하는 WINML_EXECUTION_TARGET_KIND와 CreateExecutionTarget를 함께 사용하여 WINML_EXECUTION_TARGET_PREFERENCE를 호출합니다.
ERROR_NOT_FOUND와 ERROR_NOT_SUPPORTED를 동일하게 처리하고 다른 클래스로 대체합니다.
ComPtr<IWinMLExecutionTarget> target;
HRESULT hr = runtime->CreateExecutionTarget(
WINML_EXECUTION_TARGET_KIND_NPU,
WINML_EXECUTION_TARGET_PREFERENCE_EFFICIENCY,
target.GetAddressOf());
if (hr == HRESULT_FROM_WIN32(ERROR_NOT_FOUND) ||
hr == HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED))
{
THROW_IF_FAILED(runtime->CreateExecutionTarget(
WINML_EXECUTION_TARGET_KIND_GPU,
WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
target.GetAddressOf()));
}
else
{
THROW_IF_FAILED(hr);
}
CreateCpuExecutionTarget 는 CPU 종류를 요청하는 것과 같습니다.
CreateExecutionTargetFromAdapter 및 CreateExecutionTargetFromD3D12는 런타임이 하나를 선택하도록 하는 대신 대상을 특정 DXCore 어댑터 또는 D3D12 디바이스에 바인딩합니다. 설치된 EP(실행 공급자)에 의존하는 ONNX 모델의 경우, 선택적 ONNX 런타임 호환성 계층을 통해 이미 등록한 공급자를 고정할 수 있습니다.
각 백엔드는 이러한 대상을 서로 다르게 처리합니다. 예를 들어 .gguf 모델에서 사용되는 llama.cpp 백엔드는 GPU 대상을 적용하기 위해 최소한 부분적인 GPU 오프로드가 필요하며 NPU 대상 또는 공급자 고정을 지원하지 않습니다. 백엔드당 전체 대상 해상도 매트릭스 및 GGUF 모델 실행 방법에 대한 설명은 Windows ML Runtime API concepts을 참조하세요.