API de Windows ML

Para obtener instrucciones conceptuales, consulte Ejecución de modelos ONNX con Windows ML).

Puede pensar en las API del paquete NuGet Microsoft.Windows.AI.MachineLearning como superconjunto de estos tres conjuntos:

• Nuevas API. Nuevas API de Windows ML, como la clase Infrastructure y sus métodos (que son API de Windows Runtime); y, por ejemplo, la función WinMLInitialize (que es una API win32 de estilo C plana y es una de las API de arranque de Windows ML). Estas API se documentan en el tema que está leyendo ahora.
• API de la versión anterior de Windows ML. API de Windows ML que se copiaron del espacio de nombres Windows.AI.MachineLearning . Por lo tanto, por el momento puede obtener información sobre esas API, con la comprensión de que existen ahora también en Microsoft.Windows.AI.MachineLearning, en la documentación de Windows.AI.MachineLearning. Consulte API de Windows ML en Windows.AI.MachineLearning.
• APIs en tiempo de ejecución de ONNX. Implementaciones de Windows ML (en el paquete NuGet Microsoft.Windows.AI.MachineLearning) de ciertas API de ONNX Runtime (ORT). Para obtener documentación, consulte la documentación de la API en tiempo de ejecución de ONNX. Por ejemplo, la estructura OrtCompileApi. Para obtener ejemplos de código que usan estas API y más vínculos a la documentación, consulte el tutorial Uso de Windows ML para ejecutar el tutorial del modelo ResNet-50 .

El paquete NuGet Microsoft.Windows.AI.MachineLearning

Microsoft Windows ML Runtime proporciona API para las operaciones de aprendizaje automático e inteligencia artificial en aplicaciones de Windows. El paquete NuGet Microsoft.Windows.AI.MachineLearning proporciona los archivos en tiempo de ejecución .winmd de Windows ML para su uso en proyectos de C# y C++.

APIs completamente nuevas de Windows Runtime

Clase de infraestructura

La clase Infrastructure proporciona métodos para descargar, configurar y registrar proveedores de ejecución de IA (EPs) para su uso con el entorno de ejecución de ONNX. La infraestructura controla la complejidad de la administración de paquetes y la selección de hardware.

Esta clase es el punto de entrada para que la aplicación acceda a la aceleración de aprendizaje automático optimizada para hardware a través del entorno de ejecución de Windows ML.

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)

en 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

Métodos de clase de infraestructura

Método Infrastructure.DownloadPackagesAsync

Descarga las dependencias del paquete para la configuración de hardware actual. Esto garantiza que los proveedores de ejecución adecuados para el hardware del dispositivo estén instalados y up-to-actualizados.

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}");
}

en 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";
}

Método Infrastructure.RegisterExecutionProviderLibrariesAsync

Registra todas las bibliotecas del proveedor de ejecución relevantes para la configuración de hardware actual con ONNX Runtime. Se debe llamar a este método antes de crear sesiones en tiempo de ejecución de ONNX.

Importante

La instancia de infraestructura debe permanecer válida al usar el entorno de ejecución de ONNX después de la llamada a RegisterExecutionProviderLibrariesAsync.

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)

en 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

Método Infrastructure.GetExecutionProviderLibraryPathsAsync

Obtiene un mapa que asocia los nombres de proveedores de ejecución con sus rutas de acceso de archivo completas. Esto permite a las aplicaciones recuperar información sobre los proveedores de ejecución disponibles y sus ubicaciones.

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}");
}

en 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";
}

Miembros de infraestructura adicionales

Nombre	Descripción
Infraestructura()	Constructor predeterminado que inicializa una instancia de la clase Infrastructure

Detalles de la API

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();
    }
}

Notas de implementación

La clase Infrastructure controla la administración de paquetes internamente mediante las API InstallControl de Microsoft Store, a las que se debe llamar desde el paquete principal de Windows ML Runtime, porque está firmado por Microsoft. Esto incluye:

• Resolución de proveedores de ejecución disponibles (EPs) para la configuración de hardware actual.
• Administración del ciclo de vida y las actualizaciones del paquete.
• Control del registro y la activación de paquetes.
• Compatibilidad con diferentes versiones de proveedores de ejecución

Detección de paquetes

Los proveedores de ejecución (EP) se empaquetan como componentes MSIX independientes que declaran la com.microsoft.windowsmlruntime.executionprovider extensión en sus manifiestos de paquete. Este diseño permite que los proveedores de ejecución se actualicen independientemente de los componentes de Windows ML Runtime.

El entorno de ejecución de Windows ML detecta estos paquetes a través de la infraestructura de extensión de paquete que se introdujo en Windows 11. Para cada EP detectado, el tiempo de ejecución evalúa la compatibilidad de hardware y carga la implementación adecuada para el sistema actual.

Uso de ONNX Runtime con Windows ML Runtime

Para las aplicaciones de C++, después de llamar a RegisterExecutionProviderLibrariesAsync, use la API de C en tiempo de ejecución de ONNX directamente para crear sesiones y ejecutar la inferencia.

Para las aplicaciones de C#, el uso de ONNX Runtime directamente para realizar inferencia mediante el Microsoft.ML.OnnxRuntime espacio de nombres.

Nuevas API de Win32 escritas en C de estilo básico (APIs de inicio de Windows ML)

Los siguientes requisitos se aplican a todas las funciones de arranque de Windows ML documentadas a continuación.

Requisito	Importancia
Paquete NuGet	Microsoft.Windows.AI.MachineLearning
encabezado	WinMLBootstrap.h
Namespace	Ninguno

Función callback de WinMLStatusCallback

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

Función WinMLInitialize

/**
 * 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);

Función WinMLUninitialize

/**
 * 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);

Función WinMLGetInitializationStatus

/**
 * 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);

Función WinMLDownloadExecutionProviders

/**
 * 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);

Función WinMLRegisterExecutionProviders

/**
 * 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);

Función WinMLDeployMainPackage

/**
 * 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();

Consulte también

• Ejecución de modelos ONNX con Windows ML (Microsoft.Windows.AI.MachineLearning)