mlmodel — vad är det, filstruktur och konvertering till mlpackage

Vad är mlmodel?

mlmodel — är ett binärt filformat som Apple presenterade 2017 tillsammans med ramverket Core ML på WWDC 2017. Formatet bygger på Googles serialiseringsteknik protobuf (Protocol Buffers), vilket gav kompakt storlek (modellvikter i Float32) och effektiv inläsning i minnet. En .mlmodel-fil hade filtillägget .mlmodel och MIME-typen application/x-Apple-mlmodel.

Formatets historia

Formatet .mlmodel var det enda Core ML-formatet från 2017 till 2021. Under den tiden konverterades miljontals modeller via coremltools från TensorFlow, Keras, PyTorch, Caffe, scikit-learn och andra bibliotek. Formatets begränsningar blev uppenbara när modellerna blev allt komplexare: protobuf stöder inte smidig versionshantering, metadata lagras i binär form (oläslig i git diff), och att lägga till nya fält krävde ändringar av protobuf-schemat.

Huvudsakliga egenskaper

En mlmodel-fil lagrar modellen i kompakt binär representation. Storleken varierar från tiotals kilobyte (linjär regression) till gigabyte (neurala nätverk med miljontals parametrar). Formatet stöder alla typer av Core ML-modeller: neurala nätverk (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), ensemblem modeller (TreeEnsemble, GradientBoosting), regressioner (LinearRegression, SVM) och pipelines för för-/efterbehandling (OneHotEncoder, FeatureVectorizer).

Strukturen i filen mlmodel

Den interna strukturen i filen .mlmodel bestäms av det protobuf-schema som beskrivs i ramverket CoreML.framework. Huvudsektionerna: modelDescription — beskrivning av modellens in-, utdata och metadata; modelParameters — specifika parametrar för modelltypen (neurala nätverkets vikter, tree ensembles, regressionskoefficienter); preprocessing — konfiguration av förbehandling (skalning, normalisering av bilder); postprocessing — efterbehandling (softmax, argmax, tröskelvärden).

Sektionen modelDescription

Sektionen modelDescription (MLModelDescription) innehåller modellens namn, författare, version, beskrivning, licens samt en detaljerad beskrivning av alla in- och utparametrar: namn, datatyp (Float32, Int32, String, Image), dimension, bildformat (BGR, RGB), valfria begränsningar (värdeintervall). Denna sektion användes av Xcode för att generera en Swift-klass för modellen med typad in- och utdata.

Sektionen modelParameters

Sektionen modelParameters innehåller de faktiska vikterna och parametrarna för den tränade modellen. För neurala nätverk är det en array av lager (NeuralNetworkLayer), där varje lager innehåller typ (convolution, pooling, activation, innerProduct), vikter (weights), bias (bias), parametrar (kernelSize, stride, padding). För ensemblem modeller — beslutsträd och deras noder. För regressioner — koefficienter och intercept. Vikterna lagras i Float32 (4 byte per värde).

Sektionen preprocessing

Sektionen preprocessing beskriver stegen för förbehandling av indata innan de matas in i modellen. Core ML stöder: skalning (Scaler) — normalisering via medelvärde och standardavvikelse; bildtransformering (ImagePreprocessing) — storleksändring, crop, normalisering av färgkanaler, konvertering BGR→RGB; OneHotEncoder — kodning av kategoriska variabler; FeatureVectorizer — sammanfogning av flera variabler till en vektor.

mlmodel vs mlpackage: jämförande analys

mlpackage — är formatet för nästa generation Core ML-modeller, som presenterades på WWDC 2021. Till skillnad från en enda binär .mlmodel-fil är .mlpackage en katalog (paket) med filstruktur: modellens innehåll lagras som läsbara JSON-filer (metadata, lagerkonfiguration) och separata binära filer för vikter. Detta förändrar i grunden synen på lagring, versionshantering och samarbete kring ML-modeller.

Filstrukturen i mlpackage

Paketet .mlpackage innehåller: ModelCI/ — katalog med versionshanterad modellkonfiguration; Data/ — binära viktfiler (SharedWeights.bin); Metadata.json — namn, författare, beskrivning, modellversion, skapandedatum; Model.json — beskrivning av modellarkitektur, in-/utdata, lagertyper; Manifests/ — versionsmanifest för CI/CD. En sådan struktur gör det möjligt att arbeta effektivt med modellen i git: metadata och konfiguration spåras, medan binära vikter kan använda Git LFS.

Hur man konverterar mlmodel till mlpackage

Konvertering av .mlmodel till .mlpackage görs på två sätt: automatiskt vid bygge i Xcode (Xcode konverterar själv .mlmodel till .mlpackage under kompileringen) eller manuellt via coremltools i Python. Manuell konvertering ger mer kontroll och gör det möjligt att uppdatera modellens metadata, lägga till en beskrivning och ange författare. Efter konverteringen sparas modellen i .mlpackage och kan användas i stället för den ursprungliga .mlmodel.

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

Automatisk konvertering i Xcode

När en .mlmodel-fil läggs till i ett Xcode-projekt identifierar systemet automatiskt dess format och vid bygge (build) startar Model Compiler — ett verktyg som översätter .mlmodel till .mlpackage. Den kompilerade .mlpackage placeras i byggkatalogen (DerivedData). Utvecklaren märker inte denna process — alla Core ML API:er arbetar med modellen på ett enhetligt sätt oavsett ursprungsformat. Xcode utfärdar dock en varning när .mlmodel läggs till med rekommendationen att använda .mlpackage.

Kontroll efter konvertering

Efter konverteringen måste man säkerställa att modellen behållit sin noggrannhet. coremltools tillhandahåller verktyget ct.utils.compare_models() för att jämföra förutsägelser från den ursprungliga och den konverterade modellen på samma indata. Tillåten avvikelse — högst 1e-5 för Float32. Om avvikelsen överskrids kan modellen ha haft custom layers eller operationer som inte stöds i det nya formatet.

Bakåtkompatibilitet och stöd

Bakåtkompatibilitet för .mlmodel garanteras på alla aktuella versioner av iOS och macOS. En app som kompileras med Xcode 12 eller nyare får automatiskt .mlpackage-versionen av modellen, även om originalfilen var .mlmodel. Från och med Xcode 15 (2023) meddelade Apple dock att nya modelltyper (dynamiska neurala nätverk, styrd inlärning) endast kommer att finnas i formatet .mlpackage och att .mlmodel inte kommer att få nya funktioner.

Stöd i iOS 18+ och macOS 15+

Från och med iOS 18 och macOS 15 (Sequoia) stöder Core ML inte längre att .mlmodel laddas direkt. Alla .mlmodel-modeller måste först konverteras till .mlpackage, eller så används Xcode Model Compiler för konvertering under bygget. System-API:t MLModel(contentsOf:) kan fortfarande öppna .mlmodel-filer, men bara om de konverterats till .mlpackage i projektets byggfas.

Tidsplan för avslutat stöd

Apple har inte officiellt meddelat något datum för fullständigt borttagande av .mlmodel-stöd, men den historiska kontexten tyder på 3-4 års övergångsperiod. Formatet .mlmodel introducerades 2017, .mlpackage — 2021. Depreceringsvarningar dök upp i Xcode 13 (2021). I analogi med 32-bitarsappar (iOS 11 avslutade stödet) kan man förvänta sig att fullständigt .mlmodel-stöd avslutas i iOS 20-21 (2026-2027).

När mlmodel fortfarande är aktuellt

Trots att formatet föråldras förekommer .mlmodel fortfarande i befintliga projekt och i vissa scenarier. För utvecklare som arbetar med Core ML är det viktigt att förstå när .mlmodel fortfarande är en del av arbetsflödet och hur man korrekt arbetar med det utan att förlora prestanda.

Arv — gamla projekt

Befintliga projekt som startades före 2021 kan innehålla tiotals .mlmodel-modeller som laddats via Swift Package Manager eller direkt i Xcode. Att migrera alla modeller till .mlpackage kan vara tidskrävande, särskilt om modellerna genererats av en gammal version av coremltools (före 5.0). Apple rekommenderar att migrera stegvis, en modell i taget, i samband med nästa funktionsuppdatering.

CI/CD-pipeline med coremltools

Vissa befintliga CI/CD-pipelines använder coremltools version 4.x för automatisk modellkonvertering, som som standard exporterar till .mlmodel. Att uppdatera coremltools till version 5+ ändrar exportformatet till .mlpackage, vilket kan kräva uppdatering av skript och tester. I sådana fall lämnar team ibland tillfälligt exporten till .mlmodel och planerar migreringen till senare.

Bibliotek och Pods

Tredjepartsbibliotek och CocoaPods som publicerades före 2021 kan innehålla modeller i .mlmodel-format. Till exempel bibliotek för ansiktsigenkänning, bildfiltrering eller AR-filter. Utvecklare som använder sådana bibliotek kan fortsätta arbeta med .mlmodel, eftersom Xcode konverterar dem automatiskt vid bygge. Det rekommenderas dock att kontrollera om författaren har släppt en uppdatering med .mlpackage.

Vanliga problem med mlmodel

När man arbetar med det föråldrade formatet .mlmodel stöter utvecklare på flera vanliga problem. Kännedom om dessa problem och deras lösningar gör det möjligt att undvika att förlora tid vid integration av Core ML-modeller i moderna projekt. Låt oss gå igenom de viktigaste.

Xcode-varning om deprecering

När .mlmodel läggs till i Xcode 13+ visas en varning: “'mlmodel' format is deprecated. Use 'mlpackage' instead.” Varningen blockerar inte bygget, men indikerar att en migrering behövs. För att åtgärda varningen konverterar du modellen via coremltools eller uppdaterar verktyget som skapar modellen.

Felet “Model file is not valid”

En .mlmodel-fil som skapats av en gammal version av coremltools (före 3.0) kanske inte kan öppnas på nya enheter med iOS 16+ på grund av ändringar i protobuf-codec:erna. Lösningen — ladda modellen via Python: model = ct.models.MLModel("old.mlmodel"), spara den sedan igen: model.save("fixed.mlmodel"), eller bättre, konvertera direkt till .mlpackage.

Problem med anpassade lager

.mlmodel-modeller som innehåller custom layers (anpassade lager i neurala nätverk) kan inte konverteras direkt till .mlpackage utan ytterligare steg. Du måste först ladda modellen i coremltools, kontrollera vilka lager det nya formatet inte stöder och implementera dem för .mlpackage. Om det anpassade lagret inte är kritiskt kan du försöka ta bort det från modellen.