Overzicht van Windows ML Runtime-API

Important

De Windows ML Runtime-API is momenteel experimenteel en wordt niet ondersteund voor gebruik in productieomgevingen. Apps die deze API uitproberen, mogen niet worden gepubliceerd naar de Microsoft Store.

Important

De Windows ML Runtime-API is momenteel beschikbaar in C++ en Python; C# wordt momenteel niet ondersteund. Laat het ons weten als u geïnteresseerd bent om deze API's vanuit C# te gebruiken door een issue in te dienen in de Windows ML GitHub repo!

De Windows ML Runtime-API is een systeemeigen lokale AI-inferentieframework voor C/C++ dat speciaal is gebouwd voor Windows. Met de Windows ML Runtime-API kunt u een model laden, een CPU-, GPU- of NPU-uitvoeringsdoel kiezen (inclusief een specifieke DXCore-adapter of D3D12-apparaat), tensors binden aan dat doel, model- en processorfasen opstellen in een pijplijn, de pijplijn compileren en uitvoeren om uitvoertensors te produceren.

De optionele API's voor het genereren van tekst en spraakherkenning vormen dezelfde Runtime-objecten in werkstromen op een hoger niveau voor een model dat uw app levert: zie Tekst genereren met uw eigen taalmodel met behulp van Windows ML en Spraak herkennen met uw eigen Whisper-model met behulp van Windows ML.

Runtime API vs ONNX Runtime

Als uw app alleen is gericht op Windows (en u bereid bent API's te gebruiken die momenteel experimenteel zijn), gebruik dan de Runtime-API. Het biedt expliciete controle over hardwareselectie (inclusief een specifieke DXCore-adapter of D3D12-apparaat), tensorresidentie, plaatsing van pijplijnen met meerdere fasen en compilatie.

Anders, als uw app op andere platforms moet worden uitgevoerd of al werkt met platformoverschrijdende ONNX Runtime-sessiecode, gebruikt u in plaats daarvan de ONNX Runtime-API's die zijn opgenomen in Windows ML.

Objectkernmodel

Concept hoofd-API Description
Runtime IWinMLRuntime Interface die wordt geretourneerd door WinMLCreateRuntime; laadt modelbestanden, maakt uitvoeringsdoelen en maakt pipeline builders.
Model IWinMLModel Onveranderbaar, ondoorzichtig modelartefact dat is geladen vanuit een bestand of buffer. Geef het gedeclareerde schema weer via IWinMLModelSchema.
Doel voor uitvoering IWinMLExecutionTarget Cpu-, GPU- of NPU-plaatsingstoken dat wordt gebruikt om fasen te bouwen en tensors te maken.
Pijplijnbouwer IWinMLPipelineBuilder Voegt model- en processorfasen toe, verbindt ze en bouwt een voorbereide pijplijn.
Pipeline IWinMLPipeline Voorbereide, direct uitvoerbare graaf die gebonden tensors uitvoert en outputtensors produceert.
Stage IWinMLStage Een stap in de pijplijn die eigenaar is van positionele invoer- en uitvoerbindingen en het opgeloste uitvoeringsdoel.
Tensor IWinMLTensor Getypeerde multidimensionale gegevens die zijn gebonden aan fase-invoer en -uitvoer.
Tekstgeneratie/spraakherkenning Windows ML Text Generation and Speech Recognition API's Werkstroom op een hoger niveau samengesteld over runtime-objecten die eigendom zijn van de aanroeper, met getypte sessies, streams en resultaten.

Kies een backend en uitvoeringsdoel

LoadModelFromFile selecteert de back-end op basis van de bestandsextensie van het modelartefact. Uw app maakt gebruik van dezelfde Runtime-objecten: model, uitvoeringsdoel, pijplijnbouwer, fasen, bindingen en Run , ongeacht welke back-end het bestand laadt.

Modelbestand Backend Hardwareversnelling
.onnx, .ort ONNX Runtime Uitvoeringsproviders (EPs) die door Windows worden geïnstalleerd en up-to-date worden gehouden via de Windows ML EP-catalogus
.gguf llama.cpp Een app-lokale CPU-module, plus een optionele CUDA-module voor NVIDIA GPU's die u naast uw app uitrolt. CPU en CUDA zijn de enige llama.cpp-back-ends die Windows ML voor deze release valideert.

Een uitvoeringsdoel vertegenwoordigt een hardwareklasse , CPU, GPU of NPU , gemaakt met IWinMLRuntime. Hergebruik een target om buildfasen te bouwen en tensors te maken: als u één target opnieuw gebruikt, drukt dat affiniteit met hetzelfde target uit, terwijl het gebruik van afzonderlijke targets overdrachtsgrenzen tussen targets expliciet maakt. Wanneer de methode Build van de pijplijnbouwer wordt uitgevoerd, plaatst de runtime elke fase op de uitvoeringsback-end voor het doel en legt de compatibiliteit van het doel en de back-end vast.

Voor een hardwareklasse zonder dat u zelf apparaten opsomt, roept u CreateExecutionTarget aan met een WINML_EXECUTION_TARGET_KIND en een WINML_EXECUTION_TARGET_PREFERENCE die kandidaten van die klasse rangschikt, zoals een geïntegreerde versus een discrete GPU. Behandel ERROR_NOT_FOUND en ERROR_NOT_SUPPORTED hetzelfde en val terug op een andere klasse:

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 is gelijk aan het aanvragen van het CPU-type. CreateExecutionTargetFromAdapter en CreateExecutionTargetFromD3D12 koppel een doel aan een specifieke DXCore-adapter of D3D12-apparaat in plaats van de runtime er een te laten kiezen. Voor ONNX-modellen die afhankelijk zijn van een geïnstalleerde execution provider (EP), kunt u met een optionele compatibiliteitslaag voor ONNX Runtime een provider vastzetten die u al hebt geregistreerd. Elke back-end lost deze doelen anders op, bijvoorbeeld de llama.cpp back-end die door .gguf modellen wordt gebruikt, vereist ten minste gedeeltelijke GPU-offload om een GPU-doel te respecteren en biedt geen ondersteuning voor NPU-doelen of providerpinning. Zie voor de volledige matrix voor doelresolutie per back-end en voor een overzicht van het uitvoeren van een GGUF-model Windows ML Runtime API concepts.

Volgende stappen 

  • Laatst bijgewerkt om