Visão geral da API de tempo de execução do Windows ML

Importante

A API do Windows ML Runtime atualmente é experimental e não tem suporte para uso em ambientes de produção. Os aplicativos que estejam testando esta API não devem ser publicados na Microsoft Store.

Importante

A API do runtime do Windows ML está disponível no momento em C++ e Python; Atualmente, não há suporte para C#. Informe-nos se você está interessado em usar essas APIs do C# postando um problema no repositório GitHub do Windows ML!

A API do Windows ML Runtime é uma estrutura de inferência de IA local C/C++ nativa criada especificamente para Windows. Com o Windows API do ML Runtime, você pode carregar um modelo, escolher um destino de execução de CPU, GPU ou NPU (incluindo um adaptador DXCore específico ou um dispositivo D3D12), associar tensores a esse destino, compor estágios de modelo e processador em um pipeline, compilar o pipeline e executá-lo para produzir tensores de saída.

As APIs opcionais de Geração de Texto e Reconhecimento de Fala compõem esses mesmos objetos de Runtime em fluxos de trabalho de nível superior em um modelo fornecido pelo aplicativo: consulte Gerar texto com seu próprio modelo de linguagem usando Windows ML e reconhecer fala com seu próprio modelo Whisper usando Windows ML.

Runtime API vs ONNX Runtime

Se o aplicativo tiver como destino apenas Windows (e você estiver disposto a usar APIs que atualmente são experimentais), use a API do Runtime. Ele fornece controle explícito sobre a seleção de hardware (incluindo um adaptador DXCore específico ou dispositivo D3D12), residência de tensores, posicionamento de pipeline de vários estágios e compilação.

Caso contrário, se o aplicativo precisar ser executado em outras plataformas ou já tiver um código de sessão multiplataforma do ONNX Runtime funcionando, use as APIs do ONNX Runtime incluídas no Windows ML.

Modelo de objeto principal

Conceito API primária Description
Runtime IWinMLRuntime Interface retornada por WinMLCreateRuntime; carrega arquivos de modelo, cria destinos de execução e cria construtores de pipeline.
Model IWinMLModel Artefato de modelo imutável e opaco carregado de um arquivo ou buffer. Reflita seu esquema declarado por meio de IWinMLModelSchema.
Destino de execução IWinMLExecutionTarget Token de posicionamento de CPU, GPU ou NPU usado para montar estágios e criar tensores.
Construtor de pipelines IWinMLPipelineBuilder Adiciona estágios de modelo e processador, conecta-os e cria um pipeline preparado.
Pipeline IWinMLPipeline Gráfico preparado e executável imediatamente que executa tensores associados e produz tensores de saída.
Stage IWinMLStage Uma etapa no pipeline que possui associações de entrada e saída posicionais e seu destino de execução resolvido.
Tensor IWinMLTensor Dados multidimensionais digitados vinculados às entradas e saídas do estágio.
Geração de texto/reconhecimento de fala APIs do Windows ML de Reconhecimento de Fala e Geração de Texto Fluxo de trabalho de nível superior composto por objetos Runtime de propriedade do chamador, com sessões tipadas, fluxos e resultados.

Escolha um back-end e um alvo de execução

LoadModelFromFile seleciona o back-end com base na extensão de arquivo do artefato de modelo. Seu aplicativo usa os mesmos objetos de runtime — modelo, destino de execução, construtor de pipeline, estágios, associações e Run — não importa qual back-end carregue o arquivo.

Arquivo de modelo Backend Aceleração de hardware
.onnx, .ort ONNX Runtime Provedores de execução (EPs) que o Windows instala e mantém atualizados por meio do catálogo de EP do Windows ML
.gguf llama.cpp Um módulo de CPU local do aplicativo, além de um módulo CUDA opcional para GPUs NVIDIA que você implanta junto com seu aplicativo. CPU e CUDA são os únicos back-ends do llama.cpp que o Windows ML valida para esta versão.

Um destino de execução representa uma classe de hardware — CPU, GPU ou NPU — criada com IWinMLRuntime. Reutilizar um destino para criar estágios e criar tensores: reutilizar um destino expressa afinidade de mesmo destino, enquanto o uso de destinos distintos torna explícitos os limites de transferência entre destinos. Quando o método do construtor de Build pipeline é executado, o runtime coloca cada estágio no back-end de execução para seu destino e confirma a compatibilidade de destino e back-end.

Para uma classe de hardware sem enumerar dispositivos por conta própria, chame CreateExecutionTarget com um WINML_EXECUTION_TARGET_KIND e um WINML_EXECUTION_TARGET_PREFERENCE que classifica os candidatos dessa classe, como uma GPU integrada versus uma GPU discreta. Trate ERROR_NOT_FOUND e ERROR_NOT_SUPPORTED do mesmo modo e volte para outra classe:

ComPtr<IWinMLExecutionTarget> target;
HRESULT hr = runtime->CreateExecutionTarget(
    WINML_EXECUTION_TARGET_KIND_NPU,
    WINML_EXECUTION_TARGET_PREFERENCE_EFFICIENCY,
    target.GetAddressOf());
if (hr == HRESULT_FROM_WIN32(ERROR_NOT_FOUND) ||
    hr == HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED))
{
    THROW_IF_FAILED(runtime->CreateExecutionTarget(
        WINML_EXECUTION_TARGET_KIND_GPU,
        WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
        target.GetAddressOf()));
}
else
{
    THROW_IF_FAILED(hr);
}

CreateCpuExecutionTarget é equivalente a solicitar o tipo de CPU. CreateExecutionTargetFromAdapter e CreateExecutionTargetFromD3D12 vinculam um destino a um adaptador DXCore específico ou dispositivo D3D12 em vez de deixar o Runtime escolher um. Para modelos ONNX que dependem de um EP (provedor de execução) instalado, uma superfície de compatibilidade opcional do ONNX Runtime permite fixar um provedor que você já registrou. Cada back-end resolve esses alvos de maneira diferente — por exemplo, o back-end llama.cpp usado pelos modelos .gguf requer pelo menos descarregamento parcial de GPU para honrar um alvo de GPU e não oferece suporte a alvos de NPU ou fixação de provedor. Para obter a matriz de resolução de destino completa por backend e para obter um passo a passo da execução de um modelo GGUF, consulte Conceitos da API do Windows ML Runtime.

Próximas Etapas 

  • Última atualização em