Compilare e memorizzare nella cache i modelli ONNX in Windows ML

La compilazione è il passaggio che trasforma il modello ONNX nel binario specifico per l'hardware che un provider di esecuzione (EP) esegue effettivamente. Su NPU e GPU, quel passaggio può richiedere da pochi secondi a diversi minuti con i modelli di grandi dimensioni e, se l'app non mette in cache il risultato, gli utenti ne pagano il prezzo ogni volta che l'app si avvia.

Questa pagina illustra le operazioni di compilazione, quando precompilare e come convalidare un modello compilato memorizzato nella cache prima di riutilizzarlo.

Prerequisiti

Le API di compatibilità del modello compilate richiedono Windows ML 2.3 o versione successiva. In upstream ONNX Runtime è GetModelCompatibilityForEpDevices() disponibile nella versione 1.23 ed GetCompatibilityInfoFromModel() è disponibile nella versione 1.24.

Due tipi di compilazione

"Compilazione" può significare due cose diverse. Separandoli, il resto di questa pagina risulta più semplice da ragionare:

  • Ottimizzazione del grafo : il lavoro di fusione, riduzione costante e layout eseguito dal runtime ONNX durante la creazione della sessione. È economico, indipendente dall'EP e viene eseguito ogni volta che si crea una sessione.
  • Compilazione EP : conversione del grafico ONNX nel formato di un EP, seguita dalla compilazione in un file binario specifico dell'hardware. Gli EP hardware (QNN, OpenVINO, VitisAI, NvTensorRtRtx, MIGraphX) eseguono questa operazione, ed è il passaggio più costoso. Sulle NPU possono volerci da decine di secondi a minuti per i modelli più grandi.

Windows ML evita di sostenere nuovamente il costo della compilazione EP usando il meccanismo EPContext di ONNX Runtime. La prima compilazione serializza un file binario pronto per l'hardware in un *_ctx.onnx modello (o sidecar .bin). Le sessioni successive caricano il file binario predefinito e ignorano completamente la conversione.

Perché precompilare?

Windows ML consiglia vivamente la pre-compilazione quando si usano provider di esecuzione. La precompilazione trasforma un avvio a freddo di più secondi — a volte di più minuti — in un costo una tantum e consente alla tua app di beneficiare di:

  • Avvio rapido a freddo : i lanci successivi ignorano la conversione del grafo e la compilazione hardware.
  • Comportamento prevedibile : la piattaforma supporta il controllo se un modello compilato è ottimale per i dispositivi selezionati dall'app prima di creare una sessione di inferenza.
  • Uso inferiore della CPU e della batteria : si interrompe la ricompilazione dello stesso grafico a ogni avvio.

Senza pre-compilazione, l'app esegue nuovamente la conversione e la compilazione di EP in ogni creazione di sessione e gli utenti sentono il ritardo ogni volta.

Quando precompilare

Precompila quando la tua app si rivolge a un EP hardware. Sono disponibili due opzioni di temporizzazione:

Strategy Migliore per Trade-offs
Compilazione anticipata (AOT) — compilato in fase di build o di installazione e distribuito come artefatto compilato. Flotta di hardware e driver controllati o programmi di installazione per dispositivo. Richiede strumenti di compilazione incrociata per le destinazioni in cui il computer di compilazione non può essere eseguito. Validare l'artefatto sul dispositivo di destinazione e fornire un meccanismo di fallback per la ricompilazione.
Compilare la prima esecuzione(consigliata per una distribuzione generale): verificare la presenza di un artefatto compilato, compilarlo se mancante, quindi memorizzarlo nella cache e riutilizzarlo. App dello Store e distribuzione generale per i consumatori su un'ampia gamma di hardware. Gli utenti pagano il costo di compilazione una sola volta al primo avvio.

La procedura dettagliata di Windows ML illustra i meccanismi di base di compilazione on-first-run controllando se esiste un artefatto compilato. Non è un esempio completo di gestione della cache. Prima di riutilizzare un modello compilato esistente in un'app, applicare il controllo di compatibilità descritto in questo articolo. Per l'API di compilazione nel contesto, vedere Compilare modelli.

Convalidare un modello compilato prima del riutilizzo

Un modello compilato può dipendere dalla configurazione dell'EP e del dispositivo da cui è stato prodotto. L'EP determina se un modello memorizzato nella cache rimane compatibile e ottimale per un set di dispositivi.

Durante la compilazione, un EP può generare una stringa di compatibilità UTF-8 con terminazione Null che ONNX Runtime scrive nelle proprietà dei metadati del modello compilato. Il formato e il contenuto della stringa sono definiti dall'EP. L'app non deve analizzarla o interpretarla.

La tua app trasmette la stringa e i dispositivi EP di destinazione a GetModelCompatibilityForEpDevices(). ONNX Runtime chiama l'implementazione di validazione della factory dell'EP e restituisce uno stato OrtCompiledModelCompatibility. Per i contratti di origine, vedere GetModelCompatibilityForEpDevices() e ValidateCompiledModelCompatibilityInfo() nel repository onNX Runtime.

Scenari di controllo della compatibilità

È possibile usare la stessa API di convalida in due scenari:

  • Convalidare un modello già presente nel dispositivo. Chiamare GetCompatibilityInfoFromModel() per estrarre la stringa da un file di modello compilato. Se il modello è già in memoria, richiamare GetCompatibilityInfoFromModelBytes(). Passare quindi la stringa a GetModelCompatibilityForEpDevices().
  • Convalidare prima di scaricare un modello compilato. Pubblicare la stringa opaca come metadati leggeri insieme al modello compilato. L'app può recuperare prima la stringa, convalidarla con GetModelCompatibilityForEpDevices()e scaricare il modello potenzialmente di grandi dimensioni solo quando lo stato restituito soddisfa i criteri di cache o distribuzione.

Mantenere i metadati di compatibilità remota associati all'artefatto compilato esatto che lo ha prodotto. Se l'artefatto viene modificato, aggiornare la stringa di compatibilità associata.

In entrambi gli scenari:

  1. Chiamare GetEpDevices() per enumerare i dispositivi EP disponibili, quindi applicare gli stessi criteri ep o dispositivo usati per configurare la sessione di inferenza.
  2. Ottenere la stringa di compatibilità dal modello locale o dai metadati associati a un modello remoto.
  3. Passare la stringa e il gruppo di dispositivi corrispondente a GetModelCompatibilityForEpDevices().
  4. Applica il criterio di cache o di download allo stato restituito. Gli esempi di ml Windows usano criteri conservativi e accettano il modello compilato solo per EP_SUPPORTED_OPTIMAL.

GetCompatibilityInfoFromModel() analizza l'onNX ModelProto completo dal disco. Usare il modello di metadati remoti quando è necessario prendere una decisione di compatibilità prima di scaricare il modello stesso.

Le API restituiscono un OrtCompiledModelCompatibility valore:

Condizione Meaning Azione consigliata
EP_SUPPORTED_OPTIMAL Il modello compilato è supportato e ottimale per i dispositivi EP. Riutilizzare il modello compilato.
EP_SUPPORTED_PREFER_RECOMPILATION Il modello compilato è supportato, ma l'EP consiglia la ricompilazione per ottenere prestazioni migliori. Il modello può essere eseguito, ma un criterio di cache ottimale lo ricompila.
EP_UNSUPPORTED Il modello compilato non è supportato dai dispositivi EP correnti. Non caricare il modello compilato. Ricompilare o usare il modello originale.
EP_NOT_APPLICABLE L'EP non ha fornito una determinazione della compatibilità per i dispositivi forniti. Si tratta anche dell'impostazione predefinita quando l'EP non implementa la convalida della compatibilità. Non considerare questo stato come evidenza che la cache è compatibile. Usa il modello originale a meno che l'app non abbia un altro criterio di convalida.

Con un criterio della cache basato esclusivamente sull’ottimale, considera i metadati di compatibilità mancanti per l’EP preferito come un cache miss. Se la valutazione della compatibilità restituisce un errore, usa il modello originale per quella esecuzione e non promuovere un nuovo artefatto compilato perché l'app non può convalidarlo.

Gli eventi che potrebbero richiedere una nuova voce nella cache includono:

  • Viene installato un nuovo EP.
  • Il driver GPU o NPU viene aggiornato.
  • L'hardware dell'utente cambia.
  • Il modello ONNX di origine cambia.
  • L'app modifica le impostazioni di ONNX Runtime, dell'EP o della compilazione usate per produrre l'artefatto.

Le API di compatibilità convalidano un artefatto compilato esistente nei dispositivi EP; non determinano se l'artefatto è stato prodotto dal modello di origine corrente. Includere una versione del modello di origine o un hash nella chiave della cache e invalidare la cache quando cambiano gli input di compilazione.

Se l'app è distribuita su una gamma di dispositivi, memorizza gli artefatti compilati in un percorso della cache locale, in modo che ogni dispositivo produca e riutilizzi il proprio binario.

Verifica di compatibilità di base

Le funzioni helper seguenti controllano un modello compilato per un EP. Prima di chiamare un helper, applica lo stesso criterio EP o dei dispositivi che utilizzi per configurare la sessione di inferenza. La raccolta di dispositivi deve essere non vuota e contenere dispositivi dello stesso 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;
}

Usa la verifica prima della creazione della sessione:

  • Se il risultato soddisfa i criteri di compatibilità dell'app, usa il modello compilato.
  • In caso contrario, usare o ricompilare il modello originale.

Gli esempi di ml Windows usano criteri conservativi e accettano solo EP_SUPPORTED_OPTIMAL. L'app determina come archiviare, aggiornare e sostituire i modelli compilati.

Compilare modelli

Prima di usare un modello ONNX in una sessione di inferenza, spesso deve essere compilato in una rappresentazione ottimizzata che può essere eseguita in modo efficiente sull'hardware sottostante del dispositivo.

A partire da ONNX Runtime 1.22, sono disponibili nuove API che incapsulano meglio i passaggi di compilazione. Altri dettagli sono disponibili nella documentazione sulla compilazione di ONNX Runtime (vedere struct OrtCompileApi).

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

// Compile the model
compileOptions.CompileModel();

Note

Il completamento della compilazione può richiedere alcuni minuti. In modo che qualsiasi interfaccia utente rimanga reattiva, è consigliabile eseguire questa operazione come operazione in background nell'applicazione o avvisare che l'utente sta preparando un modello.

Vedere anche

  • Ultimo aggiornamento: