mlmodel — cos'è, struttura del file e conversione in mlpackage

Cos'è mlmodel?

mlmodel è un formato di file binario presentato da Apple nel 2017 insieme al framework Core ML al WWDC 2017. Il formato si basa sulla tecnologia di serializzazione protobuf (Protocol Buffers) di Google, che garantiva dimensioni compatte (pesi del modello in Float32) e un caricamento efficiente in memoria. Il file .mlmodel aveva estensione .mlmodel e tipo MIME application/x-Apple-mlmodel.

Storia del formato

Il formato .mlmodel è stato l'unico formato Core ML dal 2017 al 2021. Durante questo periodo, milioni di modelli da TensorFlow, Keras, PyTorch, Caffe, scikit-learn e altre librerie sono stati convertiti tramite coremltools. I limiti del formato sono diventati evidenti con l'aumento della complessità dei modelli: protobuf non supporta un versionamento conveniente, i metadati vengono archiviati in forma binaria (illeggibili in git diff) e l'aggiunta di nuovi campi richiedeva modifiche allo schema protobuf.

Caratteristiche principali

Il file mlmodel archivia il modello in una rappresentazione binaria compatta. Le dimensioni variano da decine di kilobyte (regressione lineare) a gigabyte (reti neurali con milioni di parametri). Il formato supporta tutti i tipi di modelli Core ML: reti neurali (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), modelli ensemble (TreeEnsemble, GradientBoosting), regressioni (LinearRegression, SVM) e pipeline di pre/post-elaborazione (OneHotEncoder, FeatureVectorizer).

Struttura del file mlmodel

La struttura interna del file .mlmodel è definita da uno schema protobuf descritto nel framework CoreML.framework. Le sezioni principali sono: modelDescription — descrizione di ingressi, uscite e metadati del modello; modelParameters — parametri specifici del tipo di modello (pesi della rete neurale, tree ensemble, coefficienti di regressione); preprocessing — configurazione della pre-elaborazione (ridimensionamento, normalizzazione delle immagini); postprocessing — post-elaborazione (softmax, argmax, valori di soglia).

Sezione modelDescription

La sezione modelDescription (MLModelDescription) contiene il nome del modello, autore, versione, descrizione, licenza, nonché una descrizione dettagliata di tutti i parametri di ingresso e uscita: nome, tipo di dato (Float32, Int32, String, Image), dimensionalità, formato immagine (BGR, RGB), vincoli opzionali (intervallo di valori). Questa sezione veniva utilizzata da Xcode per generare una classe Swift del modello con ingressi e uscite tipizzati.

Sezione modelParameters

La sezione modelParameters contiene i pesi effettivi e i parametri del modello addestrato. Per le reti neurali, si tratta di un array di layer (NeuralNetworkLayer), ciascuno contenente il tipo (convolution, pooling, activation, innerProduct), pesi, bias e parametri (kernelSize, stride, padding). Per i modelli ensemble — alberi decisionali e i loro nodi. Per le regressioni — coefficienti e intercetta. I pesi sono memorizzati in Float32 (4 byte per valore).

Sezione preprocessing

La sezione preprocessing descrive i passaggi di pre-elaborazione dei dati di ingresso prima di alimentare il modello. Core ML supporta: ridimensionamento (Scaler) — normalizzazione tramite media e deviazione standard; trasformazione delle immagini (ImagePreprocessing) — ridimensionamento, ritaglio, normalizzazione dei canali colore, conversione BGR→RGB; OneHotEncoder — codifica delle caratteristiche categoriali; FeatureVectorizer — combinazione di più caratteristiche in un unico vettore.

mlmodel vs mlpackage: analisi comparativa

mlpackage è un formato di nuova generazione per i modelli Core ML, presentato al WWDC 2021. A differenza del singolo file binario .mlmodel, .mlpackage è una directory (pacchetto) con una struttura di file: il contenuto del modello viene archiviato come file JSON leggibili (metadati, configurazione dei layer) e file binari separati per i pesi. Questo cambia radicalmente l'approccio all'archiviazione, al versionamento e alla collaborazione sui modelli ML.

Struttura dei file di mlpackage

Il pacchetto .mlpackage contiene: ModelCI/ — directory con configurazione versionata del modello; Data/ — file binari dei pesi (SharedWeights.bin); Metadata.json — nome, autore, descrizione, versione del modello, data di creazione; Model.json — descrizione dell'architettura, ingressi/uscite, tipi di layer; Manifests/ — manifesti delle versioni per CI/CD. Questa struttura consente di lavorare efficientemente con il modello in git: i metadati e la configurazione vengono tracciati, mentre i pesi binari possono utilizzare Git LFS.

Come convertire mlmodel in mlpackage

La conversione da .mlmodel a .mlpackage avviene in due modi: automaticamente durante la compilazione in Xcode (Xcode stesso converte .mlmodel in .mlpackage durante la compilazione) o manualmente tramite coremltools in Python. La conversione manuale offre maggiore controllo e consente di aggiornare i metadati del modello, aggiungere una descrizione e impostare l'autore. Dopo la conversione, il modello viene salvato come .mlpackage e può essere utilizzato al posto del .mlmodel originale.

import coremltools as ct

model = ct.models.MLModel(
    "OldModel.mlmodel"
)
model.author = "IT Sectr"
model.short_description = "Converted from mlmodel"
model.version = "2.0"
model.save("NewModel.mlpackage")

Conversione automatica in Xcode

Quando si aggiunge un file .mlmodel a un progetto Xcode, il sistema rileva automaticamente il suo formato e durante la compilazione avvia il Model Compiler — uno strumento che traduce .mlmodel in .mlpackage. Il .mlpackage compilato viene inserito nella directory di compilazione (DerivedData). Lo sviluppatore non nota questo processo — tutte le API Core ML funzionano con il modello in modo uniforme indipendentemente dal formato originale. Tuttavia, Xcode emette un avviso quando si aggiunge .mlmodel con la raccomandazione di utilizzare .mlpackage.

Verifica dopo la conversione

Dopo la conversione, è necessario garantire che il modello abbia mantenuto la precisione. coremltools fornisce l'utilità ct.utils.compare_models() per confrontare le previsioni del modello originale e di quello convertito sugli stessi dati di ingresso. La discrepanza accettabile non supera 1e-5 per Float32. Se la discrepanza supera questa soglia, il modello potrebbe avere layer personalizzati o operazioni non supportati nel nuovo formato.

Retrocompatibilità e supporto

La retrocompatibilità di .mlmodel è garantita su tutte le versioni attuali di iOS e macOS. Un'applicazione compilata con Xcode 12 o successivo riceve automaticamente la versione .mlpackage del modello, anche se il file originale era .mlmodel. Tuttavia, a partire da Xcode 15 (2023), Apple ha annunciato che i nuovi tipi di modelli (reti neurali dinamiche, apprendimento controllato) saranno disponibili solo nel formato .mlpackage e .mlmodel non riceverà nuove funzionalità.

Supporto in iOS 18+ e macOS 15+

A partire da iOS 18 e macOS 15 (Sequoia), Core ML non supporta più il caricamento diretto di .mlmodel. Tutti i modelli .mlmodel devono essere pre-convertiti in .mlpackage, oppure il Xcode Model Compiler verrà utilizzato per la conversione durante la compilazione. L'API di sistema MLModel(contentsOf:) può aprire file .mlmodel solo se vengono convertiti in .mlpackage nella fase di compilazione del progetto.

Cronologia della fine del supporto

Apple non ha annunciato ufficialmente una data per la rimozione completa del supporto a .mlmodel, ma il contesto storico suggerisce un periodo di transizione di 3-4 anni. Il formato .mlmodel è stato introdotto nel 2017, .mlpackage nel 2021. Gli avvisi di deprecazione sono apparsi in Xcode 13 (2021). Per analogia con le applicazioni a 32 bit (iOS 11 ha terminato il supporto), il supporto completo di .mlmodel potrebbe terminare in iOS 20-21 (2026-2027).

Quando mlmodel è ancora rilevante

Nonostante la deprecazione del formato, .mlmodel si trova ancora in progetti esistenti e in alcuni scenari. Gli sviluppatori che lavorano con Core ML devono capire quando .mlmodel fa ancora parte del flusso di lavoro e come interagire correttamente con esso senza perdere prestazioni.

Legacy — progetti vecchi

I progetti esistenti iniziati prima del 2021 possono contenere dozzine di modelli .mlmodel caricati tramite Swift Package Manager o direttamente in Xcode. Migrare tutti i modelli a .mlpackage può essere dispendioso, specialmente se i modelli sono stati generati da una versione precedente di coremltools (prima della 5.0). Apple consiglia una migrazione graduale, un modello alla volta, durante il prossimo aggiornamento funzionale.

Pipeline CI/CD con coremltools

Alcune pipeline CI/CD esistenti utilizzano coremltools versione 4.x per la conversione automatica dei modelli, che per impostazione predefinita esporta in .mlmodel. L'aggiornamento di coremltools alla versione 5+ modifica il formato di esportazione in .mlpackage, il che potrebbe richiedere l'aggiornamento di script e test. In tali casi, i team a volte mantengono temporaneamente l'esportazione in .mlmodel, pianificando la migrazione per una data successiva.

Librerie e Pods

Le librerie e CocoaPods di terze parti pubblicate prima del 2021 possono contenere modelli in formato .mlmodel. Ad esempio, librerie per il riconoscimento facciale, il filtraggio delle immagini o i filtri AR. Gli sviluppatori che utilizzano tali librerie possono continuare a lavorare con .mlmodel poiché Xcode li converte automaticamente durante la compilazione. Tuttavia, si consiglia di verificare se l'autore ha pubblicato un aggiornamento con .mlpackage.

Problemi comuni con mlmodel

Quando si lavora con il formato obsoleto .mlmodel, gli sviluppatori incontrano diversi problemi comuni. Conoscere questi problemi e le loro soluzioni aiuta a evitare perdite di tempo nell'integrazione di modelli Core ML in progetti moderni. Vediamo i principali.

Avviso di deprecazione di Xcode

Quando si aggiunge .mlmodel in Xcode 13+ appare un avviso: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” L'avviso non blocca la compilazione ma indica la necessità di migrazione. Per risolvere l'avviso, convertire il modello tramite coremltools o aggiornare lo strumento di creazione del modello.

Errore “Model file is not valid”

Un file .mlmodel creato con una versione precedente di coremltools (anteriore alla 3.0) potrebbe non aprirsi su nuovi dispositivi con iOS 16+ a causa di modifiche nei codec protobuf. La soluzione è caricare il modello tramite Python: model = ct.models.MLModel(“old.mlmodel”), quindi salvarlo nuovamente: model.save(“fixed.mlmodel”), o meglio ancora convertirlo direttamente in .mlpackage.

Problemi con i layer personalizzati

I modelli .mlmodel contenenti layer personalizzati (layer di rete neurale definiti dall'utente) non possono essere convertiti direttamente in .mlpackage senza passaggi aggiuntivi. È necessario prima caricare il modello in coremltools, verificare quali layer non sono supportati dal nuovo formato e implementarli per .mlpackage. Se il layer personalizzato non è critico, si può provare a rimuoverlo dal modello.