mlmodel — qué es, estructura del archivo y conversión a mlpackage

¿Qué es mlmodel?

mlmodel es un formato de archivo binario presentado por Apple en 2017 junto con el framework Core ML en la WWDC 2017. El formato se basa en la tecnología de serialización protobuf (Protocol Buffers) de Google, lo que garantizaba un tamaño compacto (pesos del modelo en Float32) y una carga eficiente en memoria. El archivo .mlmodel tenía la extensión .mlmodel y el tipo MIME application/x-Apple-mlmodel.

Historia del formato

El formato .mlmodel fue el único formato de Core ML desde 2017 hasta 2021. Durante este tiempo, se convirtieron millones de modelos de TensorFlow, Keras, PyTorch, Caffe, scikit-learn y otras bibliotecas mediante coremltools. Las limitaciones del formato se hicieron evidentes con el aumento de la complejidad de los modelos: protobuf no admite un versionado conveniente, los metadatos se almacenan en forma binaria (ilegibles en git diff), y añadir nuevos campos requería cambios en el esquema protobuf.

Características principales

El archivo mlmodel almacena el modelo en una representación binaria compacta. El tamaño varía desde decenas de kilobytes (regresión lineal) hasta gigabytes (redes neuronales con millones de parámetros). El formato admite todos los tipos de modelos de Core ML: redes neuronales (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), modelos ensemble (TreeEnsemble, GradientBoosting), regresiones (LinearRegression, SVM) y pipelines de pre/postprocesamiento (OneHotEncoder, FeatureVectorizer).

Estructura del archivo mlmodel

La estructura interna del archivo .mlmodel viene definida por un esquema protobuf descrito en el framework CoreML.framework. Las secciones principales son: modelDescription — descripción de las entradas, salidas y metadatos del modelo; modelParameters — parámetros específicos del tipo de modelo (pesos de la red neuronal, tree ensembles, coeficientes de regresión); preprocessing — configuración de preprocesamiento (escalado, normalización de imágenes); postprocessing — postprocesamiento (softmax, argmax, valores umbral).

Sección modelDescription

La sección modelDescription (MLModelDescription) contiene el nombre del modelo, autor, versión, descripción, licencia, así como una descripción detallada de todos los parámetros de entrada y salida: nombre, tipo de dato (Float32, Int32, String, Image), dimensionalidad, formato de imagen (BGR, RGB), restricciones opcionales (rango de valores). Esta sección era utilizada por Xcode para generar una clase Swift del modelo con entradas y salidas tipificadas.

Sección modelParameters

La sección modelParameters contiene los pesos reales y parámetros del modelo entrenado. Para redes neuronales, es un array de capas (NeuralNetworkLayer), cada una con su tipo (convolution, pooling, activation, innerProduct), pesos, sesgos (bias) y parámetros (kernelSize, stride, padding). Para modelos ensemble — árboles de decisión y sus nodos. Para regresiones — coeficientes e intercepto. Los pesos se almacenan en Float32 (4 bytes por valor).

Sección preprocessing

La sección preprocessing describe los pasos de preprocesamiento de los datos de entrada antes de introducirlos en el modelo. Core ML admite: escalado (Scaler) — normalización mediante media y desviación estándar; transformación de imágenes (ImagePreprocessing) — cambio de tamaño, recorte, normalización de canales de color, conversión BGR→RGB; OneHotEncoder — codificación de características categóricas; FeatureVectorizer — combinación de múltiples características en un solo vector.

mlmodel vs mlpackage: análisis comparativo

mlpackage es un formato de nueva generación para modelos Core ML, presentado en la WWDC 2021. A diferencia del archivo binario único .mlmodel, .mlpackage es un directorio (paquete) con estructura de archivos: el contenido del modelo se almacena como archivos JSON legibles (metadatos, configuración de capas) y archivos binarios separados para los pesos. Esto cambia radicalmente el enfoque de almacenamiento, versionado y trabajo colaborativo con modelos ML.

Estructura de archivos de mlpackage

El paquete .mlpackage contiene: ModelCI/ — directorio con configuración versionada del modelo; Data/ — archivos binarios de pesos (SharedWeights.bin); Metadata.json — nombre, autor, descripción, versión del modelo, fecha de creación; Model.json — descripción de la arquitectura, entradas/salidas, tipos de capas; Manifests/ — manifiestos de versiones para CI/CD. Esta estructura permite trabajar eficientemente con el modelo en git: los metadatos y la configuración se rastrean, mientras que los pesos binarios pueden usar Git LFS.

Cómo convertir mlmodel a mlpackage

La conversión de .mlmodel a .mlpackage se realiza de dos maneras: automáticamente durante la compilación en Xcode (Xcode mismo convierte .mlmodel a .mlpackage durante la compilación) o manualmente mediante coremltools en Python. La conversión manual ofrece más control y permite actualizar los metadatos del modelo, añadir una descripción y establecer el autor. Tras la conversión, el modelo se guarda como .mlpackage y puede utilizarse en lugar del .mlmodel original.

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

Conversión automática en Xcode

Al añadir un archivo .mlmodel a un proyecto de Xcode, el sistema detecta automáticamente su formato y durante la compilación ejecuta el Compilador de Modelos — una herramienta que traduce .mlmodel a .mlpackage. El .mlpackage compilado se coloca en el directorio de compilación (DerivedData). El desarrollador no nota este proceso — todas las API de Core ML funcionan con el modelo de manera uniforme independientemente del formato original. Sin embargo, Xcode muestra una advertencia al añadir .mlmodel recomendando usar .mlpackage.

Verificación tras la conversión

Después de la conversión, es necesario asegurarse de que el modelo ha preservado la precisión. coremltools proporciona la utilidad ct.utils.compare_models() para comparar las predicciones del modelo original y el convertido con los mismos datos de entrada. La discrepancia aceptable es de no más de 1e-5 para Float32. Si la discrepancia supera este umbral, es posible que el modelo tuviera capas personalizadas u operaciones no compatibles con el nuevo formato.

Compatibilidad hacia atrás y soporte

La compatibilidad hacia atrás de .mlmodel está garantizada en todas las versiones actuales de iOS y macOS. Una aplicación compilada con Xcode 12 o superior recibe automáticamente la versión .mlpackage del modelo, incluso si el archivo original era .mlmodel. Sin embargo, a partir de Xcode 15 (2023), Apple anunció que los nuevos tipos de modelos (redes neuronales dinámicas, aprendizaje controlado) solo estarán disponibles en formato .mlpackage, y .mlmodel no recibirá nuevas capacidades.

Soporte en iOS 18+ y macOS 15+

A partir de iOS 18 y macOS 15 (Sequoia), Core ML ya no admite la carga directa de .mlmodel. Todos los modelos .mlmodel deben convertirse previamente a .mlpackage, o se utilizará el Compilador de Modelos de Xcode para la conversión durante la compilación. La API del sistema MLModel(contentsOf:) solo puede abrir archivos .mlmodel si se convierten a .mlpackage en la etapa de compilación del proyecto.

Cronología del fin del soporte

Apple no ha anunciado oficialmente una fecha para la eliminación completa del soporte de .mlmodel, pero el contexto histórico sugiere un período de transición de 3 a 4 años. El formato .mlmodel se introdujo en 2017, .mlpackage en 2021. Las advertencias de obsolescencia aparecieron en Xcode 13 (2021). Por analogía con las aplicaciones de 32 bits (iOS 11 dejó de dar soporte), el soporte completo de .mlmodel podría finalizar en iOS 20-21 (2026-2027).

Cuándo sigue siendo relevante mlmodel

A pesar de la obsolescencia del formato, .mlmodel todavía se encuentra en proyectos existentes y en algunos escenarios. Los desarrolladores que trabajan con Core ML deben comprender cuándo .mlmodel sigue siendo parte del flujo de trabajo y cómo interactuar correctamente con él sin perder rendimiento.

Legado — proyectos antiguos

Los proyectos existentes iniciados antes de 2021 pueden contener docenas de modelos .mlmodel cargados mediante Swift Package Manager o directamente en Xcode. Migrar todos los modelos a .mlpackage puede requerir mucho trabajo, especialmente si los modelos fueron generados por una versión antigua de coremltools (anterior a la 5.0). Apple recomienda una migración gradual, un modelo a la vez, durante la próxima actualización de funcionalidad.

Pipeline CI/CD con coremltools

Algunos pipeline CI/CD existentes utilizan coremltools versión 4.x para la conversión automática de modelos, que por defecto exporta a .mlmodel. Actualizar coremltools a la versión 5+ cambia el formato de exportación a .mlpackage, lo que puede requerir la actualización de scripts y pruebas. En tales casos, los equipos a veces mantienen temporalmente la exportación a .mlmodel, planificando la migración para una fecha posterior.

Bibliotecas y Pods

Las bibliotecas y CocoaPods de terceros publicadas antes de 2021 pueden contener modelos en formato .mlmodel. Por ejemplo, bibliotecas para reconocimiento facial, filtrado de imágenes o filtros AR. Los desarrolladores que utilizan dichas bibliotecas pueden seguir trabajando con .mlmodel ya que Xcode los convierte automáticamente durante la compilación. Sin embargo, se recomienda comprobar si el autor ha publicado una actualización con .mlpackage.

Problemas comunes con mlmodel

Al trabajar con el formato obsoleto .mlmodel, los desarrolladores se encuentran con varios problemas comunes. Conocer estos problemas y sus soluciones permite evitar pérdidas de tiempo al integrar modelos Core ML en proyectos modernos. Veamos los principales.

Advertencia de obsolescencia de Xcode

Al añadir .mlmodel en Xcode 13+ aparece una advertencia: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” La advertencia no bloquea la compilación, pero indica la necesidad de migración. Para eliminar la advertencia, convierta el modelo mediante coremltools o actualice la herramienta de creación del modelo.

Error “Model file is not valid”

Un archivo .mlmodel creado con una versión antigua de coremltools (anterior a la 3.0) puede no abrirse en dispositivos nuevos con iOS 16+ debido a cambios en los códecs protobuf. La solución es cargar el modelo mediante Python: model = ct.models.MLModel(“old.mlmodel”), luego guardarlo de nuevo: model.save(“fixed.mlmodel”), o mejor aún, convertirlo directamente a .mlpackage.

Problemas con capas personalizadas

Los modelos .mlmodel que contienen capas personalizadas (capas de red neuronal definidas por el usuario) no se pueden convertir directamente a .mlpackage sin pasos adicionales. Primero debe cargar el modelo en coremltools, comprobar qué capas no son compatibles con el nuevo formato e implementarlas para .mlpackage. Si la capa personalizada no es crítica, puede intentar eliminarla del modelo.