Instalación de proveedores de ejecución con Windows ML

Con Windows ML, algunos proveedores de ejecución (EPs) se descargan, instalan y comparten dinámicamente en todo el sistema a través de las API de Windows ML ExecutionProviderCatalog y se actualizan automáticamente. Para ver qué EP están disponibles, consulte Proveedores de ejecución admitidos.

En esta página se explica cómo instalar direcciones IP en el dispositivo de un usuario. Una vez instalado, deberá registrar proveedores de ejecución con ONNX Runtime antes de usarlos.

Instalación de todas las direcciones IP compatibles

Para el desarrollo inicial, es conveniente simplemente llamar a EnsureAndRegisterCertifiedAsync(), lo que descargará e instalará todos los EPs disponibles en el dispositivo del usuario y luego registrará todos los EPs con el ONNX Runtime en una sola llamada. Tenga en cuenta que, en la primera ejecución, este método puede tardar varios segundos o incluso minutos en función de la velocidad de red y los EPs que deban descargarse.

C#
C++
Python

// Get the default ExecutionProviderCatalog
var catalog = ExecutionProviderCatalog.GetDefault();

// Ensure execution providers compatible with device are present (downloads if necessary)
// and then registers all present execution providers with ONNX Runtime
await catalog.EnsureAndRegisterCertifiedAsync();

// Get the default ExecutionProviderCatalog
winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog catalog =
    winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();

// Ensure execution providers compatible with device are present (downloads if necessary)
// and then registers all present execution providers with ONNX Runtime
catalog.EnsureAndRegisterCertifiedAsync().get();

# Please DO NOT use this API. It won't register EPs to the python ort env.

Buscar todos los EP compatibles

Puede ver qué EPs (incluidos los EPs no instalados) están disponibles para el dispositivo del usuario llamando al método FindAllProviders().

C#
C++
Python

ExecutionProviderCatalog catalog = ExecutionProviderCatalog.GetDefault();

// Find all available EPs (including non-installed EPs)
ExecutionProvider[] providers = catalog.FindAllProviders();

foreach (var provider in providers)
{
    Console.WriteLine($"{provider.Name}: {provider.ReadyState}");
}

auto catalog = ExecutionProviderCatalog::GetDefault();

// Find all available EPs (including non-installed EPs)
auto providers = catalog.FindAllProviders();

for (auto const& provider : providers)
{
    std::wcout << provider.Name() << L": " << static_cast<int>(provider.ReadyState()) << std::endl;
}

# winml: winui3.microsoft.windows.ai.machinelearning
catalog = winml.ExecutionProviderCatalog.get_default()

# Find all available EPs (including non-installed EPs)
providers = catalog.find_all_providers()

for provider in providers:
    print(f"{provider.name}: {provider.ready_state}")

Los proveedores de ejecución devueltos variarán en función del dispositivo del usuario y de los proveedores de ejecución disponibles. En un dispositivo Qualcomm compatible sin ningún proveedor de ejecución instalado actualmente, el código anterior genera lo siguiente...

QNNExecutionProvider: NotPresent

Cada ExecutionProvider tiene una propiedad ReadyState que indica su estado actual en el dispositivo. Comprender estos estados le ayuda a determinar qué acciones debe realizar la aplicación.

ReadyState	Definición	Pasos siguientes
`NotPresent`	El EP no está instalado en el dispositivo cliente.	Ejecute `EnsureReadyAsync()` para descargar e instalar el EP y agréguelo al gráfico de dependencias en tiempo de ejecución de la aplicación.
`NotReady`	El EP se instala en el dispositivo cliente, pero no se ha agregado al gráfico de dependencias en tiempo de ejecución de la aplicación.	Llame `EnsureReadyAsync()` para agregar el EP al gráfico de dependencias en tiempo de ejecución de su aplicación.
`Ready`	El EP se instala en el dispositivo cliente y se ha agregado al gráfico de dependencias en tiempo de ejecución de la aplicación.	Llame `TryRegister()` para registrar el EP con ONNX Runtime.

Instalación de un EP específico

Si hay un executionProvider específico que la aplicación quiere usar y su ReadyState es NotPresent, puede descargarlo e instalarlo llamando a EnsureReadyAsync().

C#
C++
Python

// Download and install a NotPresent EP
var result = await provider.EnsureReadyAsync();

// Check that the download and install was successful
bool installed = result.Status == ExecutionProviderReadyResultState.Success;

// Download and install a NotPresent EP
auto result = provider.EnsureReadyAsync().get();

// Check that the download and install was successful
bool installed = result.Status() == ExecutionProviderReadyResultState::Success;

# Download and install a NotPresent EP
result = provider.ensure_ready_async().get()

# Check that the download and install was successful
installed = result.status == winml.ExecutionProviderReadyResultState.SUCCESS

Instalando con progreso

Las API para descargar e instalar EPs incluyen devoluciones de llamada que proporcionan actualizaciones de progreso, para que puedas mostrar indicadores de progreso y mantener informados a los usuarios.

Captura de pantalla de una barra de progreso que refleja el progreso de la descarga

C#
C++
Python

// Start the download and install of a NotPresent EP
var operation = provider.EnsureReadyAsync();

// Listen to progress callback
operation.Progress = (asyncInfo, progressInfo) =>
{
    // Dispatch to UI thread (varies based on UI platform)
    _dispatcherQueue.TryEnqueue(() =>
    {
        // progressInfo is out of 100, convert to 0-1 range
        double normalizedProgress = progressInfo / 100.0;

        // Display the progress to the user
        Progress = normalizedProgress;
    };
};

// Await for the download and install to complete
var result = await operation;

// Check that the download and install was successful
bool installed = result.Status == ExecutionProviderReadyResultState.Success;

// Start the download and install of a NotPresent EP
auto operation = provider.EnsureReadyAsync();

// Listen to progress callback
operation.Progress([this](auto const& asyncInfo, double progressInfo)
{
    // Dispatch to UI thread (varies based on UI platform)
    dispatcherQueue.TryEnqueue([this, progressInfo]()
    {
        // progressInfo is out of 100, convert to 0-1 range
        double normalizedProgress = progressInfo / 100.0;

        // Display the progress to the user
        Progress(normalizedProgress);
    });
});

// Await for the download and install to complete
auto result = operation.get();

// Check that the download and install was successful
bool installed = result.Status() == ExecutionProviderReadyResultState::Success;

# Start the download and install of a NotPresent EP
operation = provider.ensure_ready_async()

# Listen to progress callback
def on_progress(async_info, progress_info):
    # progress_info is out of 100, convert to 0-1 range
    normalized_progress = progress_info / 100.0

    # Display the progress to the user
    print(f"Progress: {normalized_progress:.0%}")

operation.progress = on_progress

# Await for the download and install to complete
result = operation.get()

# Check that the download and install was successful
installed = result.status == winml.ExecutionProviderReadyResultState.SUCCESS

Pasos siguientes

Ahora que ha instalado proveedores de ejecución, consulte Registro de proveedores de ejecución para obtener información sobre cómo registrarlos para su uso con ONNX Runtime.

Ejemplo de aplicación de producción

En el caso de las aplicaciones de producción, este es un ejemplo de lo que tu aplicación podría querer hacer para darles a ti y a tus usuarios control sobre cuándo ocurren las descargas. Puede comprobar si hay nuevos proveedores de ejecución disponibles y descargarlos condicionalmente antes de registrarse:

C#
C++
Python

using Microsoft.Windows.AI.MachineLearning;

var catalog = ExecutionProviderCatalog.GetDefault();

// Filter to the EPs our app supports/uses
var providers = catalog.FindAllProviders().Where(p =>
    p.Name == "MIGraphXExecutionProvider" ||
    p.Name == "VitisAIExecutionProvider" ||
    p.Name == "OpenVINOExecutionProvider" ||
    p.Name == "QNNExecutionProvider" ||
    p.Name == "NvTensorRtRtxExecutionProvider"
);

if (providers.Any(p => p.ReadyState == ExecutionProviderReadyState.NotPresent))
{
    // Show UI to user asking if they want to download new execution providers
    bool userWantsToDownload = await ShowDownloadDialogAsync();

    if (userWantsToDownload)
    {
        // Download all EPs
        foreach (var p in providers)
        {
            if (p.ReadyState == ExecutionProviderReadyState.NotPresent)
            {
                // Ignore result handling here; production code could inspect status
                await p.EnsureReadyAsync();
            }
        }

        // And register all EPs
        await catalog.RegisterCertifiedAsync();
    }
    else
    {
        // Register only already-present EPs
        await catalog.RegisterCertifiedAsync();
    }
}

using namespace winrt::Microsoft::Windows::AI::MachineLearning;

auto catalog = ExecutionProviderCatalog::GetDefault();
auto allProviders = catalog.FindAllProviders();

// Filter to the EPs our app supports/uses
std::vector<ExecutionProvider> targetProviders;
for (auto const& p : allProviders)
{
    auto name = p.Name();
    if (name == L"VitisAIExecutionProvider" ||
        name == L"OpenVINOExecutionProvider" ||
        name == L"QNNExecutionProvider" ||
        name == L"NvTensorRtRtxExecutionProvider")
    {
        targetProviders.push_back(p);
    }
}

bool needsDownload = false;
for (auto const& p : targetProviders)
{
    if (p.ReadyState() == ExecutionProviderReadyState::NotPresent)
    {
        needsDownload = true;
        break;
    }
}

if (needsDownload)
{
    // Show UI to user or check application settings to confirm download
    bool userWantsToDownload = ShowDownloadDialog();
    if (userWantsToDownload)
    {
        // Download only the missing target providers
        for (auto const& p : targetProviders)
        {
            if (p.ReadyState() == ExecutionProviderReadyState::NotPresent)
            {
                // Ignore result handling here; production code could inspect status
                p.EnsureReadyAsync().get();
            }
        }
        // Register all (both previously present and newly downloaded) providers
        catalog.RegisterCertifiedAsync().get();
    }
    else
    {
        // User deferred download; register only already-present providers
        catalog.RegisterCertifiedAsync().get();
    }
}
else
{
    // All target EPs already present
    catalog.RegisterCertifiedAsync().get();
}

# remove the msvcp140.dll from the winrt-runtime package.
# So it does not cause issues with other libraries.
from pathlib import Path
from importlib import metadata
site_packages_path = Path(str(metadata.distribution('winrt-runtime').locate_file('')))
dll_path = site_packages_path / 'winrt' / 'msvcp140.dll'
if dll_path.exists():
    dll_path.unlink()

from winui3.microsoft.windows.applicationmodel.dynamicdependency.bootstrap import (
    InitializeOptions,
    initialize
)
import winui3.microsoft.windows.ai.machinelearning as winml
import onnxruntime as ort

with initialize(options=InitializeOptions.ON_NO_MATCH_SHOW_UI):
    catalog = winml.ExecutionProviderCatalog.get_default()
    # Filter EPs that the app supports
    providers = [provider for provider in catalog.find_all_providers() if provider.name in [
        'VitisAIExecutionProvider',
        'OpenVINOExecutionProvider',
        'QNNExecutionProvider',
        'NvTensorRtRtxExecutionProvider'
    ]]

    # Download and make ready missing EPs if the user wants to
    if any(provider.ready_state == winml.ExecutionProviderReadyState.NOT_PRESENT for provider in providers):
        # Ask the user if they want to download the missing packages
        if user_wants_to_download:
            for provider in [provider for provider in providers if provider.ready_state == winml.ExecutionProviderReadyState.NOT_PRESENT]:
                provider.ensure_ready_async().get()

    # Make ready the existing EPs
    for provider in [provider for provider in providers if provider.ready_state == winml.ExecutionProviderReadyState.NOT_READY]:
        provider.ensure_ready_async().get()

    # Register all ready EPs
    for provider in [provider for provider in providers if provider.ready_state == winml.ExecutionProviderReadyState.READY]:
        ort.register_execution_provider_library(provider.name, provider.library_path)

Consulte también

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-02-14