Introdução ao Windows ML

Este tópico mostra como instalar e usar o Windows ML para descobrir, baixar e registrar provedores de execução (EPs) para uso com o Tempo de Execução ONNX fornecido com o Windows ML. O Windows ML lida com a complexidade do gerenciamento de pacotes e da seleção de hardware, baixando automaticamente os provedores de execução mais recentes compatíveis com o hardware do seu dispositivo.

Se você ainda não está familiarizado com o ONNX Runtime, sugerimos ler os documentos do ONNX Runtime. Em resumo, o Windows ML fornece uma cópia compartilhada em todo o Windows do Tempo de Execução ONNX, além da capacidade de baixar dinamicamente provedores de execução (EPs).

Pré-requisitos

Versão do Windows suportada pelo Windows App SDK
Pré-requisitos específicos do idioma vistos abaixo

.NET 6 ou superior
Direcionando um TFM específico do Windows 10 como net6.0-windows10.0.19041.0 ou superior

Etapa 1: Instalar ou atualizar o SDK do Aplicativo Windows

As APIs do Catálogo de Modelos estão incluídas na versão experimental do Windows App SDK 2.0.0 ou superior.

Consulte Usar o SDK de Aplicativo Windows em um projeto existente para saber como adicionar o SDK de Aplicativo Windows ao seu projeto ou, se você já estiver usando o SDK de Aplicativo Windows, atualizar seus pacotes.

A vinculação Python aproveita o projeto pywinrt para a projeção do SDK do Aplicativo Windows. Certifica-te de que a tua instalação em Python não vem da Microsoft Store (podes instalar uma versão não embalada a partir do python.org ou através do winget). O exemplo depende do uso da API dinâmica de dependência do SDK do Windows App, que só é válida para aplicações não empacotadas.

Instale os pacotes python com estes comandos:

pip install wasdk-Microsoft.Windows.AI.MachineLearning[all] wasdk-Microsoft.Windows.ApplicationModel.DynamicDependency.Bootstrap
# The onnxruntime-winml package is not published to PyPI yet. Please install it from the ort-nightly feed
pip install --pre --index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT-Nightly/pypi/simple/ --extra-index-url https://pypi.org/simple onnxruntime-winml

Verifique se a versão dos wasdk- pacotes corresponde à versão do WindowsAppRuntime.

Passo 2: Descarregue e registe os PEs

A maneira mais simples de começar é permitir que o Windows ML descubra, baixe e registre automaticamente a versão mais recente de todos os provedores de execução compatíveis. Os provedores de execução precisam ser registrados no Tempo de Execução ONNX dentro do Windows ML antes que você possa usá-los. E se eles ainda não foram baixados, eles precisam ser baixados primeiro. Ligar EnsureAndRegisterCertifiedAsync() fará as duas coisas em uma única etapa.

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

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

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

// Ensure and register all compatible execution providers with ONNX Runtime
// This downloads any necessary components and registers them
await catalog.EnsureAndRegisterCertifiedAsync();

#include <winrt/Microsoft.Windows.AI.MachineLearning.h>
#include <winml/onnxruntime_cxx_api.h>

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

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

// Ensure and register all compatible execution providers with ONNX Runtime
catalog.EnsureAndRegisterCertifiedAsync().get();

import sys
from pathlib import Path
import traceback

_winml_instance = None

class WinML:
    def __new__(cls, *args, **kwargs):
        global _winml_instance
        if _winml_instance is None:
            _winml_instance = super(WinML, cls).__new__(cls, *args, **kwargs)
            _winml_instance._initialized = False
        return _winml_instance

    def __init__(self):
        if self._initialized:
            return
        self._initialized = True

        self._fix_winrt_runtime()
        from winui3.microsoft.windows.applicationmodel.dynamicdependency.bootstrap import (
            InitializeOptions,
            initialize
        )
        import winui3.microsoft.windows.ai.machinelearning as winml
        self._win_app_sdk_handle = initialize(options=InitializeOptions.ON_NO_MATCH_SHOW_UI)
        self._win_app_sdk_handle.__enter__()
        catalog = winml.ExecutionProviderCatalog.get_default()
        self._providers = catalog.find_all_providers()
        self._ep_paths : dict[str, str] = {}
        for provider in self._providers:
            provider.ensure_ready_async().get()
            if provider.library_path == '':
                continue
            self._ep_paths[provider.name] = provider.library_path
        self._registered_eps : list[str] = []

    def __del__(self):
        self._providers = None
        self._win_app_sdk_handle.__exit__(None, None, None)

    def _fix_winrt_runtime(self):
        """
        This function removes the msvcp140.dll from the winrt-runtime package.
        So it does not cause issues with other libraries.
        """
        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()

    def register_execution_providers_to_ort(self) -> list[str]:
        import onnxruntime as ort
        for name, path in self._ep_paths.items():
            if name not in self._registered_eps:
                try:
                    ort.register_execution_provider_library(name, path)
                    self._registered_eps.append(name)
                except Exception as e:
                    print(f"Failed to register execution provider {name}: {e}", file=sys.stderr)
                    traceback.print_exc()
        return self._registered_eps

WinML().register_execution_providers_to_ort()

Sugestão

Em aplicativos de produção, envolva a EnsureAndRegisterCertifiedAsync() chamada em um bloco try-catch para lidar com possíveis falhas de rede ou download normalmente.

Próximos passos

Depois de registrar provedores de execução, você estará pronto para usar as APIs de tempo de execução ONNX no Windows ML! Você vai querer...

Selecionar provedores de execução - Informe ao tempo de execução quais provedores de execução você deseja usar
Obtenha seus modelos - Use o Catálogo de modelos para baixar dinamicamente os modelos ou incluí-los localmente
Executar inferência de modelo - Compile, carregue e infera seu modelo

Importante

Os projetos C# que usam as Microsoft.ML.OnnxRuntime.Tensors APIs devem fazer referência manual ao pacote NuGet System.Numerics.Tensors , versão 9.0.0 ou superior. Sem essa referência de pacote NuGet, seu código enfrentará o seguinte erro de tempo de execução: Could not load file or assembly 'System.Numerics.Tensors, Version=9.0.0.0.

Consulte também

Catálogo de modelos - Baixe dinamicamente modelos de catálogos on-line
Inicializar provedores de execução - Maneiras adicionais de lidar com o download de EPs
Distribuir seu aplicativo - Informações sobre como distribuir um aplicativo usando o Windows ML
Versões ONNX no Windows ML - Informações sobre qual versão do ONNX Runtime é fornecida com o Windows ML
Tutorial - Tutorial completo de ponta a ponta usando o Windows ML com o modelo ResNet-50
Exemplos de código - Nossos exemplos de código usando o Windows ML

Feedback

Esta página foi útil?

Last updated on 2025-12-11