mlmodel — qu'est-ce que c'est, structure du fichier et conversion en mlpackage

Qu'est-ce que mlmodel ?

mlmodel est un format de fichier binaire présenté par Apple en 2017 avec le framework Core ML à la WWDC 2017. Le format est basé sur la technologie de sérialisation protobuf (Protocol Buffers) de Google, ce qui garantissait une taille compacte (poids du modèle en Float32) et un chargement efficace en mémoire. Le fichier .mlmodel avait l'extension .mlmodel et le type MIME application/x-Apple-mlmodel.

Histoire du format

Le format .mlmodel a été le seul format Core ML de 2017 à 2021. Pendant cette période, des millions de modèles issus de TensorFlow, Keras, PyTorch, Caffe, scikit-learn et d'autres bibliothèques ont été convertis via coremltools. Les limites du format sont devenues évidentes avec la complexité croissante des modèles : protobuf ne prend pas en charge un versionnement pratique, les métadonnées sont stockées sous forme binaire (illisibles dans git diff), et l'ajout de nouveaux champs nécessitait des modifications du schéma protobuf.

Caractéristiques principales

Le fichier mlmodel stocke le modèle dans une représentation binaire compacte. La taille varie de quelques dizaines de kilo-octets (régression linéaire) à des gigaoctets (réseaux neuronaux avec des millions de paramètres). Le format prend en charge tous les types de modèles Core ML : réseaux neuronaux (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), modèles d'ensemble (TreeEnsemble, GradientBoosting), régressions (LinearRegression, SVM) et pipelines de pré/post-traitement (OneHotEncoder, FeatureVectorizer).

Structure du fichier mlmodel

La structure interne du fichier .mlmodel est définie par un schéma protobuf décrit dans le framework CoreML.framework. Les sections principales sont : modelDescription — description des entrées, sorties et métadonnées du modèle ; modelParameters — paramètres spécifiques du type de modèle (poids du réseau neuronal, ensembles d'arbres, coefficients de régression) ; preprocessing — configuration du prétraitement (mise à l'échelle, normalisation d'images) ; postprocessing — post-traitement (softmax, argmax, valeurs de seuil).

Section modelDescription

La section modelDescription (MLModelDescription) contient le nom du modèle, l'auteur, la version, la description, la licence, ainsi qu'une description détaillée de tous les paramètres d'entrée et de sortie : nom, type de données (Float32, Int32, String, Image), dimensionnalité, format d'image (BGR, RGB), contraintes optionnelles (plage de valeurs). Cette section était utilisée par Xcode pour générer une classe Swift du modèle avec des entrées et sorties typées.

Section modelParameters

La section modelParameters contient les poids réels et les paramètres du modèle entraîné. Pour les réseaux neuronaux, il s'agit d'un tableau de couches (NeuralNetworkLayer), chacune contenant le type (convolution, pooling, activation, innerProduct), les poids, les biais et les paramètres (kernelSize, stride, padding). Pour les modèles d'ensemble — arbres de décision et leurs nœuds. Pour les régressions — coefficients et intercept. Les poids sont stockés en Float32 (4 octets par valeur).

Section preprocessing

La section preprocessing décrit les étapes de prétraitement des données d'entrée avant de les fournir au modèle. Core ML prend en charge : la mise à l'échelle (Scaler) — normalisation par la moyenne et l'écart type ; la transformation d'images (ImagePreprocessing) — redimensionnement, recadrage, normalisation des canaux de couleur, conversion BGR→RGB ; OneHotEncoder — encodage des caractéristiques catégorielles ; FeatureVectorizer — combinaison de plusieurs caractéristiques en un seul vecteur.

mlmodel vs mlpackage : analyse comparative

mlpackage est un format de nouvelle génération pour les modèles Core ML, présenté à la WWDC 2021. Contrairement au fichier binaire unique .mlmodel, .mlpackage est un répertoire (package) avec une structure de fichiers : le contenu du modèle est stocké sous forme de fichiers JSON lisibles (métadonnées, configuration des couches) et de fichiers binaires séparés pour les poids. Cela change fondamentalement l'approche du stockage, du versionnement et du travail collaboratif sur les modèles ML.

Structure de fichiers de mlpackage

Le package .mlpackage contient : ModelCI/ — répertoire avec configuration versionnée du modèle ; Data/ — fichiers binaires de poids (SharedWeights.bin) ; Metadata.json — nom, auteur, description, version du modèle, date de création ; Model.json — description de l'architecture, entrées/sorties, types de couches ; Manifests/ — manifestes de versions pour CI/CD. Cette structure permet de travailler efficacement avec le modèle dans git : les métadonnées et la configuration sont suivies, tandis que les poids binaires peuvent utiliser Git LFS.

Comment convertir mlmodel en mlpackage

La conversion de .mlmodel en .mlpackage s'effectue de deux manières : automatiquement lors de la compilation dans Xcode (Xcode lui-même convertit .mlmodel en .mlpackage pendant la compilation) ou manuellement via coremltools en Python. La conversion manuelle offre plus de contrôle et permet de mettre à jour les métadonnées du modèle, d'ajouter une description et de définir l'auteur. Après la conversion, le modèle est enregistré au format .mlpackage et peut être utilisé à la place du .mlmodel d'origine.

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")

Conversion automatique dans Xcode

Lors de l'ajout d'un fichier .mlmodel à un projet Xcode, le système détecte automatiquement son format et pendant la compilation lance le compilateur de modèles — un outil qui traduit .mlmodel en .mlpackage. Le .mlpackage compilé est placé dans le répertoire de compilation (DerivedData). Le développeur ne remarque pas ce processus — toutes les API Core ML fonctionnent avec le modèle de manière uniforme, quel que soit le format d'origine. Cependant, Xcode émet un avertissement lors de l'ajout de .mlmodel recommandant d'utiliser .mlpackage.

Vérification après conversion

Après la conversion, il est nécessaire de s'assurer que le modèle a conservé la précision. coremltools fournit l'utilitaire ct.utils.compare_models() pour comparer les prédictions du modèle original et du modèle converti sur les mêmes données d'entrée. L'écart acceptable est d'au maximum 1e-5 pour Float32. Si l'écart dépasse ce seuil, le modèle peut contenir des couches personnalisées ou des opérations non prises en charge dans le nouveau format.

Rétrocompatibilité et support

La rétrocompatibilité de .mlmodel est assurée sur toutes les versions actuelles d'iOS et macOS. Une application compilée avec Xcode 12 ou plus récent reçoit automatiquement la version .mlpackage du modèle, même si le fichier d'origine était .mlmodel. Cependant, à partir de Xcode 15 (2023), Apple a annoncé que les nouveaux types de modèles (réseaux neuronaux dynamiques, apprentissage contrôlé) ne seront disponibles qu'au format .mlpackage, et .mlmodel ne recevra pas de nouvelles capacités.

Support dans iOS 18+ et macOS 15+

À partir d'iOS 18 et macOS 15 (Sequoia), Core ML ne prend plus en charge le chargement direct de .mlmodel. Tous les modèles .mlmodel doivent être pré-convertis en .mlpackage, ou le compilateur de modèles Xcode sera utilisé pour la conversion lors de la compilation. L'API système MLModel(contentsOf:) ne peut ouvrir les fichiers .mlmodel que s'ils sont convertis en .mlpackage lors de l'étape de compilation du projet.

Calendrier de fin de support

Apple n'a pas officiellement annoncé de date pour la suppression complète du support de .mlmodel, mais le contexte historique suggère une période de transition de 3 à 4 ans. Le format .mlmodel a été introduit en 2017, .mlpackage en 2021. Les avertissements d'obsolescence sont apparus dans Xcode 13 (2021). Par analogie avec les applications 32 bits (iOS 11 a cessé le support), le support complet de .mlmodel pourrait prendre fin dans iOS 20-21 (2026-2027).

Quand mlmodel est encore pertinent

Malgré l'obsolescence du format, .mlmodel se trouve encore dans des projets existants et certains scénarios. Les développeurs travaillant avec Core ML doivent comprendre quand .mlmodel fait encore partie du flux de travail et comment interagir correctement avec lui sans perte de performances.

Héritage — anciens projets

Les projets existants commencés avant 2021 peuvent contenir des dizaines de modèles .mlmodel chargés via Swift Package Manager ou directement dans Xcode. Migrer tous les modèles vers .mlpackage peut être laborieux, surtout si les modèles ont été générés par une ancienne version de coremltools (antérieure à 5.0). Apple recommande une migration progressive, un modèle à la fois, lors de la prochaine mise à jour fonctionnelle.

Pipeline CI/CD avec coremltools

Certains pipelines CI/CD existants utilisent coremltools version 4.x pour la conversion automatique de modèles, qui exporte par défaut en .mlmodel. La mise à jour de coremltools vers la version 5+ modifie le format d'exportation en .mlpackage, ce qui peut nécessiter la mise à jour des scripts et des tests. Dans de tels cas, les équipes conservent parfois temporairement l'exportation en .mlmodel, planifiant la migration pour une date ultérieure.

Bibliothèques et Pods

Les bibliothèques et CocoaPods tierces publiées avant 2021 peuvent contenir des modèles au format .mlmodel. Par exemple, des bibliothèques de reconnaissance faciale, de filtrage d'images ou de filtres AR. Les développeurs utilisant ces bibliothèques peuvent continuer à travailler avec .mlmodel car Xcode les convertit automatiquement lors de la compilation. Cependant, il est recommandé de vérifier si l'auteur a publié une mise à jour avec .mlpackage.

Problèmes courants avec mlmodel

Lorsqu'ils travaillent avec le format obsolète .mlmodel, les développeurs rencontrent plusieurs problèmes courants. Connaître ces problèmes et leurs solutions permet d'éviter des pertes de temps lors de l'intégration de modèles Core ML dans des projets modernes. Voyons les principaux.

Avertissement d'obsolescence de Xcode

Lors de l'ajout de .mlmodel dans Xcode 13+, un avertissement apparaît : «‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.» L'avertissement ne bloque pas la compilation mais indique la nécessité d'une migration. Pour résoudre l'avertissement, convertissez le modèle via coremltools ou mettez à jour l'outil de création du modèle.

Erreur «Model file is not valid»

Un fichier .mlmodel créé avec une ancienne version de coremltools (antérieure à 3.0) peut ne pas s'ouvrir sur les nouveaux appareils sous iOS 16+ en raison de modifications des codecs protobuf. La solution consiste à charger le modèle via Python : model = ct.models.MLModel(«old.mlmodel»), puis à le sauvegarder à nouveau : model.save(«fixed.mlmodel»), ou mieux encore, à le convertir directement en .mlpackage.

Problèmes avec les couches personnalisées

Les modèles .mlmodel contenant des couches personnalisées (couches de réseau neuronal définies par l'utilisateur) ne peuvent pas être convertis directement en .mlpackage sans étapes supplémentaires. Vous devez d'abord charger le modèle dans coremltools, vérifier quelles couches ne sont pas prises en charge par le nouveau format et les implémenter pour .mlpackage. Si la couche personnalisée n'est pas critique, vous pouvez essayer de la supprimer du modèle.