APIs de ML do Windows

2025-05-20

Para obter orientação conceitual, consulte Executar modelos ONNX com o Windows ML).

Você pode pensar nas APIs no pacote NuGet Microsoft.Windows.AI.MachineLearning como sendo o superconjunto desses três conjuntos:

Novas APIs. Novas APIs de ML do Windows, como a classe Infrastructure e seus métodos (que são APIs do Tempo de Execução do Windows); e como a função WinMLInitialize (que é uma API Win32 simples no estilo C e é uma das APIs de bootstrap do Windows ML). Essas APIs estão documentadas no tópico que você está lendo agora.
APIs da versão mais antiga do Windows ML. APIs de ML do Windows que foram copiadas do namespace Windows.AI.MachineLearning . Portanto, por enquanto, você pode aprender sobre essas APIs, com o entendimento de que elas existem agora também no Microsoft.Windows.AI.MachineLearning, na documentação do Windows.AI.MachineLearning. Consulte APIs de ML do Windows em Windows.AI.MachineLearning.
APIs de tempo de execução ONNX. Implementações do Windows ML (no pacote NuGet Microsoft.Windows.AI.MachineLearning) para certas APIs do ONNX Runtime (ORT). Para obter documentação, consulte a documentação da API do ONNX Runtime. Por exemplo, o struct OrtCompileApi. Para obter exemplos de código que usam essas APIs e mais links para a documentação, consulte o tutorial Usar o Windows ML para executar o modelo ResNet-50 .

O pacote NuGet Microsoft.Windows.AI.MachineLearning

O tempo de execução do Microsoft Windows ML fornece APIs para aprendizado de máquina e operações de IA em aplicativos do Windows. O pacote NuGet Microsoft.Windows.AI.MachineLearning fornece os arquivos de tempo de execução .winmd do Windows ML para uso em projetos C# e C++.

Novas APIs do Tempo de Execução do Windows

Classe de infraestrutura

A classe Infrastructure fornece métodos para baixar, configurar e registrar provedores de execução de IA (EPs) para uso com o ONNX Runtime. A infraestrutura lida com a complexidade do gerenciamento de pacotes e da seleção de hardware.

Esta classe é o ponto de entrada para a sua aplicação aceder à aceleração de aprendizagem automática otimizada por hardware através da runtime do Windows ML.

C#
C++/WinRT

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)

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 da classe de infraestrutura

Método Infrastructure.DownloadPackagesAsync

Transfere dependências de pacotes para a configuração de hardware atual. Isso garante que os provedores de execução apropriados para o hardware do dispositivo estejam instalados e up-todata.

C#
C++/WinRT

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

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 as bibliotecas do provedor de execução relevantes para a configuração de hardware atual com o ONNX Runtime. É importante chamar este método antes de criar sessões Runtime ONNX.

Importante

A instância de infraestrutura deve manter-se válida ao usar o tempo de execução do ONNX após a chamada para RegisterExecutionProviderLibrariesAsync.

C#
C++/WinRT

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)

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

Obtém um mapa de nomes de provedores de execução para seus caminhos de arquivo completos. Isso permite que os aplicativos recuperem informações sobre os provedores de execução disponíveis e seus locais.

C#
C++/WinRT

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

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

Outros membros da infraestrutura

Nome	Descrição
Infraestrutura()	Construtor padrão que inicializa uma instância da classe Infrastructure

Detalhes da 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 sobre a aplicação

A classe Infrastructure lida com o gerenciamento de pacotes internamente usando as APIs InstallControl da Microsoft Store, que devem ser chamadas a partir do pacote principal de tempo de execução do Windows ML, porque é assinado pela Microsoft. Isto inclui:

Resolução de provedores de execução (EPs) disponíveis para a configuração de hardware atual.
Gerenciando o tempo de vida e as atualizações do pacote.
Tratamento do registo e ativação de pacotes.
Suporte a diferentes versões de provedores de execução

Descoberta de pacotes

Os provedores de execução (EPs) são empacotados como componentes MSIX separados que declaram a extensão com.microsoft.windowsmlruntime.executionprovider nos seus manifestos de pacote. Esse design permite que os provedores de execução sejam atualizados independentemente dos componentes do Tempo de Execução do Windows ML.

O tempo de execução do Windows ML descobre esses pacotes por meio da infraestrutura de Extensão de Pacote que foi introduzida no Windows 11. Para cada EP descoberto, o tempo de execução avalia a compatibilidade de hardware e carrega a implementação apropriada para o sistema atual.

Usando o Runtime ONNX com o Runtime do Windows ML

Para aplicações C++, depois de chamar o RegisterExecutionProviderLibrariesAsync, use a API C do ONNX Runtime diretamente para criar sessões e executar inferência.

Para aplicativos C#, use o ONNX Runtime diretamente para inferência usando o Microsoft.ML.OnnxRuntime namespace.

APIs Win32 de estilo C planas e totalmente novas (APIs de inicialização do Windows ML)

Os requisitos a seguir se aplicam a todas as funções de bootstrap do Windows ML documentadas abaixo.

Requisito	Valor
pacote NuGet	Microsoft.Windows.AI.Aprendizagem Automática
Cabeçalho	WinMLBootstrap.h
Espaço de nomes	Nenhum

Função de retorno de chamada WinMLStatusCallback

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

Função 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);

Função 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);

Função 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);

Função 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);

Função 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);

Função 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();

Ver também

Executar modelos ONNX com o Windows ML (Microsoft.Windows.AI.MachineLearning)