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