Compilar e armazenar em cache modelos ONNX no Windows ML

Compilação é a etapa que transforma seu modelo ONNX no binário específico de hardware que um EP (provedor de execução) realmente executa. Em NPUs e GPUs, essa etapa pode levar de alguns segundos a vários minutos para modelos grandes e, se o aplicativo não armazenar em cache o resultado, os usuários pagarão esse custo sempre que seu aplicativo for iniciado.

Esta página explica o que a compilação envolve, quando pré-compilar e como validar um modelo compilado em cache antes de reutilizá-lo.

Pré-requisitos

As APIs de compatibilidade do modelo compilado exigem Windows ML 2.3 ou posterior. No Upstream ONNX Runtime, GetModelCompatibilityForEpDevices() está disponível na versão 1.23 e GetCompatibilityInfoFromModel() está disponível na versão 1.24.

Dois tipos de compilação

"Compilação" pode significar duas coisas diferentes. Separá-los torna o restante desta página mais fácil de entender:

  • Otimização de grafo — fusão, simplificação de constantes e ajustes de layout que o ONNX Runtime realiza durante a criação da sessão. É barato, não depende de EP e é executado toda vez que você cria uma sessão.
  • Compilação de EP – conversão do grafo ONNX em um formato próprio de EP, seguida pela compilação até um binário específico de hardware. Os EPs de hardware (QNN, OpenVINO, VitisAI, NvTensorRtRtx, MIGraphX) fazem isso, e essa é a etapa mais custosa. Em NPUs, pode levar dezenas de segundos a minutos para modelos maiores.

O ML do Windows evita pagar novamente a compilação EP usando o mecanismo EPContext do ONNX Runtime. A primeira compilação serializa um binário pronto para hardware em um modelo *_ctx.onnx (ou em um .bin de sidecar); nas sessões posteriores, o binário pré-compilado é carregado, e a conversão é completamente ignorada.

Por que pré-compilar?

Windows ML recomenda muito a pré-compilação ao usar provedores de execução. A pré-compilação transforma uma inicialização a frio de vários segundos — às vezes, vários minutos — em um custo único e dá ao seu aplicativo:

  • Inícios rápidos e frios – as inicializações subsequentes ignoram a conversão de grafo e a compilação de hardware.
  • Comportamento previsível – a plataforma dá suporte à verificação se um modelo compilado é ideal para os dispositivos selecionados pelo aplicativo antes de criar uma sessão de inferência.
  • Menor uso de CPU e bateria – você para de recompilar o mesmo grafo em cada inicialização.

Sem a pré-compilação, seu aplicativo executa novamente a conversão e a compilação de EP em cada criação de sessão e os usuários sentem o atraso a cada vez.

Quando pré-compilar

Faça a pré-compilação sempre que seu aplicativo tiver como destino um EP de hardware. Duas opções de tempo estão disponíveis:

Strategy Melhor para Compensações
Compilação antecipada (AOT) — compila no momento da construção ou da instalação e distribui o artefato compilado. Frotas controladas de hardware e de drivers, ou instaladores por dispositivo. Requer ferramentas de compilação cruzada para destinos que seu computador de build não pode executar. Valide o artefato no dispositivo de destino e forneça uma alternativa de recompilação.
Compile na primeiraexecução (recomendado para distribuição ampla) – verifique se há um artefato compilado, compile-o se estiver ausente e armazene-o em cache e reutilize-o. Aplicativos da loja e distribuição geral ao consumidor em uma ampla variedade de hardware. Os usuários pagam o custo da compilação uma vez, na primeira inicialização.

O passo a passo do Windows ML demonstra a mecânica básica de compilação em primeira execução verificando se existe um artefato compilado. Não é um exemplo completo de gerenciamento de cache. Antes de reutilizar um modelo compilado existente em um aplicativo, aplique a verificação de compatibilidade descrita neste artigo. Para obter a API de compilação no contexto, consulte Compilar modelos.

Validar um modelo compilado antes da reutilização

Um modelo compilado pode depender da configuração do EP e do dispositivo que o produziu. O EP determina se um modelo armazenado em cache permanece compatível e ideal para um conjunto de dispositivos.

Durante a compilação, um EP pode gerar uma cadeia de caracteres de compatibilidade UTF-8 terminada em nulo que o ONNX Runtime grava nas propriedades de metadados do modelo compilado. O formato e o conteúdo da cadeia de caracteres são definidos pelo EP. Seu aplicativo não deve analisá-lo nem interpretá-lo.

Seu aplicativo envia a string e os dispositivos EP de destino para GetModelCompatibilityForEpDevices(). O ONNX Runtime chama a implementação de validação da fábrica de EP e retorna um status OrtCompiledModelCompatibility. Para os contratos de origem, consulte GetModelCompatibilityForEpDevices() e ValidateCompiledModelCompatibilityInfo() no repositório ONNX Runtime.

Cenários de verificação de compatibilidade

Você pode usar a mesma API de validação em dois cenários:

  • Valide um modelo que já esteja no dispositivo. Chame GetCompatibilityInfoFromModel() para extrair a cadeia de caracteres de um arquivo de modelo compilado. Se o modelo já estiver na memória, chame GetCompatibilityInfoFromModelBytes(). Em seguida, passe a cadeia de caracteres para GetModelCompatibilityForEpDevices().
  • Valide antes de baixar um modelo compilado. Publique a cadeia de caracteres opaca como metadados leves ao lado do modelo compilado. Seu aplicativo pode recuperar a string primeiro, validá-la com GetModelCompatibilityForEpDevices() e baixar o modelo potencialmente grande somente quando o status retornado atender à sua política de cache ou de implantação.

Mantenha os metadados remotos de compatibilidade associados ao artefato compilado exato que os produziu. Se o artefato for alterado, atualize a cadeia de caracteres de compatibilidade associada.

Em qualquer cenário:

  1. Chame GetEpDevices() para enumerar os dispositivos EP disponíveis e aplique a mesma política de EP ou dispositivo que você usa para configurar a sessão de inferência.
  2. Obtenha a cadeia de caracteres de compatibilidade do modelo local ou de metadados associados a um modelo remoto.
  3. Passe a cadeia de caracteres e o grupo de dispositivos correspondentes para GetModelCompatibilityForEpDevices().
  4. Aplique sua política de cache ou download ao status retornado. Os exemplos de ML Windows usam uma política conservadora e aceitam o modelo compilado apenas para EP_SUPPORTED_OPTIMAL.

GetCompatibilityInfoFromModel() analisa o ONNX ModelProto completo do disco. Use o padrão de metadados remotos quando precisar tomar uma decisão de compatibilidade antes de baixar o próprio modelo.

As APIs retornam um valor OrtCompiledModelCompatibility:

Status Meaning Ação recomendada
EP_SUPPORTED_OPTIMAL O modelo compilado tem suporte e é ideal para os dispositivos EP. Reutilize o modelo compilado.
EP_SUPPORTED_PREFER_RECOMPILATION Há suporte para o modelo compilado, mas o EP recomenda a recompilação para melhorar o desempenho. O modelo pode ser executado, mas uma política de cache somente ideal o recompila.
EP_UNSUPPORTED O modelo compilado não é compatível com os dispositivos EP atuais. Não carregue o modelo compilado. Recompile ou use o modelo original.
EP_NOT_APPLICABLE O EP não forneceu uma determinação de compatibilidade para os dispositivos fornecidos. Esse também é o padrão quando o EP não implementa a validação de compatibilidade. Não trate esse status como evidência de que o cache é compatível. Use o modelo original, a menos que seu aplicativo tenha outra política de validação.

Em uma política de cache somente ideal, trate a ausência de metadados de compatibilidade para o EP preferido como uma perda no cache. Se a avaliação de compatibilidade retornar um erro, use o modelo original para essa execução e não promova um artefato compilado recentemente porque seu aplicativo não pode validá-lo.

Os eventos que podem exigir uma nova entrada de cache incluem:

  • Um novo EP está instalado.
  • O driver de GPU ou NPU é atualizado.
  • O hardware do usuário muda.
  • O modelo ONNX de origem é alterado.
  • Seu aplicativo altera as configurações do ONNX Runtime, do EP ou de compilação usadas para produzir o artefato.

As APIs de compatibilidade validam um artefato compilado existente em relação a dispositivos EP; elas não determinam se esse artefato foi gerado a partir do modelo-fonte atual. Inclua uma versão do modelo de origem ou hash na chave de cache e invalide o cache quando as entradas de compilação forem alteradas.

Se seu aplicativo for distribuído em uma variedade de dispositivos, armazene artefatos compilados em um local de cache local para que cada dispositivo produza e reutilize seu próprio binário.

Verificação de compatibilidade básica

As funções auxiliares a seguir verificam um modelo compilado para um EP. Antes de chamar uma função auxiliar, aplique a mesma EP ou política de dispositivo que você usa para configurar a sessão de inferência. A coleção de dispositivos deve ser não vazia e conter dispositivos do mesmo EP.

static bool IsCompiledModelOptimal(
    OrtEnv ortEnv,
    string compiledModelPath,
    string epName,
    IReadOnlyList<OrtEpDevice> epDevices)
{
    string compatibilityInfo =
        ortEnv.GetCompatibilityInfoFromModel(compiledModelPath, epName);

    return !string.IsNullOrWhiteSpace(compatibilityInfo) &&
        ortEnv.GetModelCompatibilityForEpDevices(
            epDevices,
            compatibilityInfo) ==
        OrtCompiledModelCompatibility.EP_SUPPORTED_OPTIMAL;
}

Use a verificação antes da criação da sessão:

  • Se o resultado atender à política de compatibilidade do aplicativo, use o modelo compilado.
  • Caso contrário, use ou recompile o modelo original.

Os exemplos de ML Windows usam uma política conservadora e aceitam apenas EP_SUPPORTED_OPTIMAL. Seu aplicativo determina como armazenar, atualizar e substituir modelos compilados.

Compilar modelos

Antes de usar um modelo ONNX em uma sessão de inferência, ele geralmente deve ser compilado em uma representação otimizada que pode ser executada com eficiência no hardware subjacente do dispositivo.

A partir do ONNX Runtime 1.22, há novas APIs que encapsulam melhor as etapas de compilação. Mais detalhes estão disponíveis na documentação de compilação do ONNX Runtime (consulte OrtCompileApi struct).

// Prepare compilation options
OrtModelCompilationOptions compileOptions = new(sessionOptions);
compileOptions.SetInputModelPath(modelPath);
compileOptions.SetOutputModelPath(compiledModelPath);

// Compile the model
compileOptions.CompileModel();

Note

A compilação pode levar vários minutos para ser concluída. Para que qualquer interface do usuário permaneça responsiva, considere fazer isso como uma operação em segundo plano em seu aplicativo ou alerte o usuário de que um modelo está sendo preparado.

Consulte também

  • Última atualização em