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). Програмер не примећује тај процес — сви Core ML API-и раде са моделом једнообразно без обзира на изворни формат. Међутим, 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. Ако прилагођени слој није критичан, можете покушати да га уклоните из модела.