conceitos da API do runtime 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 estão testando esta API não devem ser publicados na Microsoft Store.

A API do Windows ML Runtime é uma estrutura de inferência de IA local nativa criada especificamente para Windows. Com a API do Windows ML Runtime, você tem controle explícito sobre o carregamento de modelos, o posicionamento de hardware, a propriedade do tensor, a composição do pipeline, a compilação e o diagnóstico.

Recomendamos usar a API do Runtime para obter o melhor desempenho de inferência de modelos no Windows, mas, se o app precisar ser executado em outras plataformas ou se você já tiver um código multiplataforma funcional do ONNX Runtime, também poderá usar o ONNX Runtime por meio do Windows ML.

Como os objetos se encaixam

IWinMLRuntime
  |-- loads --> IWinMLModel
  |-- creates -> IWinMLExecutionTarget
  `-- creates -> IWinMLPipelineBuilder
                   |-- adds/connects -> IWinMLStage
                   `-- Build() ------> IWinMLPipeline

IWinMLExecutionTarget -- creates --> IWinMLTensor
IWinMLStage ----------- binds -----> IWinMLTensor
IWinMLPipeline -------- Run() -----> stage outputs

Cada método retorna HRESULTe cada ponteiro de interface segue a contagem normal de referência COM. Recursos opcionais são descobertos com QueryInterface; uma funcionalidade indisponível retorna E_NOINTERFACE.

Runtime

Criar IWinMLRuntime com WinMLCreateRuntime. Use-o para carregar artefatos de modelo, criar destinos de execução e criar construtores de pipeline.

Modelos e esquema

IWinMLModel é um artefato de modelo imutável e opaco. LoadModelFromFile aceita qualquer caminho de arquivo absoluto ou relativo que seu aplicativo possa ler; o local do modelo é a decisão de empacotamento do aplicativo.

O carregamento confirma que o artefato é reconhecido e estruturalmente legível. A compatibilidade com o destino é confirmada posteriormente, quando o método Build do construtor de pipeline for bem-sucedido.

Reflita o esquema ordinal declarado de um modelo por meio de IWinMLModelSchema. Alguns artefatos ONNX também expõem nomes por meio do opcional IWinMLOrtModelSchema, mas a identidade de execução permanece posicional.

Formas e operadores

Um esquema de modelo declarado pode conter dimensões livres, representadas por UINT64_MAX. Um elemento concreto IWinMLTensor sempre tem dimensões resolvidas. Pipelines com suporte ORT podem vincular e executar valores concretos para uma dimensão livre.

Formas fixas ou explicitamente delimitadas permanecem o centro de projeto otimizado porque permitem que Build valide a compatibilidade, aloque recursos estáveis e determine se a repetição ou a iteração residente no dispositivo é permitida. Eles também fornecem a compatibilidade mais ampla com os backends de execução. Essa é uma distinção de otimização e portabilidade, não uma rejeição geral de modelos cujo esquema ONNX declarado contém dimensões livres.

Os operadores ONNX padrão também melhoram a portabilidade de back-end. Uma carga de modelo bem-sucedida não garante que cada destino possa executar todos os operadores; Build é a verificação de compatibilidade.

Backends

O arquivo de modelo seleciona o back-end. Seu aplicativo usa os mesmos objetos runtime de qualquer maneira: modelo, destino de execução, construtor de pipeline, estágios, associações e Run.

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 llama.cpp módulos implantados com seu aplicativo: um módulo de CPU no pacote e um módulo CUDA opcional para GPUs NVIDIA. CPU e CUDA são os únicos backends do llama.cpp que o Windows ML valida para esta versão.

Os back-ends diferem no que um estágio pode expressar:

Capability ONNX Runtime llama.cpp
Forma do palco Qualquer grafo ONNX; vários estágios podem ser conectados em um pipeline Um estágio de decodificação por arquivo GGUF: IDs de token de entrada (entrada 0), logits de saída (saída 0)
Estado da sequência (cache KV) Declare pares tensores de estado com IWinMLStatefulStageOptions; o Runtime os gerencia Gerenciado pelo backend; nada para declarar
Tamanho do contexto SetSequenceCapacityHint antes de Build, ou a capacidade declarada do modelo SetSequenceCapacityHint antes de Build define o comprimento do contexto llama.cpp
define o comprimento do contexto llama.cpp Com suporte (WinMLRuntimeOrt.h) Sem suporte; Build retorna HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)
Relatório de posicionamento após Build IWinMLOrtStageDiagnostics nomeia os provedores solicitados e selecionados IWinMLStage::GetExecutionTarget reporta CPU ou GPU

Um pipeline pode misturar back-ends. Por exemplo, um estágio Whisper no ONNX Runtime pode alimentar um modelo de linguagem GGUF em llama.cpp.

Alvos de execução

IWinMLExecutionTarget é um token de posicionamento imutável que solicita uma classe de hardware e, opcionalmente, um adaptador específico. Cada back-end o resolve quando Build é executado:

Destino do estágio ONNX Runtime llama.cpp
nullptr passado para AddModelStage O posicionamento automático seleciona um EP de GPU compatível quando disponível, com fallback de CPU. Descarrega para o módulo CUDA quando um é implantado e o modelo se ajusta; caso contrário, executa na CPU.
CreateCpuExecutionTarget Seleciona um EP de CPU compatível, com o provedor de CPU do ORT como a linha de base. É executado na CPU.
CreateExecutionTarget com o tipo de GPU, CreateExecutionTargetFromAdapterou CreateExecutionTargetFromD3D12 Mapeia a identidade do adaptador para um dispositivo EP de GPU compatível. Se nenhum dispositivo de provedor corresponder, Build falhará. Requer pelo menos descarregamento parcial para o módulo CUDA. Build retorna HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) quando nenhum módulo CUDA é implantado e HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY) quando o modelo não cabe. O módulo escolhe a GPU; a identidade do adaptador não é usada.
CreateExecutionTarget com o tipo de NPU ou um adaptador de NPU Mapeia para um dispositivo EP de NPU compatível. Sem suporte; Build retorna HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).
IWinMLOrtCompatibility::CreateExecutionTarget(provider, kind, hardwareTarget) Fixa um EP registrado. Com hardwareTarget definido como nullptr, o Runtime emparelha o provedor com um de seus próprios dispositivos; em um computador com duas GPUs, isso evita emparelhar o provedor com um adaptador que ele não suporta. Sem suporte; Build retorna HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

IWinMLRuntime::CreateExecutionTarget(kind, preference) escolhe um adaptador da classe solicitada sem exigir que você enumere dispositivos por conta própria, e preference classifica os adaptadores quando há mais de um, por exemplo, uma GPU integrada e discreta:

ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateExecutionTarget(
    WINML_EXECUTION_TARGET_KIND_GPU,
    WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
    target.GetAddressOf()));

A seleção explícita do adaptador requer um provedor onnx runtime compatível para expor essa identidade de hardware por meio de ORT. Se nenhum dispositivo de provedor corresponder, Build falhará em vez de selecionar silenciosamente outro adaptador ou CPU.

CreateExecutionTargetFromD3D12 mantém o dispositivo do chamador e a fila opcional no destino, mas a execução ORT usa apenas a identidade do adaptador para a seleção de EP. O provedor ORT possui seus recursos de execução e a fila de comandos do chamador não é usada para envio ORT.

Um destino D3D12 ainda expõe IWinMLD3D12ExecutionTarget até QueryInterface. Reutilizar um destino explícito entre estágios expressa afinidade com o mesmo adaptador; destinos distintos tornam os limites de transferência explícitos.

Executar um modelo GGUF

  1. Carregue o arquivo com LoadModelFromFile. A extensão .gguf seleciona llama.cpp. Para um modelo fragmentado, mantenha cada fragmento em uma pasta e carregue o primeiro fragmento.
  2. Adicione um estágio de modelo com um destino de CPU, GPU ou nullptr. Para definir o comprimento do contexto, consulte IWinMLStatefulStageOptions do estágio e chame SetSequenceCapacityHint.
  3. Chame Build. Em seguida, associe as IDs de token do prompt à entrada 0, solicite a saída 0 e chame Run. Cada execução posterior usa o próximo token; o back-end mantém o cache KV entre execuções.
  4. Chame ResetExecutionState antes de uma sequência independente.
// Create the runtime and an execution target (CPU here; GPU also available).
ComPtr<IWinMLRuntime> runtime;
THROW_IF_FAILED(WinMLCreateRuntime(IID_PPV_ARGS(runtime.GetAddressOf())));
ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateCpuExecutionTarget(target.GetAddressOf()));

ComPtr<IWinMLModel> model;
THROW_IF_FAILED(runtime->LoadModelFromFile(
    L"C:\\models\\qwen2.5-0.5b-instruct.gguf", nullptr, model.GetAddressOf()));

ComPtr<IWinMLPipelineBuilder> builder;
THROW_IF_FAILED(runtime->CreatePipelineBuilder(builder.GetAddressOf()));

ComPtr<IWinMLStage> stage;
THROW_IF_FAILED(builder->AddModelStage(
    model.Get(), target.Get(), L"decoder", stage.GetAddressOf()));
THROW_IF_FAILED(stage->RequestOutput(0));

// Set the llama.cpp context length before Build.
ComPtr<IWinMLStatefulStageOptions> stateOptions;
THROW_IF_FAILED(stage->QueryInterface(IID_PPV_ARGS(stateOptions.GetAddressOf())));
THROW_IF_FAILED(stateOptions->SetSequenceCapacityHint(4096));

ComPtr<IWinMLPipeline> pipeline;
THROW_IF_FAILED(builder->Build(pipeline.GetAddressOf()));

// Bind token IDs to input 0 and run one token at a time; the backend keeps
// the KV cache between runs.
THROW_IF_FAILED(stage->BindInput(0, tokenIdsTensor.Get()));
THROW_IF_FAILED(pipeline->Run());

ComPtr<IWinMLTensor> logits;
THROW_IF_FAILED(stage->GetOutput(0, logits.GetAddressOf()));

// Start an independent sequence on the same pipeline.
THROW_IF_FAILED(pipeline->ResetExecutionState());

O tokenizador e a formatação de conversa vêm do arquivo GGUF, portanto, um modelo GGUF não precisa de arquivos de tokenizer separados. Para ignorar o loop de token, use a API de Geração de Texto, que funciona com modelos GGUF e ONNX.

Implantar o back-end llama.cpp

O llama.cpp backend é local ao aplicativo. Quando um projeto opta por participar, o pacote NuGet do ML do Windows copia o adaptador llama.cpp do Runtime, o núcleo llama.cpp e o módulo de CPU para o diretório do seu aplicativo. A aceleração por GPU requer o módulo CUDA opcional, compilado para a mesma revisão do llama.cpp que o pacote e colocado ao lado do seu aplicativo.

Para obter um passo a passo de ambas as etapas, consulte os exemplos de modelo GGUF e exemplos de llama.cpp.

Pipelines e estágios

Crie um pipeline com o one-shot IWinMLPipelineBuilder:

  1. Adicione estágios de modelo ou processador com seus destinos de execução.
  2. Conectar portas do stage por índice ordinal.
  3. Chame Build uma vez para congelar o grafo, resolver o posicionamento e validar a compatibilidade.

Para dois estágios de modelo, adicione ambos os estágios, conecte o ordinal de saída do primeiro estágio ao ordinal de entrada do segundo estágio e compile uma vez. Seu aplicativo fornece os modelos e associa quaisquer entradas externas. Ele não precisa de uma API de Runtime específica do modelo: embedding, decodificador, pré-processamento de imagem e outras arquiteturas de aplicativo usam os mesmos primitivos de estágio e tensor.

Cada IWinMLStage possui associações de entrada posicionais e expõe seus tensores de saída atuais. As associações de entrada persistem entre execuções. Chame BindOutput antes de uma execução quando seu aplicativo fornecer armazenamento de saída.

Os recursos de estágio opcionais incluem destino resolvido, esquema materializado, política de residência de saída e controle de estado de sequência. Use QueryInterface para testar cada capacidade.

Execução de pipeline

IWinMLPipeline::Run executa o pipeline preparado de forma síncrona. Chame ResetExecutionState entre sequências independentes para limpar o estado gerenciado por runtime.

As interfaces de execução opcionais fornecem o envio da linha do tempo do dispositivo e a reprodução iterativa de contagem fixa quando o grafo criado e o back-end selecionado dão suporte a eles. O caminho básico Run continua sendo a linha de base comum.

Tensores e travas

IWinMLTensor representa dados tipados e multidimensionais. Crie tensores a partir de uma fábrica consultada do destino de execução para que o posicionamento do tensor siga o posicionamento do destino.

As fábricas abrangem bytes brutos, dados de imagem, dados de áudio, IDs de token e processadores tensor composáveis. Interfaces opcionais de tensores expõem mutação, associações de buffer D3D12 e sincronização.

Chame IWinMLTensor::Lock antes de acessar os bytes do tensor na CPU. O valor retornado por IWinMLTensorDataLock estabelece a janela de acesso à CPU, executa o mapeamento ou a sincronização necessários e controla o tempo de vida do ponteiro retornado por GetData.

Compilação e pesos externos

A compilação antecipada é um recurso opcional de um destino de execução, exposto por meio de IWinMLModelCompiler. Artefatos compilados são recarregados por meio dos métodos normais de carregamento de modelo. Os aplicativos podem fornecer pesos externalizados por meio de IWinMLResourceMapReader.

Cargas de trabalho de texto

As cargas de trabalho de texto usam os mesmos primitivos de runtime, destino, pipeline, estágio e tensor. Seu aplicativo pode ter metadados de pacote de modelo, amostragem, política de parada e acúmulo de token gerado diretamente ou usar a API de Geração de Texto para coordenar essas operações em um pipeline de Runtime compatível.

IWinMLTokenizer fornece operações de codificação e decodificação de baixo nível. Um IWinMLTokenizerDecoder mantém um cursor de decodificação incremental independente para uma sequência. A API de Geração de Texto adiciona sessões de geração de texto, opções, atualizações de streaming, cancelamento, motivos de término e resultados concluídos sem alterar a propriedade dos objetos de Runtime subjacentes.

Compatibilidade do ONNX Runtime

Cargas de trabalho de texto WinMLRuntimeOrt.h fornecem conveniências do ONNX:

  • IWinMLOrtCompatibility seleciona um provedor de execução ONNX Runtime já registrado.
  • IWinMLOrtModelSchema reflete os nomes de entrada e saída.
  • IWinMLOrtNamedBindings associa um estágio apoiado por ORT pelo nome.
  • IWinMLOrtStageDiagnostics relata os provedores solicitados e selecionados após Build.

Essas interfaces resolvem nomes e política de provedor durante a instalação. A execução continua a usar o mesmo contrato de pipeline posicional.

Consulte IWinMLOrtCompatibility no ambiente de execução para fixar um estágio do modelo ONNX a um provedor de execução que você já registrou, em vez de deixar Build escolher um automaticamente:

ComPtr<IWinMLOrtCompatibility> ortCompatibility;
THROW_IF_FAILED(runtime->QueryInterface(IID_PPV_ARGS(ortCompatibility.GetAddressOf())));

ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(ortCompatibility->CreateExecutionTarget(
    L"MyRegisteredProvider",
    WINML_EXECUTION_TARGET_KIND_GPU,
    /* hardwareTarget */ nullptr,
    target.GetAddressOf()));

Passar nullptr para hardwareTarget permite que o Runtime emparelhe o provedor com um de seus próprios dispositivos dessa classe de hardware; passe um existente IWinMLExecutionTarget para fixar o provedor nesse adaptador específico. Este destino não é compatível com estágios .gguf; Build retorna HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

Consulte também

  • Última atualização em