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) — зміна розміру, кадрування, нормалізація колірних каналів, переведення BGR→RGB; OneHotEncoder — кодування категоріальних ознак; FeatureVectorizer — об'єднання кількох ознак в один вектор.

mlmodel vs 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. Якщо відхилення перевищено, можливо, у моделі були користувацькі шари або операції, які не підтримуються в новому форматі.

Зворотна сумісність і підтримка

Зворотна сумісність .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 pipeline із 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, що містять користувацькі шари (користувацькі шари нейронної мережі), не піддаються прямій конвертації в .mlpackage без додаткових кроків. Необхідно спочатку завантажити модель в coremltools, перевірити, які шари не підтримуються новим форматом, і реалізувати їх для .mlpackage. Якщо користувацький шар не критичний, можна спробувати видалити його з моделі.