Vue d’ensemble de l’API Windows ML Runtime

Important

L’API Windows ML Runtime est actuellement expérimentale et n’est pas prise en charge pour une utilisation dans les environnements de production. Les applications qui testent cette API ne doivent pas être publiées sur le Microsoft Store.

Important

L’API Windows ML Runtime est actuellement disponible en C++ et Python ; C# n’est actuellement pas pris en charge. Faites-nous savoir si vous souhaitez utiliser ces API à partir de C# en créant une issue dans le dépôt GitHub Windows ML !

L’API Windows ML Runtime est une infrastructure d’inférence d’ia locale C/C++ native conçue spécifiquement pour Windows. Avec l’API Windows ML Runtime, vous pouvez charger un modèle, choisir une cible d’exécution processeur, GPU ou NPU (y compris un adaptateur DXCore spécifique ou un appareil D3D12), lier des tenseurs à cette cible, composer des étapes de modèle et de processeur dans un pipeline, compiler le pipeline et l’exécuter pour produire des tenseurs de sortie.

Les API de génération de texte et de reconnaissance vocale facultatives composent ces mêmes objets Runtime dans des flux de travail de niveau supérieur sur un modèle que votre application fournit : consultez Générer du texte avec votre propre modèle de langage à l’aide de Windows ML et reconnaître la parole avec votre propre modèle Whisper à l’aide de Windows ML.

Runtime API vs ONNX Runtime

Si votre application cible uniquement Windows (et que vous êtes prêt à utiliser des API actuellement expérimentales), utilisez l'API Runtime. Il donne un contrôle explicite sur la sélection matérielle (y compris un adaptateur DXCore spécifique ou un périphérique D3D12), la résidence du tenseur, le placement de pipeline à plusieurs étapes et la compilation.

Dans le cas contraire, si votre application doit s’exécuter sur d’autres plateformes ou qu’elle utilise déjà du code de session ONNX Runtime multiplateforme, utilisez les API ONNX Runtime incluses dans Windows ML à la place.

Modèle d'objet central

Concept API principale Description
Runtime IWinMLRuntime Interface retournée par WinMLCreateRuntime; charge les fichiers de modèle, crée des cibles d’exécution et crée des générateurs de pipelines.
Model IWinMLModel Artefact de modèle opaque immuable chargé à partir d’un fichier ou d’une mémoire tampon. Reflète son schéma déclaré via IWinMLModelSchema.
Cible d’exécution IWinMLExecutionTarget Jeton de placement CPU, GPU ou NPU utilisé pour générer des phases et créer des tenseurs.
Créateur de pipelines IWinMLPipelineBuilder Ajoute des phases de modèle et de processeur, les connecte et génère un pipeline préparé.
Pipeline IWinMLPipeline Graphe préparé, exécutable immédiatement, qui exécute des tenseurs liés et produit des tenseurs de sortie.
Stage IWinMLStage Une étape du pipeline qui possède des liaisons d’entrée et de sortie positionnelles et sa cible d’exécution résolue.
Tenseur IWinMLTensor Données multidimensionnelles typées liées aux entrées et sorties d’étape.
Génération de texte / reconnaissance vocale API de génération de texte et de reconnaissance vocale ML Windows Flux de travail de niveau supérieur composé d’objets Runtime appartenant à l’appelant, avec des sessions typées, des flux et des résultats.

Choisir un backend et une cible d’exécution

LoadModelFromFile sélectionne le back-end à partir de l’extension de fichier de l’artefact de modèle. Votre application utilise les mêmes objets Runtime (modèle, cible d’exécution, générateur de pipelines, étapes, liaisons et Run) — quel que soit le backend qui charge le fichier.

Fichier modèle Backend Accélération matérielle
.onnx, .ort ONNX Runtime Fournisseurs d’exécution (EPs) que Windows installe et maintient à jour via le catalogue EP Windows ML
.gguf llama.cpp Module CPU local à l’application, ainsi qu’un module CUDA facultatif pour les GPU NVIDIA que vous déployez en même temps que votre application. CPU et CUDA sont les seuls back-ends llama.cpp que Windows ML valide pour cette version.

Une cible d’exécution représente une classe matérielle ( PROCESSEUR, GPU ou NPU) créée avec IWinMLRuntime. Réutilisez une cible pour créer des phases et créer des tenseurs : la réutilisation d’une cible exprime une affinité de même cible, tandis que l’utilisation de cibles distinctes rend les limites de transfert inter-cibles explicites. Lorsque la méthode Build du générateur de pipeline s’exécute, l’environnement d’exécution place chaque phase sur le backend d’exécution pour sa cible et valide la compatibilité de la cible et du backend.

Pour une classe de matériel sans énumérer vous-même les appareils, appelez CreateExecutionTarget avec un WINML_EXECUTION_TARGET_KIND et un WINML_EXECUTION_TARGET_PREFERENCE qui classe les candidats de cette classe, tels qu’un GPU intégré et un GPU discret. Traitez ERROR_NOT_FOUND et ERROR_NOT_SUPPORTED de la même manière et revenez à une autre classe :

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 équivaut à demander le type d’UC. CreateExecutionTargetFromAdapter et CreateExecutionTargetFromD3D12 lient une cible à un adaptateur DXCore spécifique ou à un périphérique D3D12 au lieu de laisser le runtime en choisir un. Pour les modèles ONNX qui dépendent d’un fournisseur d'exécution (EP) installé, une surface de compatibilité ONNX Runtime facultative vous permet d’épingler un fournisseur que vous avez déjà enregistré. Chaque back-end résout ces cibles différemment ; par exemple, le back-end llama.cpp utilisé par les modèles .gguf nécessite au moins un déchargement partiel vers le GPU pour honorer une cible GPU et ne prend pas en charge les cibles NPU ni l’épinglage du fournisseur. Pour obtenir la matrice de résolution cible complète par back-end, et pour un guide pas à pas sur l’exécution d’un modèle GGUF, consultez Concepts de l’API Windows ML Runtime.

Étapes suivantes

  • Dernière mise à jour :