mlmodel — was es ist, Dateistruktur und Konvertierung in mlpackage

Was ist mlmodel?

mlmodel ist ein binäres Dateiformat, das von Apple im Jahr 2017 zusammen mit dem Core ML-Framework auf der WWDC 2017 vorgestellt wurde. Das Format basiert auf der protobuf-Serialisierungstechnologie (Protocol Buffers) von Google, die eine kompakte Größe (Modellgewichte in Float32) und effizientes Laden in den Speicher gewährleistete. Die .mlmodel-Datei hatte die Erweiterung .mlmodel und den MIME-Typ application/x-Apple-mlmodel.

Geschichte des Formats

Das .mlmodel-Format war von 2017 bis 2021 das einzige Core ML-Format. In dieser Zeit wurden Millionen von Modellen aus TensorFlow, Keras, PyTorch, Caffe, scikit-learn und anderen Bibliotheken über coremltools konvertiert. Die Grenzen des Formats wurden mit zunehmender Modellkomplexität deutlich: protobuf unterstützt keine praktische Versionierung, Metadaten werden binär gespeichert (in git diff nicht lesbar), und das Hinzufügen neuer Felder erforderte Änderungen am protobuf-Schema.

Wichtige Merkmale

Die mlmodel-Datei speichert das Modell in einer kompakten binären Darstellung. Die Größe reicht von Dutzenden Kilobyte (lineare Regression) bis zu Gigabyte (neuronale Netze mit Millionen von Parametern). Das Format unterstützt alle Core ML-Modelltypen: neuronale Netze (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), Ensemble-Modelle (TreeEnsemble, GradientBoosting), Regressionen (LinearRegression, SVM) sowie Vor- und Nachverarbeitungspipelines (OneHotEncoder, FeatureVectorizer).

Struktur der mlmodel-Datei

Die interne Struktur der .mlmodel-Datei wird durch ein protobuf-Schema definiert, das im CoreML.framework-Framework beschrieben ist. Die Hauptabschnitte sind: modelDescription — Beschreibung der Eingaben, Ausgaben und Metadaten des Modells; modelParameters — spezifische Parameter des Modelltyps (Gewichte neuronaler Netze, Tree-Ensembles, Regressionskoeffizienten); preprocessing — Konfiguration der Vorverarbeitung (Skalierung, Bildnormalisierung); postprocessing — Nachverarbeitung (softmax, argmax, Schwellwerte).

Der modelDescription-Abschnitt

Der modelDescription-Abschnitt (MLModelDescription) enthält den Modellnamen, Autor, Version, Beschreibung, Lizenz sowie eine detaillierte Beschreibung aller Eingabe- und Ausgabeparameter: Name, Datentyp (Float32, Int32, String, Image), Dimensionalität, Bildformat (BGR, RGB), optionale Einschränkungen (Wertebereich). Dieser Abschnitt wurde von Xcode verwendet, um eine Swift-Modellklasse mit typisierten Ein- und Ausgaben zu generieren.

Der modelParameters-Abschnitt

Der modelParameters-Abschnitt enthält die tatsächlichen Gewichte und Parameter des trainierten Modells. Bei neuronalen Netzen handelt es sich um ein Array von Schichten (NeuralNetworkLayer), die jeweils Typ (convolution, pooling, activation, innerProduct), Gewichte, Bias und Parameter (kernelSize, stride, padding) enthalten. Bei Ensemble-Modellen — Entscheidungsbäume und deren Knoten. Bei Regressionen — Koeffizienten und Intercept. Die Gewichte werden in Float32 (4 Byte pro Wert) gespeichert.

Der preprocessing-Abschnitt

Der preprocessing-Abschnitt beschreibt die Schritte zur Vorverarbeitung der Eingabedaten vor der Zuführung zum Modell. Core ML unterstützt: Skalierung (Scaler) — Normalisierung über Mittelwert und Standardabweichung; Bildtransformation (ImagePreprocessing) — Größenänderung, Zuschneiden, Farbkanalnormalisierung, BGR→RGB-Konvertierung; OneHotEncoder — Kodierung kategorialer Merkmale; FeatureVectorizer — Zusammenführen mehrerer Merkmale in einen Vektor.

mlmodel vs mlpackage: Vergleichsanalyse

mlpackage ist ein neues Format für Core ML-Modelle, das auf der WWDC 2021 vorgestellt wurde. Im Gegensatz zur einzelnen binären .mlmodel-Datei ist .mlpackage ein Verzeichnis (Paket) mit einer Dateistruktur: Der Modellinhalt wird als lesbare JSON-Dateien (Metadaten, Schichtkonfiguration) und separate Binärdateien für die Gewichte gespeichert. Dies ändert grundlegend den Ansatz für Speicherung, Versionierung und Zusammenarbeit an ML-Modellen.

Dateistruktur von mlpackage

Das .mlpackage-Paket enthält: ModelCI/ — Verzeichnis mit versionierter Modellkonfiguration; Data/ — binäre Gewichtedateien (SharedWeights.bin); Metadata.json — Name, Autor, Beschreibung, Modellversion, Erstellungsdatum; Model.json — Architekturbeschreibung, Ein-/Ausgaben, Schichttypen; Manifests/ — Versionsmanifeste für CI/CD. Diese Struktur ermöglicht effizientes Arbeiten mit dem Modell in git: Metadaten und Konfiguration werden nachverfolgt, während binäre Gewichte Git LFS verwenden können.

So konvertieren Sie mlmodel in mlpackage

Die Konvertierung von .mlmodel in .mlpackage erfolgt auf zwei Arten: automatisch während des Builds in Xcode (Xcode selbst konvertiert .mlmodel während der Kompilierung in .mlpackage) oder manuell über coremltools in Python. Die manuelle Konvertierung bietet mehr Kontrolle und ermöglicht die Aktualisierung der Modellmetadaten, das Hinzufügen einer Beschreibung und das Festlegen des Autors. Nach der Konvertierung wird das Modell als .mlpackage gespeichert und kann anstelle des ursprünglichen .mlmodel verwendet werden.

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")

Automatische Konvertierung in Xcode

Beim Hinzufügen einer .mlmodel-Datei zu einem Xcode-Projekt erkennt das System automatisch deren Format und startet während des Builds den Model Compiler — ein Tool, das .mlmodel in .mlpackage übersetzt. Das kompilierte .mlpackage wird im Build-Verzeichnis (DerivedData) abgelegt. Der Entwickler bemerkt diesen Vorgang nicht — alle Core ML-APIs arbeiten einheitlich mit dem Modell, unabhängig vom ursprünglichen Format. Allerdings gibt Xcode beim Hinzufügen von .mlmodel eine Warnung mit der Empfehlung aus, .mlpackage zu verwenden.

Überprüfung nach der Konvertierung

Nach der Konvertierung muss sichergestellt werden, dass das Modell die Genauigkeit beibehalten hat. coremltools bietet das Dienstprogramm ct.utils.compare_models() zum Vergleich der Vorhersagen des ursprünglichen und des konvertierten Modells bei identischen Eingabedaten. Die akzeptable Abweichung beträgt nicht mehr als 1e-5 für Float32. Überschreitet die Abweichung diesen Schwellenwert, enthielt das Modell möglicherweise benutzerdefinierte Schichten oder Operationen, die im neuen Format nicht unterstützt werden.

Rückwärtskompatibilität und Support

Die Rückwärtskompatibilität von .mlmodel ist auf allen aktuellen Versionen von iOS und macOS gewährleistet. Eine mit Xcode 12 oder neuer kompilierte Anwendung erhält automatisch die .mlpackage-Version des Modells, selbst wenn die Originaldatei .mlmodel war. Ab Xcode 15 (2023) hat Apple jedoch angekündigt, dass neue Modelltypen (dynamische neuronale Netze, kontrolliertes Lernen) nur im .mlpackage-Format verfügbar sein werden und .mlmodel keine neuen Fähigkeiten erhält.

Support in iOS 18+ und macOS 15+

Ab iOS 18 und macOS 15 (Sequoia) unterstützt Core ML das direkte Laden von .mlmodel nicht mehr. Alle .mlmodel-Modelle müssen vorab in .mlpackage konvertiert werden, oder der Xcode Model Compiler wird zur Konvertierung während des Builds verwendet. Die System-API MLModel(contentsOf:) kann .mlmodel-Dateien nur öffnen, wenn sie in der Build-Phase des Projekts in .mlpackage konvertiert wurden.

Zeitplan für das Support-Ende

Apple hat kein offizielles Datum für die vollständige Einstellung des .mlmodel-Supports bekannt gegeben, aber der historische Kontext deutet auf eine 3- bis 4-jährige Übergangszeit hin. Das .mlmodel-Format wurde 2017 eingeführt, .mlpackage 2021. Veraltungswarnungen erschienen in Xcode 13 (2021). In Analogie zu 32-Bit-Anwendungen (iOS 11 stellte den Support ein) könnte der vollständige Support für .mlmodel in iOS 20-21 (2026-2027) eingestellt werden.

Wann mlmodel noch relevant ist

Trotz der Veraltung des Formats ist .mlmodel immer noch in bestehenden Projekten und einigen Szenarien zu finden. Entwickler, die mit Core ML arbeiten, müssen verstehen, wann .mlmodel weiterhin Teil des Workflows ist und wie man richtig damit interagiert, ohne Leistungseinbußen hinzunehmen.

Legacy — alte Projekte

Bestehende Projekte, die vor 2021 begonnen wurden, können Dutzende von .mlmodel-Modellen enthalten, die über Swift Package Manager oder direkt in Xcode geladen wurden. Die Migration aller Modelle zu .mlpackage kann aufwändig sein, insbesondere wenn die Modelle von einer älteren Version von coremltools (vor 5.0) generiert wurden. Apple empfiehlt eine schrittweise Migration, ein Modell nach dem anderen, beim nächsten Funktionsupdate.

CI/CD-Pipeline mit coremltools

Einige bestehende CI/CD-Pipelines verwenden coremltools Version 4.x zur automatischen Modellkonvertierung, die standardmäßig nach .mlmodel exportiert. Ein Update von coremltools auf Version 5+ ändert das Exportformat zu .mlpackage, was möglicherweise eine Aktualisierung von Skripten und Tests erfordert. In solchen Fällen behalten Teams manchmal vorübergehend den Export nach .mlmodel bei und planen die Migration für ein späteres Datum.

Bibliotheken und Pods

Drittanbieter-Bibliotheken und CocoaPods, die vor 2021 veröffentlicht wurden, können Modelle im .mlmodel-Format enthalten. Zum Beispiel Bibliotheken für Gesichtserkennung, Bildfilterung oder AR-Filter. Entwickler, die solche Bibliotheken verwenden, können weiterhin mit .mlmodel arbeiten, da Xcode sie während des Builds automatisch konvertiert. Es wird jedoch empfohlen zu überprüfen, ob der Autor ein Update mit .mlpackage veröffentlicht hat.

Häufige Probleme mit mlmodel

Bei der Arbeit mit dem veralteten .mlmodel-Format stoßen Entwickler auf mehrere häufige Probleme. Die Kenntnis dieser Probleme und ihrer Lösungen hilft, Zeitverlust bei der Integration von Core ML-Modellen in moderne Projekte zu vermeiden. Sehen wir uns die wichtigsten an.

Xcode-Veraltungswarnung

Beim Hinzufügen von .mlmodel in Xcode 13+ erscheint eine Warnung: „‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.“ Die Warnung blockiert den Build nicht, zeigt aber die Notwendigkeit einer Migration an. Um die Warnung zu beheben, konvertieren Sie das Modell über coremltools oder aktualisieren Sie das Modellerstellungstool.

Fehler „Model file is not valid“

Eine mit einer älteren Version von coremltools (vor 3.0) erstellte .mlmodel-Datei kann auf neuen Geräten mit iOS 16+ aufgrund von Änderungen in den protobuf-Codecs möglicherweise nicht geöffnet werden. Die Lösung besteht darin, das Modell über Python zu laden: model = ct.models.MLModel(„old.mlmodel“), dann erneut zu speichern: model.save(„fixed.mlmodel“), oder besser direkt in .mlpackage zu konvertieren.

Probleme mit benutzerdefinierten Schichten

.mlmodel-Modelle mit benutzerdefinierten Schichten (benutzerdefinierte neuronale Netzschichten) können ohne zusätzliche Schritte nicht direkt in .mlpackage konvertiert werden. Zunächst muss das Modell in coremltools geladen werden, um zu prüfen, welche Schichten vom neuen Format nicht unterstützt werden, und diese für .mlpackage implementieren. Wenn die benutzerdefinierte Schicht nicht kritisch ist, können Sie versuchen, sie aus dem Modell zu entfernen.