mlmodel — какво е това, структура на файла и конвертиране в mlpackage

Какво е mlmodel?

mlmodel — е двоичен файлов формат, представен от Apple през 2017 г. заедно с рамката Core ML на WWDC 2017. Форматът се основава на технологията за сериализация protobuf (Protocol Buffers) на Google, което осигуряваше компактен размер (теглата на моделите във Float32) и ефективно зареждане в паметта. Файлът .mlmodel имаше разширение .mlmodel и MIME тип application/x-Apple-mlmodel.

История на формата

Форматът .mlmodel беше единственият формат на Core ML от 2017 до 2021 г. През това време чрез coremltools бяха конвертирани милиони модели от TensorFlow, Keras, PyTorch, Caffe, scikit-learn и други библиотеки. Ограниченията на формата станаха очевидни с нарастването на сложността на моделите: protobuf не поддържа удобно версиониране, метаданните се съхраняват в двоичен вид (нечетими в git diff), а добавянето на нови полета изискваше промяна на protobuf схемата.

Основни характеристики

Файлът mlmodel съхранява модела в компактно двоично представяне. Размерът варира от десетки килобайта (линейна регресия) до гигабайти (невронни мрежи с милиони параметри). Форматът поддържа всички типове модели на Core ML: невронни мрежи (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), ансамблови модели (TreeEnsemble, GradientBoosting), регресии (LinearRegression, SVM) и тръбопроводи за предварителна/последваща обработка (OneHotEncoder, FeatureVectorizer).

Структура на файла mlmodel

Вътрешната структура на файла .mlmodel се определя от protobuf схемата, описана в рамката CoreML.framework. Основните секции: modelDescription — описание на входовете, изходите и метаданните на модела; modelParameters — конкретни параметри на типа на модела (тегла на невронната мрежа, tree ensembles, коефициенти на регресия); preprocessing — конфигурация за предварителна обработка (мащабиране, нормализация на изображения); postprocessing — последваща обработка (softmax, argmax, прагови стойности).

Секция modelDescription

Секцията modelDescription (MLModelDescription) съдържа името на модела, автора, версията, описанието, лиценза, както и подробно описание на всички входни и изходни параметри: име, тип данни (Float32, Int32, String, Image), размерност, формат на изображението (BGR, RGB), незадължителни ограничения (обхват на стойностите). Тази секция се използваше от Xcode за генериране на Swift клас на модела с типизирани входове и изходи.

Секция modelParameters

Секцията modelParameters съдържа действителните тегла и параметри на обучения модел. За невронните мрежи това е масив от слоеве (NeuralNetworkLayer), всеки от които съдържа тип (convolution, pooling, activation, innerProduct), тегла (weights), отмествания (bias), параметри (kernelSize, stride, padding). За ансамбловите модели — дървета на решенията и техните възли. За регресиите — коефициенти и intercept. Теглата се съхраняват във Float32 (4 байта за стойност).

Секция preprocessing

Секцията preprocessing описва стъпките за предварителна обработка на входните данни преди подаването им в модела. Core ML поддържа: мащабиране (Scaler) — нормализация чрез средна стойност и стандартно отклонение; трансформация на изображения (ImagePreprocessing) — промяна на размера, crop, нормализация на цветовите канали, преобразуване BGR→RGB; OneHotEncoder — кодиране на категорийни признаци; FeatureVectorizer — обединяване на няколко признака в един вектор.

mlmodel срещу mlpackage: сравнителен анализ

mlpackage — е форматът от ново поколение за модели на Core ML, представен на WWDC 2021. За разлика от единичния двоичен файл .mlmodel, .mlpackage представлява директория (пакет) с файлова структура: съдържанието на модела се съхранява под формата на четими JSON файлове (метаданни, конфигурация на слоевете) и отделни двоични файлове за теглата. Това коренно променя подхода към съхранението, версионирането и съвместната работа върху ML моделите.

Файлова структура на mlpackage

Пакетът .mlpackage съдържа: ModelCI/ — директория с версионирана конфигурация на модела; Data/ — двоични файлове с теглата (SharedWeights.bin); Metadata.json — име, автор, описание, версия на модела, дата на създаване; Model.json — описание на архитектурата на модела, входовете/изходите, типовете слоеве; Manifests/ — манифести на версиите за CI/CD. Такава структура позволява ефективна работа с модела в git: метаданните и конфигурацията се проследяват, а двоичните тегла могат да използват Git LFS.

Как да конвертирате mlmodel в mlpackage

Конвертирането на .mlmodel в .mlpackage се извършва по два начина: автоматично при изграждане в Xcode (Xcode сам конвертира .mlmodel в .mlpackage по време на компилацията) или ръчно чрез coremltools в Python. Ръчното конвертиране дава повече контрол и позволява актуализиране на метаданните на модела, добавяне на описание и задаване на автор. След конвертирането моделът се съхранява в .mlpackage и може да се използва вместо оригиналния .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")

Автоматично конвертиране в Xcode

При добавяне на файл .mlmodel в проект на Xcode системата автоматично определя неговия формат и при изграждането (build) стартира Model Compiler — инструмент, който трансформира .mlmodel в .mlpackage. Компилираният .mlpackage се поставя в директорията за изграждане (DerivedData). Разработчикът не забелязва този процес — всички API на Core ML работят с модела еднакво, независимо от оригиналния формат. Въпреки това Xcode издава предупреждение при добавяне на .mlmodel с препоръка да използвате .mlpackage.

Проверка след конвертиране

След конвертирането е необходимо да се уверите, че моделът е запазил точността си. coremltools предоставя помощната програма ct.utils.compare_models() за сравняване на прогнозите на оригиналния и конвертирания модел върху еднакви входни данни. Допустимо отклонение — не повече от 1e-5 за Float32. Ако отклонението е превишено, възможно е в модела да е имало custom layers или операции, които новият формат не поддържа.

Обратна съвместимост и поддръжка

Обратната съвместимост на .mlmodel е осигурена на всички актуални версии на iOS и macOS. Приложение, компилирано с Xcode 12 или по-нова версия, автоматично получава .mlpackage версията на модела, дори ако оригиналният файл е бил .mlmodel. Въпреки това, считано от Xcode 15 (2023), Apple обяви, че новите типове модели (динамични невронни мрежи, контролирано обучение) ще бъдат достъпни само във формата .mlpackage, а .mlmodel няма да получава нови възможности.

Поддръжка в iOS 18+ и macOS 15+

Считано от iOS 18 и macOS 15 (Sequoia), Core ML вече не поддържа директно зареждане на .mlmodel. Всички модели .mlmodel трябва предварително да бъдат конвертирани в .mlpackage, или ще бъде използван Xcode Model Compiler за конвертиране по време на изграждането. Системният API MLModel(contentsOf:) все още може да отваря файлове .mlmodel, само ако те са конвертирани в .mlpackage на етапа на изграждане на проекта.

Срокове за прекратяване на поддръжката

Apple не е обявила официално дата за пълно премахване на поддръжката на .mlmodel, но историческият контекст сочи към 3-4 години преходен период. Форматът .mlmodel беше представен през 2017 г., а .mlpackage — през 2021 г. Предупрежденията за остаряване се появиха в Xcode 13 (2021). По аналогия с 32-битовите приложения (iOS 11 прекрати поддръжката) може да се очаква, че пълната поддръжка на .mlmodel ще бъде прекратена в iOS 20-21 (2026-2027).

Кога mlmodel все още е актуален

Въпреки остаряването на формата, .mlmodel все още се среща в съществуващи проекти и в някои сценарии. За разработчиците, работещи с Core ML, е важно да разберат кога .mlmodel остава част от работния процес и как да работят правилно с него без загуба на производителност.

Наследство — стари проекти

Съществуващи проекти, започнати преди 2021 г., могат да съдържат десетки модели .mlmodel, заредени чрез Swift Package Manager или директно в Xcode. Мигрирането на всички модели в .mlpackage може да бъде трудоемко, особено ако моделите са генерирани от стара версия на coremltools (преди 5.0). Apple препоръчва миграцията да се извършва постепенно, по един модел, при най-близкото актуализиране на функционалността.

CI/CD тръбопровод с coremltools

Някои съществуващи CI/CD тръбопроводи използват coremltools версия 4.x за автоматично конвертиране на модели, което по подразбиране експортира в .mlmodel. Актуализирането на coremltools до версия 5+ променя формата на експорт на .mlpackage, което може да наложи актуализиране на скриптовете и тестовете. В такива случаи екипите понякога временно оставят експорта в .mlmodel, планирайки миграцията за по-късно.

Библиотеки и Pods

Библиотеки на трети страни и CocoaPods, публикувани преди 2021 г., могат да съдържат модели във формат .mlmodel. Например библиотеки за разпознаване на лица, филтриране на изображения или AR филтри. Разработчиците, които използват такива библиотеки, могат да продължат да работят с .mlmodel, тъй като Xcode ги конвертира автоматично при изграждане. Въпреки това се препоръчва да проверите дали авторът не е пуснал актуализация с .mlpackage.

Типични проблеми с mlmodel

При работа с остарелия формат .mlmodel разработчиците срещат няколко типични проблема. Познаването на тези проблеми и техните решения позволява да се избегне загубата на време при интегрирането на модели Core ML в съвременни проекти. Нека разгледаме основните.

Предупреждение на Xcode за остаряване

При добавяне на .mlmodel в Xcode 13+ се появява предупреждение: „'mlmodel' format is deprecated. Use 'mlpackage' instead.“ Предупреждението не блокира изграждането, но сочи необходимостта от миграция. За отстраняване на предупреждението конвертирайте модела чрез coremltools или актуализирайте инструмента за създаване на модели.

Грешка „Model file is not valid“

Файл .mlmodel, създаден от стара версия на coremltools (преди 3.0), може да не се отваря на нови устройства с iOS 16+ поради промени в кодеците на protobuf. Решението — заредете модела чрез Python: model = ct.models.MLModel("old.mlmodel"), след което го запазете отново: model.save("fixed.mlmodel"), или по-добре веднага го конвертирайте в .mlpackage.

Проблеми с персонализирани слоеве

Модели .mlmodel, съдържащи custom layers (персонализирани слоеве на невронната мрежа), не подлежат на директно конвертиране в .mlpackage без допълнителни стъпки. Необходимо е първо да заредите модела в coremltools, да проверите кои слоеве не се поддържат от новия формат и да ги реализирате за .mlpackage. Ако персонализираният слой не е критичен, можете да опитате да го премахнете от модела.