Übersicht über Windows ML-Runtime-API

Important

Die Windows ML-Runtime-API ist derzeit experimentell und wird für die Verwendung in Produktionsumgebungen nicht unterstützt. Apps, die diese API ausprobieren, sollten nicht im Microsoft Store veröffentlicht werden.

Important

Die Windows ML-Runtime-API ist derzeit in C++ und Python verfügbar; C# wird derzeit nicht unterstützt. Lassen Sie uns wissen, ob Sie diese APIs von C# verwenden möchten, indem Sie ein Problem im Windows ML GitHub-Repository veröffentlichen!

Die Windows ML-Runtime-API ist ein systemeigenes lokales C/C++-KI-Inferencing-Framework, das speziell für Windows erstellt wurde. Mit der Windows ML-Runtime-API können Sie ein Modell laden, ein CPU-, GPU- oder NPU-Ausführungsziel (einschließlich eines bestimmten DXCore-Adapters oder D3D12-Geräts) auswählen, Tensoren an dieses Ziel binden, Modell- und Prozessorphasen zu einer Pipeline zusammensetzen, die Pipeline kompilieren und ausführen, um Ausgabe-Tensoren zu erzeugen.

Die optionalen APIs für die Textgenerierung und Spracherkennung fügen dieselben Laufzeitobjekte zu Workflows höherer Ebene auf Basis eines von Ihrer App bereitgestellten Modells zusammen: Siehe Generieren von Text mit ihrem eigenen Sprachmodell mithilfe von Windows ML und Erkennen von Sprache mit Ihrem eigenen Whisper-Modell mit Windows ML.

Runtime API im Vergleich zur ONNX Runtime

Wenn Ihre App nur auf Windows ausgerichtet ist (und Sie bereit sind, APIs zu verwenden, die derzeit experimentell sind), verwenden Sie die Runtime-API. Sie bietet explizite Kontrolle über die Hardwareauswahl (einschließlich eines bestimmten DXCore-Adapters oder D3D12-Geräts), Tensor-Residency, Mehrstufige Pipelineplatzierung und Kompilierung.

Wenn Ihre App auf anderen Plattformen ausgeführt werden muss oder bereits funktionierenden plattformübergreifenden ONNX-Runtime-Sitzungscode hat, verwenden Sie stattdessen die in Windows ML enthaltenen ONNX-Runtime-APIs.

Kernobjektmodell

Konzept Primäre API Description
Runtime IWinMLRuntime Von WinMLCreateRuntime zurückgegebene Schnittstelle; lädt Modelldateien, erstellt Ausführungsziele und erstellt Pipeline-Generatoren.
Modell IWinMLModel Unveränderliches, opakes Modellartefakt, das aus einer Datei oder einem Puffer geladen wird. Spiegeln Sie das deklarierte Schema durch IWinMLModelSchema wider.
Ausführungsziel IWinMLExecutionTarget CPU-, GPU- oder NPU-Platzierungstoken zum Erstellen von Phasen und Erstellen von Tensoren.
Pipeline-Builder IWinMLPipelineBuilder Fügt Modell- und Prozessorphasen hinzu, verbindet sie und erstellt eine vorbereitete Pipeline.
Rohrleitung IWinMLPipeline Vorbereiteter, sofort lauffähiger Graph, der mit gebundenen Tensoren ausgeführt wird und Ausgabe-Tensoren erzeugt.
Stage IWinMLStage Ein Schritt in der Pipeline, der positionsbezogene Eingabe- und Ausgabebindungen sowie ein aufgelöstes Ausführungsziel umfasst.
Tensor IWinMLTensor Typisierte mehrdimensionale Daten, die an Phaseneingaben und -ausgaben gebunden sind.
Textgenerierung /Spracherkennung Windows ML-Textgenerierungs- und Spracherkennungs-APIs Höherer Workflow, der auf aufrufereigenen Runtime-Objekten mit typisierten Sitzungen, Datenströmen und Ergebnissen aufbaut.

Wählen Sie ein Back-End und ein Ausführungsziel aus

LoadModelFromFile wählt das Back-End aus der Dateierweiterung des Modellartefaktes aus. Ihre App verwendet dieselben Laufzeitobjekte – Modell, Ausführungsziel, Pipeline-Generator, Phasen, Bindungen und Run – unabhängig davon, welches Back-End die Datei lädt.

Modelldatei Backend Hardwarebeschleunigung
.onnx, .ort ONNX Runtime Execution Provider (EPs), die Windows installiert und über den Windows ML EP-Katalog auf dem neuesten Stand hält
.gguf llama.cpp Ein app-lokales CPU-Modul sowie ein optionales CUDA-Modul für NVIDIA GPUs, das Sie zusammen mit Ihrer App bereitstellen. CPU und CUDA sind die einzigen llama.cpp-Backends, die Windows ML für diese Version überprüft.

Ein Ausführungsziel stellt eine Hardwareklasse – CPU, GPU oder NPU – dar, die mit IWinMLRuntime erstellt wird. Wiederverwenden eines Ziels für Build-Stufen und Erstellen von Tensoren: Durch die Wiederverwendung eines Ziels wird die gleiche Zielaffinität ausgedrückt, während die Verwendung unterschiedlicher Ziele die Grenzen für die Übertragung zwischen verschiedenen Zielen explizit macht. Wenn die Methode des Pipeline-Generators Build ausgeführt wird, platziert die Laufzeit jede Phase im Ausführungs-Back-End für das Ziel und stellt die Ziel- und Back-End-Kompatibilität sicher.

Rufen Sie CreateExecutionTarget für eine Hardwareklasse auf, ohne Geräte selbst aufzuzählen, mit einer WINML_EXECUTION_TARGET_KIND und einer WINML_EXECUTION_TARGET_PREFERENCE , die Kandidaten dieser Klasse bewertet, z. B. eine integrierte oder eine diskrete GPU. Behandeln Sie ERROR_NOT_FOUND und ERROR_NOT_SUPPORTED gleich und kehren Sie zu einer anderen Klasse zurück:

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 entspricht dem Anfordern der CPU-Art. CreateExecutionTargetFromAdapter und CreateExecutionTargetFromD3D12 binden ein Ziel an einen bestimmten DXCore-Adapter oder ein D3D12-Gerät, anstatt die Auswahl der Runtime zuzulassen. Bei ONNX-Modellen, die von einem installierten Execution Provider (EP) abhängen, können Sie über eine optionale ONNX-Runtime-Kompatibilitätsoberfläche einen Anbieter anheften, den Sie bereits registriert haben. Jedes Back-End geht mit diesen Zielen unterschiedlich um, z. B. erfordert das von .gguf-Modellen verwendete llama.cpp-Back-End mindestens teilweise GPU-Offload, um ein GPU-Ziel zu berücksichtigen, und unterstützt keine NPU-Ziele oder Anbieter-Pinning. Eine vollständige Zielauflösungsmatrix pro Back-End und eine exemplarische Vorgehensweise zum Ausführen eines GGUF-Modells finden Sie unter Windows ML-Runtime-API-Konzepte.

Nächste Schritte

  • Zuletzt aktualisiert um