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.

In questa pagina viene illustrato quale compilazione comporta, quando eseguire la pre-compilazione e come Windows ML memorizza nella cache l'artefatto compilato automaticamente.

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 — un'incompatibilità tra driver, SDK o versione EP si manifesta come un errore esplicito INVALID_GRAPH che è possibile gestire, invece di causare rallentamenti non segnalati.
• 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:

La compilazione alla prima esecuzione è l'approccio illustrato nella guida dettagliata a Windows ML. Usa OrtModelCompilationOptions.CompileModel() (disponibile nel runtime ONNX fornito con Windows ML, ORT 1.22 e versioni successive) per produrre un artefatto compilato accanto al tuo modello e riutilizzarlo a ogni esecuzione successiva. Per l'API nel contesto, vedere Compilare modelli.

I modelli compilati sono specifici del dispositivo

Un modello compilato è associato all'EP specifico per cui è stato compilato.

I modelli compilati possono richiedere la ricompilatazione

Gli aggiornamenti ep e gli aggiornamenti dei driver possono causare la mancata validità di un modello compilato in precedenza. È consigliabile che quando cambia la versione di EP o driver, gli sviluppatori testano il modello compilato in precedenza (caricando una sessione di inferenza) e convalidano l'output, altrimenti ricompilano. Pianifica l'invalidazione della cache: intercetta gli errori INVALID_GRAPH della sessione e ricompila per aggiornare l'artefatto memorizzato nella cache. Le cause comuni includono:

• Viene installato un nuovo EP.
• Il driver GPU o NPU viene aggiornato.
• L'hardware dell'utente cambia.

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.

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();

const OrtCompileApi* compileApi = ortApi.GetCompileApi();

// Prepare compilation options
OrtModelCompilationOptions* compileOptions = nullptr;
OrtStatus* status = compileApi->CreateModelCompilationOptionsFromSessionOptions(env, sessionOptions, &compileOptions);
status = compileApi->ModelCompilationOptions_SetInputModelPath(compileOptions, modelPath.c_str());
status = compileApi->ModelCompilationOptions_SetOutputModelPath(compileOptions, compiledModelPath.c_str());

// Compile the model
status = compileApi->CompileModel(env, compileOptions);

// Clean up
compileApi->ReleaseModelCompilationOptions(compileOptions);

import os

input_model_path = "path_to_your_model.onnx"
output_model_path = "path_to_your_compiled_model.onnx"

model_compiler = ort.ModelCompiler(
    options,
    input_model_path,
    embed_compiled_data_into_model=True,
    external_initializers_file_path=None,
)
model_compiler.compile_to_file(output_model_path)
if not os.path.exists(output_model_path):
    # For some EP, there might not be a compilation output.
    # In that case, use the original model directly.
    output_model_path = input_model_path

Vedere anche

• Accelerare i modelli di intelligenza artificiale con Windows ML - Panoramica dei provider di esecuzione e dell'accelerazione hardware
• Guida dettagliata a Windows ML — esempio end-to-end che include la compilazione alla prima esecuzione
• Eseguire modelli ONNX : l'API OrtModelCompilationOptions nel contesto
• Provider di esecuzione di Windows ML — versioni dei provider di esecuzione supportate dalla tua app
• EP Context Design(per gli autori di EP) — l'architettura di ONNX Runtime alla base dell'artefatto *_ctx.onnx