mlmodel — o que é, estrutura do arquivo e conversão para mlpackage

O que é mlmodel?

mlmodel é um formato de arquivo binário apresentado pela Apple em 2017 junto com o framework Core ML na WWDC 2017. O formato é baseado na tecnologia de serialização protobuf (Protocol Buffers) do Google, que garantia tamanho compacto (pesos do modelo em Float32) e carregamento eficiente em memória. O arquivo .mlmodel tinha a extensão .mlmodel e o tipo MIME application/x-Apple-mlmodel.

História do formato

O formato .mlmodel foi o único formato Core ML de 2017 a 2021. Durante este período, milhões de modelos do TensorFlow, Keras, PyTorch, Caffe, scikit-learn e outras bibliotecas foram convertidos via coremltools. As limitações do formato tornaram-se evidentes com o aumento da complexidade dos modelos: protobuf não suporta versionamento conveniente, metadados são armazenados em formato binário (ilegíveis em git diff), e adicionar novos campos exigia alterações no esquema protobuf.

Características principais

O arquivo mlmodel armazena o modelo em uma representação binária compacta. O tamanho varia de dezenas de kilobytes (regressão linear) a gigabytes (redes neurais com milhões de parâmetros). O formato suporta todos os tipos de modelos Core ML: redes neurais (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), modelos ensemble (TreeEnsemble, GradientBoosting), regressões (LinearRegression, SVM) e pipelines de pré/pós-processamento (OneHotEncoder, FeatureVectorizer).

Estrutura do arquivo mlmodel

A estrutura interna do arquivo .mlmodel é definida por um esquema protobuf descrito no framework CoreML.framework. As seções principais são: modelDescription — descrição das entradas, saídas e metadados do modelo; modelParameters — parâmetros específicos do tipo de modelo (pesos da rede neural, tree ensembles, coeficientes de regressão); preprocessing — configuração de pré-processamento (escalonamento, normalização de imagens); postprocessing — pós-processamento (softmax, argmax, valores limiares).

Seção modelDescription

A seção modelDescription (MLModelDescription) contém o nome do modelo, autor, versão, descrição, licença, bem como uma descrição detalhada de todos os parâmetros de entrada e saída: nome, tipo de dado (Float32, Int32, String, Image), dimensionalidade, formato de imagem (BGR, RGB), restrições opcionais (faixa de valores). Esta seção era usada pelo Xcode para gerar uma classe Swift do modelo com entradas e saídas tipificadas.

Seção modelParameters

A seção modelParameters contém os pesos reais e parâmetros do modelo treinado. Para redes neurais, é um array de camadas (NeuralNetworkLayer), cada uma com seu tipo (convolution, pooling, activation, innerProduct), pesos, vieses (bias) e parâmetros (kernelSize, stride, padding). Para modelos ensemble — árvores de decisão e seus nós. Para regressões — coeficientes e intercepto. Os pesos são armazenados em Float32 (4 bytes por valor).

Seção preprocessing

A seção preprocessing descreve as etapas de pré-processamento dos dados de entrada antes de alimentar o modelo. Core ML suporta: escalonamento (Scaler) — normalização via média e desvio padrão; transformação de imagens (ImagePreprocessing) — redimensionamento, recorte, normalização de canais de cor, conversão BGR→RGB; OneHotEncoder — codificação de características categóricas; FeatureVectorizer — combinação de múltiplas características em um único vetor.

mlmodel vs mlpackage: análise comparativa

mlpackage é um formato de nova geração para modelos Core ML, apresentado na WWDC 2021. Diferentemente do arquivo binário único .mlmodel, .mlpackage é um diretório (pacote) com estrutura de arquivos: o conteúdo do modelo é armazenado como arquivos JSON legíveis (metadados, configuração de camadas) e arquivos binários separados para os pesos. Isso muda radicalmente a abordagem de armazenamento, versionamento e trabalho colaborativo com modelos ML.

Estrutura de arquivos do mlpackage

O pacote .mlpackage contém: ModelCI/ — diretório com configuração versionada do modelo; Data/ — arquivos binários de pesos (SharedWeights.bin); Metadata.json — nome, autor, descrição, versão do modelo, data de criação; Model.json — descrição da arquitetura, entradas/saídas, tipos de camadas; Manifests/ — manifestos de versões para CI/CD. Essa estrutura permite trabalhar eficientemente com o modelo no git: metadados e configuração são rastreados, enquanto os pesos binários podem usar Git LFS.

Como converter mlmodel para mlpackage

A conversão de .mlmodel para .mlpackage é feita de duas maneiras: automaticamente durante a compilação no Xcode (o próprio Xcode converte .mlmodel para .mlpackage durante a compilação) ou manualmente via coremltools em Python. A conversão manual oferece mais controle e permite atualizar os metadados do modelo, adicionar uma descrição e definir o autor. Após a conversão, o modelo é salvo como .mlpackage e pode ser usado no lugar do .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")

Conversão automática no Xcode

Ao adicionar um arquivo .mlmodel a um projeto Xcode, o sistema detecta automaticamente seu formato e durante a compilação executa o Compilador de Modelos — uma ferramenta que traduz .mlmodel para .mlpackage. O .mlpackage compilado é colocado no diretório de compilação (DerivedData). O desenvolvedor não percebe esse processo — todas as APIs Core ML funcionam com o modelo de forma uniforme independentemente do formato original. No entanto, o Xcode emite um aviso ao adicionar .mlmodel recomendando o uso de .mlpackage.

Verificação após a conversão

Após a conversão, é necessário garantir que o modelo preservou a precisão. O coremltools fornece a utilidade ct.utils.compare_models() para comparar as previsões do modelo original e do convertido com os mesmos dados de entrada. A discrepância aceitável é de no máximo 1e-5 para Float32. Se a discrepância exceder esse limite, o modelo pode ter camadas personalizadas ou operações não suportadas no novo formato.

Compatibilidade retroativa e suporte

A compatibilidade retroativa do .mlmodel é garantida em todas as versões atuais do iOS e macOS. Um aplicativo compilado com Xcode 12 ou superior recebe automaticamente a versão .mlpackage do modelo, mesmo que o arquivo original seja .mlmodel. No entanto, a partir do Xcode 15 (2023), a Apple anunciou que novos tipos de modelos (redes neurais dinâmicas, aprendizado controlado) estarão disponíveis apenas no formato .mlpackage, e o .mlmodel não receberá novas capacidades.

Suporte no iOS 18+ e macOS 15+

A partir do iOS 18 e macOS 15 (Sequoia), o Core ML não suporta mais o carregamento direto de .mlmodel. Todos os modelos .mlmodel devem ser pré-convertidos para .mlpackage, ou o Compilador de Modelos do Xcode será usado para conversão durante a compilação. A API do sistema MLModel(contentsOf:) só pode abrir arquivos .mlmodel se eles forem convertidos para .mlpackage na etapa de compilação do projeto.

Cronograma de fim de suporte

A Apple não anunciou oficialmente uma data para a remoção completa do suporte ao .mlmodel, mas o contexto histórico sugere um período de transição de 3 a 4 anos. O formato .mlmodel foi introduzido em 2017, o .mlpackage em 2021. Avisos de descontinuação apareceram no Xcode 13 (2021). Por analogia com aplicativos de 32 bits (iOS 11 encerrou o suporte), o suporte completo ao .mlmodel pode ser descontinuado no iOS 20-21 (2026-2027).

Quando mlmodel ainda é relevante

Apesar da descontinuação do formato, .mlmodel ainda é encontrado em projetos existentes e em alguns cenários. Desenvolvedores que trabalham com Core ML precisam entender quando o .mlmodel ainda faz parte do fluxo de trabalho e como interagir corretamente com ele sem perder desempenho.

Legado — projetos antigos

Projetos existentes iniciados antes de 2021 podem conter dezenas de modelos .mlmodel carregados via Swift Package Manager ou diretamente no Xcode. Migrar todos os modelos para .mlpackage pode ser trabalhoso, especialmente se os modelos foram gerados por uma versão antiga do coremltools (anterior à 5.0). A Apple recomenda uma migração gradual, um modelo de cada vez, durante a próxima atualização de funcionalidade.

Pipeline CI/CD com coremltools

Alguns pipelines CI/CD existentes usam coremltools versão 4.x para conversão automática de modelos, que por padrão exporta para .mlmodel. Atualizar o coremltools para a versão 5+ altera o formato de exportação para .mlpackage, o que pode exigir a atualização de scripts e testes. Nesses casos, as equipes às vezes mantêm temporariamente a exportação para .mlmodel, planejando a migração para uma data posterior.

Bibliotecas e Pods

Bibliotecas e CocoaPods de terceiros publicadas antes de 2021 podem conter modelos no formato .mlmodel. Por exemplo, bibliotecas para reconhecimento facial, filtragem de imagens ou filtros AR. Desenvolvedores que usam essas bibliotecas podem continuar trabalhando com .mlmodel, pois o Xcode os converte automaticamente durante a compilação. No entanto, recomenda-se verificar se o autor publicou uma atualização com .mlpackage.

Problemas comuns com mlmodel

Ao trabalhar com o formato obsoleto .mlmodel, os desenvolvedores encontram vários problemas comuns. Conhecer esses problemas e suas soluções ajuda a evitar perda de tempo ao integrar modelos Core ML em projetos modernos. Vamos ver os principais.

Aviso de descontinuação do Xcode

Ao adicionar .mlmodel no Xcode 13+ aparece um aviso: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” O aviso não bloqueia a compilação, mas indica a necessidade de migração. Para resolver o aviso, converta o modelo via coremltools ou atualize a ferramenta de criação do modelo.

Erro “Model file is not valid”

Um arquivo .mlmodel criado com uma versão antiga do coremltools (anterior à 3.0) pode não abrir em dispositivos novos com iOS 16+ devido a alterações nos codecs protobuf. A solução é carregar o modelo através do Python: model = ct.models.MLModel(“old.mlmodel”), depois salvá-lo novamente: model.save(“fixed.mlmodel”), ou melhor ainda, convertê-lo diretamente para .mlpackage.

Problemas com camadas personalizadas

Modelos .mlmodel contendo camadas personalizadas (camadas de rede neural definidas pelo usuário) não podem ser convertidos diretamente para .mlpackage sem etapas adicionais. Primeiro, você deve carregar o modelo no coremltools, verificar quais camadas não são suportadas pelo novo formato e implementá-las para .mlpackage. Se a camada personalizada não for crítica, você pode tentar removê-la do modelo.