Windows ML-APIs

Konzeptionelle Anleitungen finden Sie unter Ausführen von ONNX-Modellen mit Windows ML.For conceptual guidance, see Run ONNX models with Windows ML).

Sie können sich die APIs im Microsoft.Windows.AI.MachineLearning NuGet-Paket vorstellen als die Obermenge dieser drei Sätze:

• Neue APIs. Net-neue Windows ML-APIs, z. B. die Infrastructure-Klasse und ihre Methoden (die Windows-Runtime-APIs sind); und z. B. die WinMLInitialize-Funktion (eine flache Win32-API im C-Stil und eine der Windows ML-Bootstrap-APIs). Diese APIs sind im Thema dokumentiert, das Sie jetzt lesen.
• APIs aus der älteren Version von Windows ML. Windows ML-APIs, die aus dem Windows.AI.MachineLearning-Namespace kopiert wurden. Nun können Sie also mehr über diese APIs erfahren – mit dem Verständnis, dass sie jetzt auch in Microsoft.Windows.AI.MachineLearning vorhanden sind – in der Dokumentation für Windows.AI.MachineLearning. Siehe Windows ML-APIs in Windows.AI.MachineLearning.
• ONNX-Runtime-APIs. Windows ML-Implementierungen (im Microsoft.Windows.AI.MachineLearning NuGet-Paket) bestimmter APIs aus der ONNX-Runtime (ORT). Dokumentation finden Sie in den ONNX-Runtime-API-Dokumenten. Beispiel: die OrtCompileApi-Struktur. Codebeispiele, die diese APIs verwenden, und weitere Links zur Dokumentation finden Sie im Lernprogramm "Verwenden von Windows ML zum Ausführen des ResNet-50-Modelllernprogramms ".

Das NuGet-Paket "Microsoft.Windows.AI.MachineLearning"

Die Microsoft Windows ML-Runtime stellt APIs für maschinelles Lernen und KI-Vorgänge in Windows-Anwendungen bereit. Das Microsoft.Windows.AI.MachineLearning NuGet-Paket stellt die Windows ML-Runtime-Dateien .winmd für die Verwendung in C#- und C++-Projekten bereit.

Net-neue Windows-Runtime-APIs

Infrastrukturklasse

Die Infrastructure-Klasse bietet Methoden zum Herunterladen, Konfigurieren und Registrieren von KI-Ausführungsanbietern (EPs) für die Verwendung mit der ONNX-Runtime. Die Infrastruktur behandelt die Komplexität der Paketverwaltung und der Hardwareauswahl.

Diese Klasse ist der Einstiegspunkt für Ihre App, um über die Windows ML-Runtime auf hardwareoptimierte Maschinelle Lernbeschleunigung zuzugreifen.

C#

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

// Download the latest execution provider packages
await infrastructure.DownloadPackagesAsync();

// Register available execution providers with ONNX Runtime
await infrastructure.RegisterExecutionProviderLibrariesAsync();

// Use ONNX Runtime directly for inference (using Microsoft.ML.OnnxRuntime namespace)

C++/WinRT

winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

// Download packages
infrastructure.DownloadPackagesAsync().get();

// Register execution providers with ONNX Runtime
infrastructure.RegisterExecutionProviderLibrariesAsync().get();

// Use ONNX Runtime C API directly for inference

Methoden der Infrastrukturklasse

Infrastructure.DownloadPackagesAsync-Methode

Lädt Paketabhängigkeiten für die aktuelle Hardwarekonfiguration herunter. Dadurch wird sichergestellt, dass die entsprechenden Ausführungsanbieter für die Hardware des Geräts installiert sind und up-to-datum.

C#

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

try {
    // This will download the appropriate packages for the current hardware
    await infrastructure.DownloadPackagesAsync();
    Console.WriteLine("Execution provider packages downloaded successfully");
}
catch (Exception ex) {
    Console.WriteLine($"Failed to download execution provider packages: {ex.Message}");
}

C++/WinRT

try {
    winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;
    
    // Download the packages
    infrastructure.DownloadPackagesAsync().get();
    std::wcout << L"Execution provider packages downloaded successfully\n";
}
catch (const winrt::hresult_error& ex) {
    std::wcout << L"Error: " << ex.message().c_str() << L"\n";
}

Infrastructure.RegisterExecutionProviderLibrariesAsync-Methode

Registriert alle Ausführungsanbieterbibliotheken, die für die aktuelle Hardwarekonfiguration relevant sind, bei ONNX Runtime. Diese Methode sollte vor dem Erstellen von ONNX-Runtime-Sitzungen aufgerufen werden.

Von Bedeutung

Die Infrastrukturinstanz muss bei Verwendung der ONNX-Laufzeit nach dem Aufruf von RegisterExecutionProviderLibrariesAsync gültig bleiben.

C#

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

// Register execution providers with ONNX Runtime
await infrastructure.RegisterExecutionProviderLibrariesAsync();

// Use ONNX Runtime directly for inference (using Microsoft.ML.OnnxRuntime namespace)

C++/WinRT

winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

// Register execution providers with ONNX Runtime
infrastructure.RegisterExecutionProviderLibrariesAsync().get();

// Use ONNX Runtime C API directly for inference

Infrastructure.GetExecutionProviderLibraryPathsAsync-Methode

Ruft eine Zuordnung von Namen der Ausführungsanbieter zu ihren vollständigen Dateipfaden ab. Auf diese Weise können Anwendungen Informationen zu den verfügbaren Ausführungsanbietern und deren Speicherorten abrufen.

C#

// C# example
var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

try {
    // Get the map of execution provider names to paths
    var providerPaths = await infrastructure.GetExecutionProviderLibraryPathsAsync();

    foreach (var provider in providerPaths) {
        Console.WriteLine($"Provider: {provider.Key}, Path: {provider.Value}");
    }
}
catch (Exception ex) {
    Console.WriteLine($"Failed to get execution provider paths: {ex.Message}");
}

C++/WinRT

try {
    winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

    // Get the execution provider paths
    auto providerPaths = infrastructure.GetExecutionProviderLibraryPathsAsync().get();

    for (const auto& pair : providerPaths) {
        std::wcout << L"Provider: " << pair.Key().c_str() << L", Path: " << pair.Value().c_str() << L"\n";
    }
}
catch (const winrt::hresult_error& ex) {
    std::wcout << L"Error: " << ex.message().c_str() << L"\n";
}

Andere Infrastrukturmitglieder

Name	BESCHREIBUNG
Infrastruktur()	Standardkonstruktor, der eine Instanz der Infrastructure-Klasse initialisiert

APIDetails

namespace Microsoft.Windows.AI.MachineLearning
{
    [contract(Windows.Foundation.UniversalApiContract, 1)]
    [threading(both)]
    [marshaling_behavior(agile)]
    runtimeclass Infrastructure
    {
        // Constructor
        Infrastructure();

        // Downloads package dependencies for the current hardware.
        Windows.Foundation.IAsyncAction DownloadPackagesAsync();

        // Registers all execution provider libraries with ONNX Runtime.
        Windows.Foundation.IAsyncAction RegisterExecutionProviderLibrariesAsync();
    }
}

Implementierungshinweise

Die Infrastructure-Klasse verarbeitet die Paketverwaltung intern mithilfe der Microsoft Store InstallControl-APIs , die aus dem Hauptpaket für Windows ML-Runtime aufgerufen werden müssen, da sie von Microsoft signiert ist. Dazu gehören:

• Auflösen verfügbarer Ausführungsanbieter (EPs) für die aktuelle Hardwarekonfiguration.
• Verwalten der Paketlebensdauer und -updates.
• Verwaltung der Paketregistrierung und -aktivierung.
• Unterstützung verschiedener Versionen von Ausführungsanbietern

Paketentdeckung

Ausführungsanbieter (EPs) werden als separate MSIX-Komponenten verpackt, die die com.microsoft.windowsmlruntime.executionprovider Erweiterung in ihren Paketmanifesten deklarieren. Mit diesem Design können Ausführungsanbieter unabhängig von den Komponenten der Windows ML-Runtime aktualisiert werden.

Die Windows ML-Runtime ermittelt diese Pakete über die Paketerweiterungsinfrastruktur, die in Windows 11 eingeführt wurde. Für jedes ermittelte EP wertet die Laufzeit die Hardwarekompatibilität aus und lädt die entsprechende Implementierung für das aktuelle System.

Verwenden der ONNX-Runtime mit Windows ML-Runtime

Verwenden Sie für C++-Anwendungen nach dem Aufrufen RegisterExecutionProviderLibrariesAsyncdie ONNX-Runtime-C-API direkt, um Sitzungen zu erstellen und Rückschlüsse auszuführen.

Verwenden Sie für C#-Anwendungen die ONNX-Runtime direkt für die Inferenz mithilfe des Microsoft.ML.OnnxRuntime-Namespaces.

Netto-neue flache C-stil Win32-APIs (Windows ML Bootstrap-APIs)

Die folgenden Anforderungen gelten für alle unten dokumentierten Windows ML-Bootstrapfunktionen.

Anforderung	Wert
NuGet-Paket	Microsoft.Windows.AI.MachineLearning
Überschrift	WinMLBootstrap.h
Namespace	Nichts

WinMLStatusCallback-Rückruffunktion

typedef void (*WinMLStatusCallback)(void* context, HRESULT result);

WinMLInitialize-Funktion

/**
 * Initializes the WinML runtime, and adds dependencies to the current process.
 * You must call this function before you call any other WinML APIs.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 */
HRESULT WinMLInitialize(void);

WinMLUninitialize-Funktion

/**
 * Uninitializes the WinML runtime, and removes any dependencies in the current process.
 * You must call this function before before the process exits.
 *
 * @return No return value.
 */
void WinMLUninitialize(void);

WinMLGetInitializationStatus-Funktion

/**
 * Returns the initialization status of the WinML runtime.
 * S_OK indicates that the runtime is initialized and ready to use.
 *
 * @return HRESULT S_OK if the runtime is initialized; an error code otherwise.
 */
HRESULT WinMLGetInitializationStatus(void);

WinMLDownloadExecutionProviders-Funktion

/**
 * Downloads the execution providers applicable to the current device.
 * This function is asynchronous, and will return immediately.
 * A status result will be returned to the callback when the download is complete or has failed.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 */
HRESULT WinMLDownloadExecutionProviders(
    WinMLStatusCallback onCompletedCallback,
    void* context);

WinMLRegisterExecutionProviders-Funktion

/**
 * Registers the execution providers applicable to the current device.
 * This function is asynchronous, and will return immediately.
 * A status result will be returned to the callback when the registration is complete or has failed.
 *
 * @return HRESULT S_OK on success, an error code otherwise.
 */
HRESULT WinMLRegisterExecutionProviders(
    WinMLStatusCallback onCompletedCallback,
    void* context);

WinMLDeployMainPackage-Funktion

/**
 * Deploys the Microsoft.Windows.AI.MachineLearning MSIX package from the
 * msix/win-{arch} directory relative to the application executable.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 * S_OK is also returned if the package is already installed.
 */
HRESULT WinMLDeployMainPackage();

Siehe auch

• Ausführen von ONNX-Modellen mit Windows ML (Microsoft.Windows.AI.MachineLearning)