mlmodel — co to je, struktura souboru a konverze na mlpackage

Co je mlmodel?

mlmodel — je binární formát souboru, který Apple představil v roce 2017 spolu s frameworkem Core ML na WWDC 2017. Formát je založen na technologii serializace protobuf (Protocol Buffers) od Googlu, což zajišťovalo kompaktní velikost (váhy modelů ve Float32) a efektivní načítání do paměti. Soubor .mlmodel měl příponu .mlmodel a typ MIME application/x-Apple-mlmodel.

Historie formátu

Formát .mlmodel byl jediným formátem Core ML v letech 2017 až 2021. Za tuto dobu bylo přes coremltools převedeno miliony modelů z TensorFlow, Keras, PyTorch, Caffe, scikit-learn a dalších knihoven. Omezení formátu se stala zřejmá s rostoucí složitostí modelů: protobuf nepodporuje pohodlné verzování, metadata jsou uložena v binární podobě (nečitelná v git diff) a přidávání nových polí vyžadovalo změnu schématu protobuf.

Hlavní charakteristiky

Soubor mlmodel ukládá model v kompaktní binární podobě. Velikost se pohybuje od desítek kilobajtů (lineární regrese) po gigabajty (neuronové sítě s miliony parametrů). Formát podporuje všechny typy modelů Core ML: neuronové sítě (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), ensemblové modely (TreeEnsemble, GradientBoosting), regrese (LinearRegression, SVM) a pipeline před/následného zpracování (OneHotEncoder, FeatureVectorizer).

Struktura souboru mlmodel

Vnitřní struktura souboru .mlmodel je určena schématem protobuf popsaným ve frameworku CoreML.framework. Hlavní sekce: modelDescription — popis vstupů, výstupů a metadat modelu; modelParameters — konkrétní parametry typu modelu (váhy neuronové sítě, tree ensembles, koeficienty regrese); preprocessing — konfigurace předzpracování (škálování, normalizace obrazu); postprocessing — následné zpracování (softmax, argmax, prahové hodnoty).

Sekce modelDescription

Sekce modelDescription (MLModelDescription) obsahuje název modelu, autora, verzi, popis, licenci a také podrobný popis všech vstupních a výstupních parametrů: název, typ dat (Float32, Int32, String, Image), rozměr, formát obrazu (BGR, RGB), volitelná omezení (rozsah hodnot). Tato sekce byla používána Xcode pro generování Swift třídy modelu s typovanými vstupy a výstupy.

Sekce modelParameters

Sekce modelParameters obsahuje skutečné váhy a parametry natrénovaného modelu. Pro neuronové sítě je to pole vrstev (NeuralNetworkLayer), z nichž každá obsahuje typ (convolution, pooling, activation, innerProduct), váhy (weights), posuny (bias), parametry (kernelSize, stride, padding). Pro ensemblové modely — rozhodovací stromy a jejich uzly. Pro regrese — koeficienty a intercept. Váhy jsou uloženy ve Float32 (4 bajty na hodnotu).

Sekce preprocessing

Sekce preprocessing popisuje kroky předzpracování vstupních dat před předáním do modelu. Core ML podporuje: škálování (Scaler) — normalizace přes průměr a směrodatnou odchylku; transformaci obrazu (ImagePreprocessing) — změna velikosti, crop, normalizace barevných kanálů, převod BGR→RGB; OneHotEncoder — kódování kategoriálních znaků; FeatureVectorizer — spojení více znaků do jednoho vektoru.

mlmodel vs mlpackage: srovnávací analýza

mlpackage — je formát nové generace pro modely Core ML, představený na WWDC 2021. Na rozdíl od jediného binárního souboru .mlmodel představuje .mlpackage adresář (balíček) se strukturou souborů: obsah modelu je uložen ve formě čitelných JSON souborů (metadata, konfigurace vrstev) a samostatných binárních souborů pro váhy. To zásadně mění přístup k ukládání, verzování a spolupráci na ML modelech.

Struktura souborů mlpackage

Balíček .mlpackage obsahuje: ModelCI/ — adresář s verzovanou konfigurací modelu; Data/ — binární soubory vah (SharedWeights.bin); Metadata.json — název, autor, popis, verze modelu, datum vytvoření; Model.json — popis architektury modelu, vstupů/výstupů, typů vrstev; Manifests/ — manifesty verzí pro CI/CD. Taková struktura umožňuje efektivní práci s modelem v gitu: metadata a konfigurace jsou sledovány, zatímco binární váhy mohou používat Git LFS.

Jak převést mlmodel na mlpackage

Konverze .mlmodel na .mlpackage se provádí dvěma způsoby: automaticky při sestavování v Xcode (Xcode sám převede .mlmodel na .mlpackage během kompilace) nebo ručně přes coremltools v Pythonu. Ruční konverze poskytuje větší kontrolu a umožňuje aktualizovat metadata modelu, přidat popis a nastavit autora. Po konverzi je model uložen do .mlpackage a může být používán místo původního .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")

Automatická konverze v Xcode

Při přidání souboru .mlmodel do projektu Xcode systém automaticky určí jeho formát a při sestavování (build) spustí Model Compiler — nástroj, který převádí .mlmodel na .mlpackage. Zkompilovaný .mlpackage je umístěn do adresáře sestavení (DerivedData). Vývojář tento proces nevnímá — všechny API Core ML pracují s modelem jednotně bez ohledu na původní formát. Xcode však při přidání .mlmodel vydá upozornění s doporučením použít .mlpackage.

Ověření po konverzi

Po konverzi je nutné se ujistit, že model zachoval přesnost. coremltools poskytuje nástroj ct.utils.compare_models() pro porovnání predikcí původního a převedeného modelu na stejných vstupních datech. Přípustná odchylka — ne více než 1e-5 pro Float32. Pokud je odchylka překročena, je možné, že model obsahoval custom layers nebo operace, které nový formát nepodporuje.

Zpětná kompatibilita a podpora

Zpětná kompatibilita .mlmodel je zajištěna na všech aktuálních verzích iOS a macOS. Aplikace zkompilovaná s Xcode 12 nebo novějším automaticky získá verzi .mlpackage modelu, i když původní soubor byl .mlmodel. Avšak od Xcode 15 (2023) Apple oznámil, že nové typy modelů (dynamické neuronové sítě, řízené učení) budou dostupné pouze ve formátu .mlpackage a .mlmodel nedostane nové možnosti.

Podpora v iOS 18+ a macOS 15+

Od iOS 18 a macOS 15 (Sequoia) Core ML již nepodporuje přímé načítání .mlmodel. Všechny modely .mlmodel musí být předem převedeny na .mlpackage, nebo bude použit Xcode Model Compiler pro konverzi během sestavování. Systémové API MLModel(contentsOf:) stále může otevřít soubory .mlmodel, pouze pokud jsou převedeny na .mlpackage ve fázi sestavení projektu.

Termíny ukončení podpory

Apple oficiálně neoznámil datum úplného odstranění podpory .mlmodel, ale historický kontext ukazuje na 3-4 roky přechodného období. Formát .mlmodel byl představen v roce 2017, .mlpackage — v roce 2021. Upozornění o deprekaci se objevila v Xcode 13 (2021). Analogicky s 32bitovými aplikacemi (iOS 11 ukončil podporu) lze očekávat, že plná podpora .mlmodel bude ukončena v iOS 20-21 (2026-2027).

Kdy je mlmodel stále aktuální

Navzdory zastarávání formátu se .mlmodel stále vyskytuje v existujících projektech a některých scénářích. Pro vývojáře pracující s Core ML je důležité pochopit, kdy .mlmodel zůstává součástí pracovního postupu a jak s ním správně pracovat bez ztráty výkonu.

Dědictví — staré projekty

Existující projekty, které začaly před rokem 2021, mohou obsahovat desítky modelů .mlmodel načtených přes Swift Package Manager nebo přímo v Xcode. Migrace všech modelů na .mlpackage může být náročná, zejména pokud byly modely vygenerovány starou verzí coremltools (před 5.0). Apple doporučuje provádět migraci postupně, po jednom modelu, při nejbližší aktualizaci funkcí.

CI/CD pipeline s coremltools

Některé existující CI/CD pipeline používají coremltools verze 4.x pro automatickou konverzi modelů, která ve výchozím nastavení exportuje do .mlmodel. Aktualizace coremltools na verzi 5+ mění formát exportu na .mlpackage, což může vyžadovat aktualizaci skriptů a testů. V takových případech týmy někdy dočasně ponechají export do .mlmodel a plánují migraci na později.

Knihovny a Pods

Knihovny třetích stran a CocoaPods publikované před rokem 2021 mohou obsahovat modely ve formátu .mlmodel. Například knihovny pro rozpoznávání obličejů, filtrování obrázků nebo AR filtry. Vývojáři používající takové knihovny mohou pokračovat v práci s .mlmodel, protože Xcode je automaticky převádí při sestavování. Doporučuje se však zkontrolovat, zda autor nevydal aktualizaci s .mlpackage.

Typické problémy s mlmodel

Při práci se zastaralým formátem .mlmodel se vývojáři setkávají s několika typickými problémy. Znalost těchto problémů a jejich řešení umožňuje vyhnout se ztrátě času při integraci modelů Core ML do moderních projektů. Podívejme se na hlavní.

Upozornění Xcode o deprekaci

Při přidání .mlmodel v Xcode 13+ se objeví upozornění: „'mlmodel' format is deprecated. Use 'mlpackage' instead.“ Upozornění neblokuje sestavení, ale ukazuje na nutnost migrace. K odstranění upozornění převeďte model přes coremltools nebo aktualizujte nástroj pro vytváření modelu.

Chyba „Model file is not valid“

Soubor .mlmodel vytvořený starou verzí coremltools (před 3.0) se nemusí otevřít na nových zařízeních s iOS 16+ kvůli změnám v kodecích protobuf. Řešení — načtěte model přes Python: model = ct.models.MLModel("old.mlmodel"), poté jej znovu uložte: model.save("fixed.mlmodel"), nebo lépe rovnou převeďte na .mlpackage.

Problémy s uživatelskými vrstvami

Modely .mlmodel obsahující custom layers (uživatelské vrstvy neuronové sítě) nejsou přímo převeditelné na .mlpackage bez dalších kroků. Je nutné nejprve načíst model do coremltools, zkontrolovat, které vrstvy nový formát nepodporuje, a implementovat je pro .mlpackage. Pokud uživatelská vrstva není kritická, můžete zkusit ji z modelu odstranit.