Guida completa all'utilizzo di ONNX Runtime in locale

Se lavori quotidianamente con l'intelligenza artificiale e l'apprendimento automatico, prima o poi ti imbatterai in modelli in formato ONNX e nel motore ONNX Runtime . Questa combinazione è diventata uno dei pilastri per portare i modelli di IA dall'ambiente di laboratorio alle applicazioni reali su Windows, cloud, dispositivi mobili e persino dispositivi edge.

In questa guida, analizzeremo in modo chiaro e conciso come sfruttare ONNX Runtime sia per la modellazione tradizionale che per le applicazioni di LLM/visione artificiale . Spiegherò esattamente di cosa si tratta, come si relaziona con framework come PyTorch e TensorFlow, come integrarlo in applicazioni .NET e WinUI, come sfruttare l'accelerazione GPU, NPU e FPGA e quali sono i casi d'uso pratici più interessanti.

Che cos'è ONNX e cosa risolve ONNX Runtime?

ONNX (Open Neural Network Exchange) è uno standard aperto per la rappresentazione di modelli di intelligenza artificiale, che consente di trasferirli tra diversi framework e hardware senza dover rifare tutto il lavoro. Si può pensare a ONNX come a un "traduttore universale" per le reti neurali : si addestra il modello in PyTorch, lo si esporta in formato ONNX e poi lo si può eseguire in altri ambienti ottimizzati.

Internamente, un modello ONNX è definito come un grafo computazionale statico , in cui ogni nodo rappresenta un'operazione matematica (convoluzione, attivazione, normalizzazione, ecc.) e gli archi rappresentano il flusso dei tensori di dati. Questo grafo utilizza un insieme di operatori standard che diversi motori di esecuzione possono interpretare.

ONNX Runtime è il motore di inferenza ad alte prestazioni progettato per eseguire modelli ONNX . È multipiattaforma, altamente ottimizzato e consente di integrare diversi provider di esecuzione per sfruttare CPU, GPU, NPU, FPGA o altri acceleratori hardware senza dover modificare il codice di inferenza.

In pratica, ONNX Runtime funge da livello di compatibilità e accelerazione : riceve un singolo file .onnx e si occupa di eseguirlo utilizzando l'hardware più performante disponibile, applicando ottimizzazioni come la fusione degli operatori, una gestione efficiente della memoria e il supporto per i modelli quantizzati.

Vantaggi dell'utilizzo di ONNX Runtime in locale

Uno dei principali vantaggi di ONNX Runtime è la possibilità di eseguire i modelli di intelligenza artificiale completamente in locale , senza dipendere dai servizi cloud. Questa soluzione è ideale per scenari in cui privacy, latenza o costi sono fattori critici.

Il primo vantaggio evidente è la privacy: i dati non lasciano mai il dispositivo . Se è necessario elaborare immagini mediche, documenti interni o conversazioni riservate, la possibilità di eseguire il modello sul dispositivo evita l'invio di informazioni a terzi, semplificando la conformità normativa e riducendo i rischi.

Anche l'aspetto economico è degno di nota, poiché non è necessario pagare per i servizi di inferenza nel cloud né preoccuparsi di limiti di utilizzo. Una volta installati il ​​modello e ONNX Runtime, è possibile effettuare un numero illimitato di previsioni sul proprio hardware.

In termini di esperienza utente, la bassa latenza fa la differenza : non dipendendo dalla rete, le risposte del modello sono praticamente istantanee, un aspetto fondamentale nelle applicazioni interattive, nei giochi, negli strumenti di editing o nei sistemi di controllo in tempo reale.

Infine, c'è il fattore controllo: sei tu a decidere come gestire le versioni, aggiornare o sostituire i modelli , senza essere vincolato a un'API esterna. Puoi integrare ONNX Runtime con i tuoi sistemi esistenti in C#, C++, Python o altri linguaggi e automatizzare l'intero ciclo di vita della distribuzione dei modelli.

Modelli ONNX e la loro relazione con i framework di formazione

Un modello di intelligenza artificiale in formato ONNX è una combinazione di struttura di rete, pesi addestrati e una chiara definizione di input e output . La struttura descrive i livelli e le operazioni, i pesi contengono le conoscenze apprese durante l'addestramento e le specifiche di input/output indicano quali formati di dati il ​​modello supporta.

In genere, si addestra il modello in framework come PyTorch, TensorFlow o Keras utilizzando i loro formati nativi (.pt, .pb, .h5, ecc.). Una volta soddisfatti delle prestazioni, si esporta il modello nel formato .onnx utilizzando gli strumenti ufficiali del framework o le librerie ausiliarie.

In termini di interoperabilità, ONNX elimina la necessità di riscrivere o riaddestrare i modelli quando si cambia ambiente . Ad esempio, è possibile addestrare un modello di visione in PyTorch e poi utilizzarlo in un'applicazione mobile grazie a ONNX Runtime for Mobile, oppure integrarlo in un backend C++ senza appesantire l'intero stack Python.

Inoltre, lo standard ONNX include il supporto per operatori quantizzati e diversi set di operatori (opset) , semplificando l'adattamento dello stesso modello a diversi livelli di precisione (ad esempio, passando da float32 a int8) e alle nuove funzionalità hardware man mano che emergono.

Come funzionano ONNX Runtime e i suoi provider di esecuzione

Il cuore di ONNX Runtime è un motore di inferenza ottimizzato che interpreta il grafo ONNX e decide come eseguire ogni operazione nel modo più efficiente possibile. Questo avviene grazie ai provider di esecuzione, ovvero moduli specializzati per diversi tipi di hardware.

Tra i provider più diffusi c'è DirectML su Windows , che consente di sfruttare GPU e NPU tramite un'API unificata. Utilizzando il provider DirectML, la tua applicazione può eseguire lo stesso modello ONNX su un'ampia gamma di schede grafiche e acceleratori integrati senza modifiche al codice.

ONNX Runtime si integra anche con acceleratori specifici come le FPGA Xilinx U250 , tramite librerie come Vitis AI. In questo caso, Microsoft e Xilinx hanno collaborato affinché ONNX Runtime possa eseguire modelli su queste FPGA, sfruttandone appieno le capacità di parallelizzazione.

Un altro elemento chiave è l'integrazione con Windows ML e il catalogo dei provider di esecuzione di Windows . Applicazioni come AI Dev Gallery utilizzano questo catalogo per garantire che i provider certificati siano registrati e pronti, e quindi scelgono automaticamente la migliore combinazione di CPU, GPU o NPU disponibile sul dispositivo.

Infine, ONNX Runtime viene utilizzato anche come backend per ambienti di produzione critici come Bing Semantic Precise Image Search , dove sono richieste prestazioni e stabilità estremamente elevate. In questi scenari, la sua capacità di ottimizzare i grafi e gestire la memoria è fondamentale per gestire milioni di inferenze al giorno.

Crea un'app WinUI in C# che utilizza ONNX Runtime

Un esempio molto efficace di utilizzo di ONNX Runtime su Windows è la creazione di un'applicazione desktop con WinUI 3 in C# che carica un modello di classificazione delle immagini ONNX (come ResNet-50), esegue inferenze accelerate dalla GPU e visualizza i risultati all'utente.

Il primo passo consiste nel preparare l'ambiente di sviluppo: è necessario un dispositivo Windows con la modalità sviluppatore abilitata e Visual Studio 2022 o versioni successive installate con il carico di lavoro "Sviluppo di applicazioni desktop .NET". Questo vi fornirà tutto il necessario per lavorare con i progetti WinUI preconfigurati.

All'interno di Visual Studio, è necessario creare un nuovo progetto di tipo "Applicazione vuota e impacchettata (WinUI 3 su desktop)" utilizzando C# . Un nome comune per questo tipo di esempio potrebbe essere ONNXWinUIExample, anche se è possibile assegnargli il nome che si preferisce, purché la struttura rimanga chiara.

A partire da qui, l'idea è di aggiungere al progetto le dipendenze NuGet che consentono di utilizzare ONNX Runtime, elaborare le immagini e comunicare con DirectX . Questo viene fatto tramite il Gestore pacchetti NuGet nella soluzione, cercando i pacchetti e scegliendo l'ultima versione stabile.

Pacchetti NuGet e configurazione dell'interfaccia

Per questo esempio di classificazione di immagini con accelerazione su Windows, i pacchetti di base da installare sono Microsoft.ML.OnnxRuntime.DirectML, SixLabors.ImageSharp e SharpDX.DXGI . Ciascuno di essi copre una parte specifica del flusso di lavoro.

Il pacchetto Microsoft.ML.OnnxRuntime.DirectML aggiunge il supporto per l'utilizzo di ONNX Runtime con GPU tramite DirectML . Ciò consente di eseguire in modo efficiente i modelli ONNX sull'hardware grafico del dispositivo senza richiedere una gestione di basso livello.

La libreria SixLabors.ImageSharp fornisce utilità avanzate per il caricamento, il ridimensionamento e l'elaborazione delle immagini in .NET . La utilizziamo per trasformare l'immagine selezionata dall'utente nel tensore normalizzato previsto dal modello di classificazione (ad esempio, 224×224 pixel in RGB).

SharpDX.DXGI , dal canto suo, espone le funzionalità DirectX da C# e ci permette di selezionare schede grafiche specifiche (come la prima GPU disponibile) da associare alla sessione di inferenza ONNX Runtime quando configuriamo DirectML come provider di esecuzione.

Una volta installati i pacchetti, si consiglia di aggiungere le direttive `using` corrispondenti al file `MainWindow.xaml.cs` per poter fare riferimento facilmente ai namespace di `OnnxRuntime`, `Tensors`, `SharpDX` e `ImageSharp`. In questo modo, il codice nella finestra principale potrà utilizzare direttamente tutte queste API.

Aggiungi il modello ONNX e crea l'interfaccia semplice

Il passo successivo consiste nell'includere il modello ONNX nel progetto stesso . Una pratica comune è quella di creare una cartella chiamata "model" all'interno del progetto e copiare al suo interno il file .onnx scaricato, ad esempio il modello ResNet50 v2 (resnet50-v2-7.onnx) dal repository ufficiale dei modelli ONNX su GitHub.

In Esplora soluzioni di Visual Studio, è consigliabile configurare la proprietà "Copia nella directory di output" del file modello in modo che venga copiato automaticamente durante la compilazione dell'applicazione. L'opzione "Copia se più recente" è solitamente sufficiente per garantire che il modello sia disponibile insieme al file eseguibile.

L'interfaccia utente per l'esempio può essere molto semplice: un pulsante per selezionare una foto dal disco, un controllo Immagine per visualizzarla e un TextBlock per elencare le previsioni . Il tutto può essere organizzato con una griglia a tre colonne in modo che ogni elemento abbia il proprio spazio.

Nel file MainWindow.xaml, è possibile sostituire lo StackPanel generato dal template iniziale con una Grid a tre colonne: un pulsante nella prima, un'immagine nella seconda e i risultati testuali nella terza . Il pulsante attiverà un evento click che sarà responsabile dell'intero flusso di inferenza.

Per rendere l'esperienza più confortevole, è utile regolare il controllo Immagine per limitare la larghezza massima dell'immagine visualizzata (ad esempio, 300 pixel), in modo che non comprometta il design, e mantenere il TextBlock allineato in alto in modo che l'utente possa leggere le previsioni senza dover scorrere.

Inizializza la sessione ONNX Runtime con DirectML

Una volta definita l'interfaccia, è necessario preparare il motore di inferenza. Nella classe della finestra principale, in genere vengono dichiarati un campo privato di tipo InferenceSession e un percorso base alla cartella del modello . Ciò consente di inizializzare la sessione una sola volta e di riutilizzarla nelle inferenze successive.

La funzione helper InitModel è responsabile della creazione di un'istanza Factory1 di SharpDX per ottenere l'adattatore grafico (di solito il primo, indice 0) e, con tale identificatore di dispositivo, della configurazione di un oggetto ONNX Runtime SessionOptions in cui viene indicato che verrà utilizzato il provider di esecuzione DirectML con tale dispositivo.

Con lo stesso metodo, la InferenceSession viene creata passando il percorso completo del file .onnx e le opzioni di sessione . È anche comune impostare il livello di gravità del log per il debug (ad esempio, ORT_LOGGING_LEVEL_INFO), che aiuta a capire cosa sta succedendo internamente in caso di problemi.

È importante che InitModel verifichi innanzitutto se la sessione esiste già . Se il campo privato _inferenceSession non è nullo, l'inizializzazione non deve essere ripetuta. Questo evita di caricare il modello ripetutamente, risparmiando tempo e risorse, e comportando il costo iniziale solo la prima volta che viene utilizzato.

Con questa struttura, la tua applicazione dispone già di un motore ONNX Runtime configurato per utilizzare DirectML sulla scheda grafica selezionata , pronto a ricevere tensori di input e a restituire output del modello con accelerazione hardware, quando disponibile.

Caricamento e preelaborazione delle immagini con ImageSharp

Il flusso di inferenza in genere inizia dal gestore dell'evento click del pulsante. In questo gestore, viene utilizzato un FileOpenPicker per consentire all'utente di scegliere un'immagine dal file system, limitando le estensioni ai formati comuni come .jpg, .jpeg, .png o .gif.

Una volta selezionata l'immagine, questa può essere visualizzata immediatamente nel controllo Immagine dell'interfaccia utilizzando un oggetto BitmapImage e impostando la sua sorgente sul flusso di file. Ciò consente all'utente di visualizzare l'immagine sulla quale verranno generate le previsioni.

Per preparare l'input del modello, entra in gioco SixLabors.ImageSharp, che consente di aprire l'immagine come Image<Rgb24> e ridimensionarla alle dimensioni previste dal modello , solitamente 224×224 pixel per i modelli di classificazione generale di tipo ResNet.

A questo punto, in genere si applica la modalità Ridimensiona con Ritaglia per adattare l'immagine in modo appropriato , mantenendo le proporzioni e ritagliandola se necessario. L'immagine viene quindi salvata in un flusso di memoria nello stesso formato in cui è stata inizialmente rilevata. Questo passaggio garantisce che tutti i dati di input abbiano le stesse dimensioni.

L'ultimo passaggio della preelaborazione è la normalizzazione: viene creato un DenseTensor<float> con forma (batch di 1, tre canali RGB, altezza e larghezza) e l'immagine viene attraversata riga per riga normalizzando ciascun canale separatamente utilizzando le medie e le deviazioni standard usuali (255* e 255*).

Configurare gli input ed eseguire l'inferenza

Una volta popolato il tensore immagine, è necessario associarlo a un OrtValue affinché ONNX Runtime possa utilizzarlo . Idealmente, questo valore dovrebbe essere creato dalla memoria utilizzando OrtValue.CreateTensorValueFromMemory con il buffer DenseTensor, evitando così ulteriori copie di dati.

Viene creato un dizionario in cui la chiave è il nome della voce del modello (ad esempio, "data") e il valore è il nuovo OrtValue creato. Questo dizionario viene quindi passato alla sessione di inferenza per indicare quali tensori devono essere inseriti nelle voci del grafo.

Prima di avviare l'inferenza, è consigliabile assicurarsi che la sessione sia inizializzata chiamando `InitModel` se non è già stato fatto . Questo garantisce che il modello sia in memoria e configurato con il provider di esecuzione appropriato (DirectML in questo caso).

Per eseguire il modello, viene chiamata la funzione _inferenceSession.Run, passando RunOptions, il dizionario di input e la raccolta dei nomi di output . Il risultato è una raccolta di OrtValue di sola lettura contenenti i tensori di output del modello.

Questo processo incapsula tutta la logica di esecuzione nel runtime ONNX, quindi non devi preoccuparti dei dettagli interni di pianificazione della CPU o della GPU . Il tuo codice rimane relativamente semplice: prepari l'input, chiami Run e raccogli l'output.

Post-elaborazione, softmax e selezione della previsione

L'output di un modello di classificazione è solitamente un vettore di logit, ovvero valori non normalizzati per ogni possibile classe . In questo esempio, i logit vengono ottenuti dal primo OrtValue dei risultati utilizzando GetTensorDataAsSpan<float> e convertendolo in un array per la manipolazione con LINQ.

Per trasformare questi logit in probabilità comprensibili, viene applicata una funzione softmax , che calcola gli esponenziali di ciascun valore e li normalizza in modo che la loro somma sia pari a 1. In questo modo, ogni indice del vettore rappresenta la fiducia del modello nell'appartenenza dell'immagine a quella classe.

Il passo successivo consiste nel confrontare queste probabilità con una LabelMap contenente i nomi umani di ciascuna classe nello stesso ordine utilizzato per addestrare il modello. L'indice dell'array di output deve corrispondere esattamente all'indice dell'etichetta nella LabelMap.

Per presentare le informazioni in modo chiaro all'utente, la raccolta viene solitamente ordinata in base al livello di confidenza decrescente, mantenendo le 10 etichette più probabili . Ciascuna etichetta è rappresentata da un oggetto ausiliario contenente l'etichetta stessa e la relativa probabilità.

Infine, questo elenco di previsioni viene iterato e viene creata una stringa di testo che viene visualizzata nel TextBlock dell'interfaccia , includendo ogni etichetta e il relativo livello di confidenza. Ciò consente all'utente di vedere rapidamente quali oggetti il ​​modello considera più probabili nell'immagine selezionata.

Classi ausiliarie: Prediction e LabelMap

Per gestire i risultati in modo più pulito, viene spesso definita una semplice classe chiamata Prediction, con due proprietà: Label e Confidence . Questa classe viene utilizzata quando si proiettano le probabilità, insieme ai nomi delle classi, su una sequenza di risultati tipizzati.

La proprietà Label può essere di tipo object per una maggiore flessibilità, sebbene in pratica venga solitamente utilizzata come stringa con il nome della categoria restituita dal modello . Confidence è un valore float che memorizza la probabilità calcolata da softmax.

D'altra parte, è necessaria una classe statica LabelMap con un array pubblico di stringhe chiamato Labels . Questo array contiene tutte le etichette utilizzate per addestrare il modello, nell'esatto ordine in cui sono state utilizzate durante l'addestramento e sono codificate nel file ONNX.

Nel caso di modelli di tipo ImageNet, l'elenco dei tag è esteso e di solito include centinaia o migliaia di classi (ad esempio, "tinch", "goldfish", "great white shark", ecc.). È prassi comune prendere questo elenco direttamente dagli esempi presenti nel repository ONNX Runtime per evitare discrepanze negli indici.

Grazie alla combinazione di Prediction e LabelMap, il codice di post-elaborazione risulta notevolmente semplificato : le probabilità vengono iterate, associate alle rispettive etichette e ordinate in base al livello di confidenza, fornendo un risultato finale leggibile e facile da visualizzare nell'interfaccia utente.

ONNX Runtime con LLM nella Galleria di sviluppo AI

Oltre ai modelli di visione, ONNX Runtime supporta anche modelli linguistici di grandi dimensioni (LLM) tramite il formato ONNX Runtime GenAI . Microsoft offre un'applicazione per Windows chiamata AI Dev Gallery, disponibile nel Microsoft Store, che consente di testare in modo interattivo questi modelli LLM ONNX.

L'applicazione include esempi di generazione di testo, chat, riassunto automatico, analisi del sentiment, moderazione dei contenuti e altri scenari , tutti basati su LLM in formato GenAI. È possibile caricare modelli pre-convertiti o convertire i propri da framework comuni.

Attualmente, i modelli supportati per la conversione nel formato ONNX Runtime GenAI includono DeepSeek R1, Distill Qwen 1.5B, Phi 3.5 Mini, Qwen 2.5-1.5B e Llama 3.2 1B , principalmente nelle varianti orientate all'"istruzione" o al "suggerimento". Questi modelli sono particolarmente adatti per attività di chat e generazione di testo locale.

La AI Dev Gallery si integra con l'estensione AI Toolkit per Visual Studio Code , consentendo di avviare lo strumento di conversione direttamente dal selettore del modello. Se non hai installato l'estensione, puoi cercare "AI Toolkit" nel Marketplace di VS Code e, una volta installata, utilizzarla per convertire i tuoi LLM nel formato GenAI.

Dopo aver convertito o scaricato un modello, è sufficiente tornare al selettore di modelli della AI Dev Gallery, scegliere la scheda dei modelli personalizzati e aggiungere il file dal disco . Da lì, è possibile selezionare il proprio LLM negli esempi interattivi e vedere come si comporta in diverse attività di elaborazione del testo.

Integrazione con Microsoft.Extensions.AI e WinML

Al di sotto dell'interfaccia AI Dev Gallery, l'esecuzione di LLM in formato GenAI è gestita dal client OnnxRuntimeGenAIChatClient , che funge da ponte tra ONNX Runtime e le astrazioni di Microsoft.Extensions.AI per la chat.

Questo client è conforme a interfacce come IChatClient e tipi come ChatMessage , quindi il codice che utilizza il modello lavora con messaggi di alto livello anziché con tensori e dettagli di basso livello. Ciò consente alla stessa applicazione di cambiare backend (ad esempio, da un servizio cloud a un modello ONNX locale) con modifiche minime.

Nella classe OnnxRuntimeGenAIChatClientFactory, i provider di esecuzione di Windows ML (WinML) vengono registrati utilizzando ExecutionProviderCatalog.GetDefault e chiamate asincrone per proteggere e registrare i provider certificati prima di creare il client di chat.

Quando viene creato OnnxRuntimeGenAIChatClient, gli vengono passati il ​​percorso del modello ONNX e un modello di prompt (LlmPromptTemplate) che definisce il formato dei ruoli di sistema, utente e assistente, nonché le sequenze di arresto che indicano dove interrompere la generazione del testo.

Con tutto ciò a posto, l'applicazione può ricevere messaggi, chiamare GetStreamingResponseAsync e scaricare in modo incrementale le risposte nell'interfaccia , ottenendo un'esperienza di chat fluida con il modello ONNX locale, sfruttando l'accelerazione hardware disponibile tramite WinML e ONNX Runtime.

Esportare i modelli YOLO su ONNX e distribuirli

Oltre agli esempi di Microsoft, l'ecosistema ONNX è molto diffuso anche in librerie di terze parti come Ultralytics, dove la conversione di un modello YOLO in ONNX richiede solo poche righe di codice . Questo apre la strada all'implementazione dello stesso rilevatore di oggetti su diversi tipi di dispositivi.

Tramite l'API Ultralytics, è possibile caricare un modello YOLO pre-addestrato (ad esempio, yolo11n.pt) ed esportarlo con l'opzione format="onnx" . Il processo converte l'architettura e i pesi nello standard ONNX e genera un file .onnx pronto all'uso.

Una volta ottenuto il modello in ONNX, è possibile integrarlo in applicazioni mobili, web o IoT utilizzando ONNX Runtime e le sue varianti specifiche . Per le applicazioni mobili, ONNX Runtime for Mobile offre una versione semplificata ottimizzata per un minore consumo di risorse, mentre per le applicazioni edge e IoT vengono utilizzate build adattate a dispositivi con memoria limitata.

Negli ambienti industriali, la conversione a ONNX semplifica l'integrazione di modelli di visione artificiale in sistemi legacy C++ o C# senza la necessità di incorporare interpreti Python. Ciò semplifica la manutenzione e riduce i requisiti di implementazione in sistemi in cui ogni dipendenza è importante.

Rispetto all'utilizzo di formati nativi del framework, affidarsi a ONNX riduce le difficoltà nel passaggio dai prototipi di laboratorio alle soluzioni di produzione , poiché evita costose riscritture e consente di sfruttare appieno le ottimizzazioni di ONNX Runtime, TensorRT o altri motori compatibili con il formato.

ONNX Runtime si propone come componente chiave per chi desidera eseguire modelli di intelligenza artificiale in locale, sfruttare l'accelerazione hardware e mantenere la flessibilità tra framework e piattaforme , sia in applicazioni desktop, mobile, cloud o edge.