Ejecución de modelos ONNX con Windows ML

Importante

Las API de Windows ML son actualmente experimentales y no se admiten para su uso en entornos de producción. Las aplicaciones que prueban estas API no deben publicarse en Microsoft Store.

Con los tipos de Windows Machine Learning (ML) en el espacio de nombres Microsoft.Windows.AI.MachineLearning , puede ejecutar modelos ONNX localmente en las aplicaciones de Windows sin tener que administrar manualmente los paquetes del proveedor de ejecución subyacente (EP). Las APIs gestionan la descarga, actualización e inicialización de EPs; que puede seguir utilizando con Microsoft.Windows.AI.MachineLearning y/o con ONNX Runtime.

Prerrequisitos

• Pc Windows 11 que ejecuta la versión 24H2 (compilación 26100) o posterior.

Además de lo anterior, hay requisitos previos específicos del idioma en función del idioma en el que se escribe la aplicación.

C#

• .NET 8 o superior
• Objetivo TFM windows10.0.26100 o más

C++

C++20 o posterior.

Pitón

Versiones de Python 3.10 a 3.13, en dispositivos x64 y ARM64.

Paso 1: Instalar el paquete en tiempo de ejecución de WinML y el paquete NuGet

El paquete en tiempo de ejecución se distribuye a través de Microsoft Store. Ejecute el siguiente comando en Terminal Windows para instalarlo (el identificador es el identificador de catálogo de la Tienda para el paquete en tiempo de ejecución):

winget install --id 9MVL55DVGWWW

A continuación, siga los pasos que se indican a continuación en función del lenguaje de programación de la aplicación.

C#

En el proyecto de .NET, agregue el paquete NuGet Microsoft.Windows.AI.MachineLearning (asegúrese de incluir paquetes de versión preliminar si usa el Administrador de paquetes NuGet).

dotnet add package Microsoft.Windows.AI.MachineLearning --prerelease

A continuación, importe los espacios de nombres en su código.

using Microsoft.ML.OnnxRuntime;
using Microsoft.Windows.AI.MachineLearning;

C++

En el proyecto de Visual Studio, use el Administrador de paquetes NuGet para buscar y agregar el paquete NuGet Microsoft.Windows.AI.MachineLearning al proyecto (asegúrese de incluir pacakges de versión preliminar en la búsqueda).

A continuación, agregue el archivo de encabezado OnnxRuntime al código.

#include <win_onnxruntime_cxx_api.h>

Pitón

Windows ML proporciona un enlace de Python denominado onnxruntime-winml, que tiene compatibilidad con Python para la adquisición y configuración de EP. Una vez configurada, las aplicaciones de Python pueden usar características en tiempo de ejecución de ONNX, como la selección automática de EP como de costumbre.

pip install --index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT-Nightly/pypi/simple --extra-index-url https://pypi.org/simple onnxruntime-winml

A continuación, importe el módulo OnnxRuntime en el código.

import onnxruntime as ort

Paso 2: Descargar y registrar los paquetes extendidos más recientes

A continuación, usaremos Windows ML para asegurarnos de que los proveedores de ejecución (EPs) más recientes están disponibles en el dispositivo y registrados con el entorno de ejecución de ONNX.

C#

// First we create a new instance of EnvironmentCreationOptions
EnvironmentCreationOptions envOptions = new()
{
    logId = "WinMLDemo", // Use an ID of your own choice
    logLevel = OrtLoggingLevel.ORT_LOGGING_LEVEL_ERROR
};

// And then use that to create the ORT environment
using var ortEnv = OrtEnv.CreateInstanceWithOptions(ref envOptions);

// Then, initialize Windows ML infrastructure
Infrastructure infrastructure = new();

// Ensure the latest execution providers are available (downloads them if they aren't)
await infrastructure.DownloadPackagesAsync();

// And register the EPs with ONNX Runtime
await infrastructure.RegisterExecutionProviderLibrariesAsync();

C++

// First we need to create an ORT environment
Ort::Env env(ORT_LOGGING_LEVEL_ERROR, "WinMLDemo"); // Use an ID of your own choice

// Then, initialize Windows ML infrastructure
winrt::Microsoft.Windows.AI.MachineLearning::Infrastructure infrastructure{};

// Ensure the latest execution providers are available (downloads them if they aren't)
co_await infrastructure.DownloadPackagesAsync();

// And register the EPs with ONNX Runtime
co_await infrastructure.RegisterExecutionProviderLibrariesAsync();

Pitón

Para Python, los EPs se descargan y registran automáticamente como parte del primer import. No es necesario hacer nada adicional.

Paso 3: Configurar los proveedores de ejecución

El entorno de ejecución de ONNX permite a las aplicaciones configurar proveedores de ejecución (EPs) en función de las directivas de dispositivo, o explícitamente, lo que permite un mayor control sobre las opciones del proveedor y qué dispositivos se deben usar.

Se recomienda comenzar con la selección explícita de EPs para que puedas tener más predictibilidad en los resultados. Una vez que haya funcionado, puede experimentar con el uso de directivas de dispositivo para seleccionar proveedores de ejecución de forma natural y orientada a resultados.

Para seleccionar explícitamente uno o varios EPs, usará la GetEpDevices función en OrtApi, que permite enumerar a través de todos los dispositivos disponibles. SessionOptionsAppendExecutionProvider_V2 Después, se puede usar para anexar explícitamente dispositivos específicos y proporcionar opciones de proveedor personalizadas al EP deseado.

C#

using Microsoft.ML.OnnxRuntime;

// Get all available EP devices from the environment
var epDevices = ortEnv.GetEpDevices();

// Accumulate devices by EpName
// Passing all devices for a given EP in a single call allows the execution provider
// to select the best configuration or combination of devices, rather than being limited
// to a single device. This enables optimal use of available hardware if supported by the EP.
var epDeviceMap = epDevices
    .GroupBy(device => device.EpName)
    .ToDictionary(g => g.Key, g => g.ToList());

// For demonstration, list all found EPs, vendors, and device types
foreach (var epGroup in epDeviceMap)
{
    var epName = epGroup.Key;
    var devices = epGroup.Value;

    Console.WriteLine($"Execution Provider: {epName}");
    foreach (var device in devices)
    {
        string deviceType = GetDeviceTypeString(device.HardwareDevice.Type);
        Console.WriteLine($" | Vendor: {device.EpVendor,-16} | Device Type: {deviceType,-8}");
    }
}

// Configure and append each EP type only once, with all its devices
var sessionOptions = new SessionOptions();
foreach ((var epName, var devices) in epDeviceMap)
{
    Dictionary<string, string> epOptions = new();
    switch (epName)
    {
        case "VitisAIExecutionProvider":
            // Demonstrating passing no options for VitisAI
            sessionOptions.AppendExecutionProvider(ortEnv, devices, epOptions);
            Console.WriteLine($"Successfully added {epName} EP");
            break;

        case "OpenVINOExecutionProvider":
            // Configure threading for OpenVINO EP, pick the first device found
            epOptions["num_of_threads"] = "4";
            sessionOptions.AppendExecutionProvider(ortEnv, [devices.First()], epOptions);
            Console.WriteLine($"Successfully added {epName} EP (first device only)");
            break;

        case "QNNExecutionProvider":
            // Configure performance mode for QNN EP
            epOptions["htp_performance_mode"] = "high_performance";
            sessionOptions.AppendExecutionProvider(ortEnv, devices, epOptions);
            Console.WriteLine($"Successfully added {epName} EP");
            break;

        default:
            Console.WriteLine($"Skipping EP: {epName}");
            break;
    }
}

C++

#include <win_onnxruntime_cxx_api.h>

// Get all available EP devices from the environment
std::vector<Ort::ConstEpDevice> ep_devices = env.GetEpDevices();

// Accumulate devices by ep_name
// Passing all devices for a given EP in a single call allows the execution provider
// to select the best configuration or combination of devices, rather than being limited
// to a single device. This enables optimal use of available hardware if supported by the EP.
std::unordered_map<std::string, std::vector<Ort::ConstEpDevice>> ep_device_map;
for (const auto& device : ep_devices)
{
    ep_device_map[device.EpName()].push_back(device);
}

// For demonstration, list all found EPs, vendors, and device types
for (const auto& [ep_name, devices] : ep_device_map)
{
    std::cout << "Execution Provider: " << ep_name << std::endl;
    for (const auto& device : devices)
    {
        std::cout << " | Vendor: " << std::setw(16) << device.EpVendor() << " | Device Type: " << std::setw(8)
                    << ToString(device.Device().Type()) << std::endl;
    }
}

// Configure and append each EP type only once, with all its devices
Ort::SessionOptions session_options;
for (const auto& [ep_name, devices] : ep_device_map)
{
    Ort::KeyValuePairs ep_options;
    if (ep_name == "VitisAIExecutionProvider")
    {
        // Demonstrating passing no options for VitisAI
        session_options.AppendExecutionProvider_V2(env, devices, ep_options);
    }
    else if (ep_name == "OpenVINOExecutionProvider")
    {
        // Configure threading for OpenVINO EP, pick the first device found.
        ep_options.Add("num_of_threads", "4");
        session_options.AppendExecutionProvider_V2(env, {devices.front()}, ep_options);
    }
    else if (ep_name == "QNNExecutionProvider")
    {
        // Configure performance mode for QNN EP
        ep_options.Add("htp_performance_mode", "high_performance");
        session_options.AppendExecutionProvider_V2(env, devices, ep_options);
    }
    else
    {
        std::cout << "Skipping EP: " << ep_name << std::endl;
    }
}

Pitón

# This example shows how to register a specific EP.
# Note that EPs registered by Windows ML cannot be accessed via the old "providers" option

import onnxruntime as ort

# Select a specific EP.
def add_ep_for_device(session_options, ep_name, device_type, ep_options=None):
    ep_devices = ort.get_ep_devices()
    for ep_device in ep_devices:
        if ep_device.ep_name == ep_name and ep_device.device.type == device_type:
            session_options.add_provider_for_devices([ep_device], {} if ep_options is None else ep_options)

options = ort.SessionOptions()
add_ep_for_device(options, "QNNExecutionProvider", ort.OrtHardwareDeviceType.NPU)  # example for QNN NPU
assert options.has_providers()

session = ort.InferenceSession(
    "path_to_your_model.onnx",
    sess_options=options,
)

Para obtener más información, consulte la documentación de ONNX Runtime OrtApi. Para obtener información sobre la estrategia de control de versiones en torno a los proveedores de ejecución, consulte la documentación sobre el control de versiones de los proveedores de ejecución.

Paso 4: Compilar el modelo

Los modelos ONNX deben compilarse en una representación optimizada que se pueda ejecutar de forma eficaz en el hardware subyacente del dispositivo. El proveedor de excecution que configuró en el paso 3 ayuda a realizar esta transformación.

A partir de la versión 1.22, ONNX Runtime ha introducido nuevas API para encapsular mejor los pasos de compilación. Hay más detalles disponibles en la documentación de compilación de ONNX Runtime (consulte OrtCompileApi struct).

Nota:

La compilación puede tardar varios minutos en completarse. Para que cualquier interfaz de usuario siga respondiendo, considere la posibilidad de hacerlo como una operación en segundo plano en la aplicación.

C#

// Prepare compilation options using our session we configured in step 3
OrtModelCompilationOptions compileOptions = new(sessionOptions);
compileOptions.SetInputModelPath(modelPath);
compileOptions.SetOutputModelPath(compiledModelPath);

// Compile the model
compileOptions.CompileModel();

C++

const OrtCompileApi* compileApi = ortApi.GetCompileApi();

// Prepare compilation options
OrtModelCompilationOptions* compileOptions = nullptr;
OrtStatus* status = compileApi->CreateModelCompilationOptionsFromSessionOption(env, sessionOptions, &compileOptions);
status = compileApi->ModelCompilationOptions_SetInputModelPath(compileOptions, modelPath.c_str());
status = compileApi->ModelCompilationOptions_SetOutputModelPath(compileOptions, compiledModelPath.c_str());

// Compile the model
status = compileApi->CompileModel(env, compileOptions);

// Clean up
compileApi->ReleaseModelCompilationOptions(compileOptions);

Pitón

input_model_path = "path_to_your_model.onnx"
output_model_path = "path_to_your_compiled_model.onnx"

model_compiler = ort.ModelCompiler(
    options,
    input_model_path,
    embed_compiled_data_into_model=True,
    external_initializers_file_path=None,
)
model_compiler.compile_to_file(output_model_path)
assert os.path.exists(output_model_path)

Paso 5: Ejecución de la inferencia del modelo

Ahora que el modelo se compila para el hardware local en el dispositivo, podemos crear una sesión de inferencia e inferencia del modelo.

C#

// Create inference session using compiled model
using InferenceSession session = new(compiledModelPath, sessionOptions);

C++

// Create inference session using compiled model
Ort::Session session(env, compiledModelPath.c_str(), sessionOptions);

Pitón

# Create inference session using compiled model
session = ort.InferenceSession(output_model_path, sess_options=options)

Paso 6: Distribuir la aplicación

Antes de distribuir la aplicación, los desarrolladores de C# y C++ deberán seguir pasos adicionales para asegurarse de que Windows ML Runtime está instalado en los dispositivos de los usuarios cuando la aplicación esté instalada. Consulta la página de distribución de la aplicación para obtener más información.

Compilación de modelos

Un modelo ONNX se representa como un gráfico, donde los nodos corresponden a operadores (como multiplicaciones de matriz, convoluciones y otros procesos matemáticos) y los bordes definen el flujo de datos entre ellos.

Esta estructura basada en grafos permite una ejecución y optimización eficientes al permitir transformaciones como la fusión de operadores (es decir, combinar varias operaciones relacionadas en una sola operación optimizada) y la eliminación de grafos (es decir, quitar nodos redundantes del grafo).

La compilación de modelos hace referencia al proceso de transformación de un modelo ONNX con la ayuda de un proveedor de ejecución (EP) en una representación optimizada que se puede ejecutar de forma eficaz en el hardware subyacente del dispositivo.

Diseño para compilación

Estas son algunas ideas para controlar la compilación en la aplicación.

• Rendimiento de la compilación. La compilación puede tardar varios minutos en completarse. Para que cualquier interfaz de usuario siga respondiendo, considere la posibilidad de hacerlo como una operación en segundo plano en la aplicación.
• Actualizaciones de la interfaz de usuario. Considere la posibilidad de informar a los usuarios de si la aplicación está realizando cualquier trabajo de compilación y notificarlas cuando se complete.
• Mecanismos de recuperación elegante. Si hay un problema al cargar un modelo compilado, intente capturar datos de diagnóstico para el fallo y haga que su aplicación vuelva a utilizar el modelo original si es posible, para que la funcionalidad de IA relacionada de la aplicación pueda seguir utilizándose.

Uso de directivas de dispositivo para la selección del proveedor de ejecución

Además de seleccionar explícitamente Proveedores de Ejecución (EPs), también puede usar políticas de dispositivo, que son una manera natural y orientada a resultados por la cual puede especificar cómo desea que se ejecute la carga de trabajo de inteligencia artificial. Para ello, utilizará la función SessionOptions.SetEpSelectionPolicy en OrtApi, pasará los valores OrtExecutionProviderDevicePolicy. Hay una variedad de valores que puede usar para la selección automática, como MAX_PERFORMANCE, PREFER_NPU, MAX_EFFICIENCYy mucho más. Consulte los documentos de ONNX OrtExecutionProviderDevicePolicy para ver otros valores que puede usar.

C#

// Configure the session to select an EP and device for MAX_EFFICIENCY which typically
// will choose an NPU if available with a CPU fallback.
var sessionOptions = new SessionOptions();
sessionOptions.SetEpSelectionPolicy(ExecutionProviderDevicePolicy.MAX_EFFICIENCY);

C++

// Configure the session to select an EP and device for MAX_EFFICIENCY which typically
// will choose an NPU if available with a CPU fallback.
Ort::SessionOptions sessionOptions;
sessionOptions.SetEpSelectionPolicy(OrtExecutionProviderDevicePolicy_MAX_EFFICIENCY);

Pitón

# Configure the session to select an EP and device for MAX_EFFICIENCY which typically
# will choose an NPU if available with a CPU fallback.
options = ort.SessionOptions()
options.set_provider_selection_policy(ort.OrtExecutionProviderDevicePolicy.MAX_EFFICIENCY)
assert options.has_providers()

Proporcionar comentarios sobre Windows ML

Nos encantaría escuchar sus comentarios sobre el uso de Windows ML. Si tiene algún problema, use la aplicación Centro de opiniones en Windows para notificar el problema.

Los comentarios deben enviarse en la categoría Plataforma para desarrolladores:> Windows Machine Learning .

Consulte también

• API de Windows ML en Microsoft.Windows.AI.MachineLearning