mlmodel — co to jest, struktura pliku i konwersja do mlpackage

Co to jest mlmodel?

mlmodel — to binarny format pliku, przedstawiony przez Apple w 2017 roku wraz z frameworkiem Core ML na WWDC 2017. Format opiera się na technologii serializacji protobuf (Protocol Buffers) od Google, co zapewniało kompaktowy rozmiar (wagi modeli w Float32) i efektywne ładowanie do pamięci. Plik .mlmodel miał rozszerzenie .mlmodel i typ MIME application/x-Apple-mlmodel.

Historia formatu

Format .mlmodel był jedynym formatem Core ML od 2017 do 2021 roku. W tym czasie przez coremltools przekonwertowano miliony modeli z TensorFlow, Keras, PyTorch, Caffe, scikit-learn i innych bibliotek. Ograniczenia formatu stały się oczywiste wraz ze wzrostem złożoności modeli: protobuf nie obsługuje wygodnego wersjonowania, metadane są przechowywane w formacie binarnym (nieczytelne w git diff), a dodawanie nowych pól wymagało zmiany schematu protobuf.

Główne cechy

Plik mlmodel przechowuje model w kompaktowej reprezentacji binarnej. Rozmiar waha się od kilkudziesięciu kilobajtów (regresja liniowa) do gigabajtów (sieci neuronowe z milionami parametrów). Format obsługuje wszystkie typy modeli Core ML: sieci neuronowe (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), modele ensemble (TreeEnsemble, GradientBoosting), regresje (LinearRegression, SVM) i potoki pre/postprocessingu (OneHotEncoder, FeatureVectorizer).

Struktura pliku mlmodel

Wewnętrzna struktura pliku .mlmodel jest określona przez schemat protobuf opisany w frameworku CoreML.framework. Główne sekcje: modelDescription — opis wejść, wyjść i metadanych modelu; modelParameters — konkretne parametry typu modelu (wagi sieci neuronowej, tree ensembles, współczynniki regresji); preprocessing — konfiguracja preprocessingu (skalowanie, normalizacja obrazów); postprocessing — postprocessing (softmax, argmax, wartości progowe).

Sekcja modelDescription

Sekcja modelDescription (MLModelDescription) zawiera nazwę modelu, autora, wersję, opis, licencję, a także szczegółowy opis wszystkich parametrów wejściowych i wyjściowych: nazwę, typ danych (Float32, Int32, String, Image), wymiarowość, format obrazu (BGR, RGB), opcjonalne ograniczenia (zakres wartości). Ta sekcja była używana przez Xcode do generowania klasy Swift modelu z typowanymi wejściami i wyjściami.

Sekcja modelParameters

Sekcja modelParameters zawiera rzeczywiste wagi i parametry wytrenowanego modelu. Dla sieci neuronowych jest to tablica warstw (NeuralNetworkLayer), z których każda zawiera typ (convolution, pooling, activation, innerProduct), wagi (weights), przesunięcia (bias), parametry (kernelSize, stride, padding). Dla modeli ensemble — drzewa decyzyjne i ich węzły. Dla regresji — współczynniki i intercept. Wagi są przechowywane w Float32 (4 bajty na wartość).

Sekcja preprocessing

Sekcja preprocessing opisuje kroki preprocessingu danych wejściowych przed podaniem do modelu. Core ML obsługuje: skalowanie (Scaler) — normalizacja przez średnią i odchylenie standardowe; przekształcanie obrazów (ImagePreprocessing) — zmiana rozmiaru, crop, normalizacja kanałów kolorów, konwersja BGR→RGB; OneHotEncoder — kodowanie cech kategorycznych; FeatureVectorizer — łączenie wielu cech w jeden wektor.

mlmodel vs mlpackage: analiza porównawcza

mlpackage — to format nowej generacji dla modeli Core ML, przedstawiony na WWDC 2021. W przeciwieństwie do pojedynczego pliku binarnego .mlmodel, .mlpackage jest katalogiem (pakietem) o strukturze plikowej: zawartość modelu jest przechowywana w postaci czytelnych plików JSON (metadane, konfiguracja warstw) i oddzielnych plików binarnych dla wag. To radykalnie zmienia podejście do przechowywania, wersjonowania i współpracy nad modelami ML.

Struktura plikowa mlpackage

Pakiet .mlpackage zawiera: ModelCI/ — katalog z wersjonowaną konfiguracją modelu; Data/ — binarne pliki wag (SharedWeights.bin); Metadata.json — nazwa, autor, opis, wersja modelu, data utworzenia; Model.json — opis architektury modelu, wejść/wyjść, typów warstw; Manifests/ — manifesty wersji dla CI/CD. Taka struktura pozwala efektywnie pracować z modelem w git: metadane i konfiguracja są śledzone, a binarne wagi mogą korzystać z Git LFS.

Jak przekonwertować mlmodel na mlpackage

Konwersja .mlmodel na .mlpackage jest wykonywana na dwa sposoby: automatycznie podczas kompilacji w Xcode (Xcode sam konwertuje .mlmodel na .mlpackage w procesie kompilacji) lub ręcznie przez coremltools w Pythonie. Ręczna konwersja daje większą kontrolę i pozwala zaktualizować metadane modelu, dodać opis i ustawić autora. Po konwersji model jest zapisywany w .mlpackage i może być używany zamiast oryginalnego .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")

Automatyczna konwersja w Xcode

Po dodaniu pliku .mlmodel do projektu Xcode system automatycznie określa jego format i podczas kompilacji (build) uruchamia Model Compiler — narzędzie, które transluje .mlmodel na .mlpackage. Skompilowany .mlpackage jest umieszczany w katalogu kompilacji (DerivedData). Deweloper nie zauważa tego procesu — wszystkie API Core ML działają z modelem jednolicie niezależnie od oryginalnego formatu. Jednak Xcode wyświetla ostrzeżenie przy dodawaniu .mlmodel z zaleceniem używania .mlpackage.

Weryfikacja po konwersji

Po konwersji należy upewnić się, że model zachował dokładność. coremltools udostępnia narzędzie ct.utils.compare_models() do porównywania przewidywań oryginalnego i przekonwertowanego modelu na tych samych danych wejściowych. Dopuszczalna różnica — nie więcej niż 1e-5 dla Float32. Jeśli różnica jest większa, możliwe, że model zawierał custom layers lub operacje, które nie są obsługiwane w nowym formacie.

Wsteczna kompatybilność i wsparcie

Wsteczna kompatybilność .mlmodel jest zapewniona na wszystkich aktualnych wersjach iOS i macOS. Aplikacja skompilowana z Xcode 12 lub nowszym automatycznie otrzymuje wersję .mlpackage modelu, nawet jeśli oryginalny plik był .mlmodel. Jednak począwszy od Xcode 15 (2023) Apple ogłosiło, że nowe typy modeli (dynamiczne sieci neuronowe, uczenie nadzorowane) będą dostępne tylko w formacie .mlpackage, a .mlmodel nie będzie otrzymywać nowych funkcji.

Wsparcie w iOS 18+ i macOS 15+

Począwszy od iOS 18 i macOS 15 (Sequoia), Core ML nie obsługuje już bezpośredniego ładowania .mlmodel. Wszystkie modele .mlmodel muszą być wcześniej przekonwertowane na .mlpackage lub zostanie użyty Xcode Model Compiler do konwersji podczas kompilacji. Systemowe API MLModel(contentsOf:) wciąż może otwierać pliki .mlmodel, ale tylko jeśli zostały przekonwertowane na .mlpackage na etapie kompilacji projektu.

Terminy zakończenia wsparcia

Apple oficjalnie nie ogłosiło daty całkowitego usunięcia wsparcia dla .mlmodel, ale kontekst historyczny wskazuje na 3-4 lata okresu przejściowego. Format .mlmodel został przedstawiony w 2017, .mlpackage — w 2021. Ostrzeżenia o deprecjacji pojawiły się w Xcode 13 (2021). Przez analogię do aplikacji 32-bitowych (iOS 11 zakończył wsparcie) można oczekiwać, że pełne wsparcie dla .mlmodel zostanie zakończone w iOS 20-21 (2026-2027).

Kiedy mlmodel jest nadal aktualny

Pomimo przestarzałości formatu, .mlmodel wciąż występuje w istniejących projektach i niektórych scenariuszach. Deweloperzy pracujący z Core ML powinni rozumieć, kiedy .mlmodel pozostaje częścią procesu pracy i jak z nim prawidłowo współdziałać bez utraty wydajności.

Dziedzictwo — stare projekty

Istniejące projekty rozpoczęte przed 2021 rokiem mogą zawierać dziesiątki modeli .mlmodel załadowanych przez Swift Package Manager lub bezpośrednio w Xcode. Migracja wszystkich modeli do .mlpackage może być czasochłonna, szczególnie jeśli modele zostały wygenerowane starszą wersją coremltools (przed 5.0). Apple zaleca przeprowadzanie migracji stopniowo, po jednym modelu, przy najbliższej aktualizacji funkcjonalności.

Pipeline CI/CD z coremltools

Niektóre istniejące pipeline'y CI/CD używają coremltools w wersji 4.x do automatycznej konwersji modeli, która domyślnie eksportuje do .mlmodel. Aktualizacja coremltools do wersji 5+ zmienia format eksportu na .mlpackage, co może wymagać aktualizacji skryptów i testów. W takich przypadkach zespoły czasowo pozostawiają eksport do .mlmodel, planując migrację na późniejszy termin.

Biblioteki i Pods

Biblioteki zewnętrzne i CocoaPods opublikowane przed 2021 rokiem mogą zawierać modele w formacie .mlmodel. Na przykład biblioteki do rozpoznawania twarzy, filtrowania obrazów lub filtrów AR. Deweloperzy korzystający z takich bibliotek mogą nadal pracować z .mlmodel, ponieważ Xcode automatycznie konwertuje je podczas kompilacji. Zaleca się jednak sprawdzenie, czy autor nie wydał aktualizacji z .mlpackage.

Typowe problemy z mlmodel

Podczas pracy z przestarzałym formatem .mlmodel deweloperzy napotykają kilka typowych problemów. Znajomość tych problemów i ich rozwiązań pozwala uniknąć straty czasu przy integracji modeli Core ML w nowoczesnych projektach. Omówmy najważniejsze.

Ostrzeżenie Xcode o deprecjacji

Po dodaniu .mlmodel w Xcode 13+ pojawia się ostrzeżenie: „'mlmodel' format is deprecated. Use 'mlpackage' instead.” Ostrzeżenie nie blokuje kompilacji, ale wskazuje na konieczność migracji. Aby usunąć ostrzeżenie, przekonwertuj model przez coremltools lub zaktualizuj narzędzie do tworzenia modeli.

Błąd „Model file is not valid”

Plik .mlmodel utworzony starszą wersją coremltools (przed 3.0) może nie otwierać się na nowych urządzeniach z iOS 16+ z powodu zmian w kodekach protobuf. Rozwiązanie — załaduj model przez Python: model = ct.models.MLModel(„old.mlmodel”), następnie zapisz go ponownie: model.save(„fixed.mlmodel”), lub lepiej od razu przekonwertuj na .mlpackage.

Problemy z warstwami niestandardowymi

Modele .mlmodel zawierające custom layers (niestandardowe warstwy sieci neuronowej) nie poddają się bezpośredniej konwersji na .mlpackage bez dodatkowych kroków. Należy najpierw załadować model w coremltools, sprawdzić, które warstwy nie są obsługiwane przez nowy format, i zaimplementować je dla .mlpackage. Jeśli niestandardowa warstwa nie jest krytyczna, można spróbować usunąć ją z modelu.