mlmodel — nedir, dosya yapısı ve mlpackage'a dönüştürme

mlmodel nedir?

mlmodel, Apple tarafından 2017 yılında WWDC 2017'de Core ML çerçevesiyle birlikte tanıtılan ikili bir dosya formatıdır. Format, Google'ın protobuf (Protocol Buffers) serileştirme teknolojisine dayanır ve kompakt boyut (Float32 cinsinden model ağırlıkları) ve verimli bellek yüklemesi sağlardı. .mlmodel dosyası .mlmodel uzantısına ve application/x-Apple-mlmodel MIME türüne sahipti.

Formatın tarihçesi

.mlmodel formatı, 2017'den 2021'e kadar tek Core ML formatıydı. Bu süre zarfında, TensorFlow, Keras, PyTorch, Caffe, scikit-learn ve diğer kütüphanelerden milyonlarca model coremltools aracılığıyla dönüştürüldü. Formatın sınırlamaları, model karmaşıklığı arttıkça belirginleşti: protobuf kullanışlı sürümlemeyi desteklemez, meta veriler ikili biçimde saklanır (git diff'te okunamaz) ve yeni alanlar eklemek protobuf şemasında değişiklik gerektiriyordu.

Temel özellikler

mlmodel dosyası, modeli kompakt bir ikili gösterimde saklar. Boyut, onlarca kilobayttan (doğrusal regresyon) gigabaytlara (milyonlarca parametreye sahip sinir ağları) kadar değişir. Format, tüm Core ML model türlerini destekler: sinir ağları (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), topluluk modelleri (TreeEnsemble, GradientBoosting), regresyonlar (LinearRegression, SVM) ve ön/son işleme hatları (OneHotEncoder, FeatureVectorizer).

mlmodel dosyasının yapısı

.mlmodel dosyasının iç yapısı, CoreML.framework çerçevesinde tanımlanan bir protobuf şeması tarafından belirlenir. Ana bölümler şunlardır: modelDescription — modelin girdi, çıktı ve meta veri tanımı; modelParameters — model türüne özgü parametreler (sinir ağı ağırlıkları, ağaç toplulukları, regresyon katsayıları); preprocessing — ön işleme yapılandırması (ölçekleme, görüntü normalizasyonu); postprocessing — son işleme (softmax, argmax, eşik değerleri).

modelDescription bölümü

modelDescription bölümü (MLModelDescription), model adını, yazarı, sürümü, tanımı, lisansı ve tüm girdi ve çıktı parametrelerinin ayrıntılı tanımını içerir: ad, veri türü (Float32, Int32, String, Image), boyut, görüntü formatı (BGR, RGB), isteğe bağlı kısıtlamalar (değer aralığı). Bu bölüm, Xcode tarafından tür belirtilmiş girdiler ve çıktılarla bir Swift model sınıfı oluşturmak için kullanılırdı.

modelParameters bölümü

modelParameters bölümü, eğitilmiş modelin gerçek ağırlıklarını ve parametrelerini içerir. Sinir ağları için bu, her biri tür (convolution, pooling, activation, innerProduct), ağırlıklar, sapma (bias) ve parametreler (kernelSize, stride, padding) içeren katmanlardan (NeuralNetworkLayer) oluşan bir dizidir. Topluluk modelleri için — karar ağaçları ve düğümleri. Regresyonlar için — katsayılar ve kesişim noktası. Ağırlıklar Float32 (değer başına 4 bayt) olarak saklanır.

preprocessing bölümü

preprocessing bölümü, girdi verilerinin modele verilmeden önce ön işleme adımlarını tanımlar. Core ML şunları destekler: ölçekleme (Scaler) — ortalama ve standart sapma yoluyla normalizasyon; görüntü dönüşümü (ImagePreprocessing) — yeniden boyutlandırma, kırpma, renk kanalı normalizasyonu, BGR→RGB dönüşümü; OneHotEncoder — kategorik özelliklerin kodlanması; FeatureVectorizer — birden çok özelliğin tek bir vektörde birleştirilmesi.

mlmodel vs mlpackage: karşılaştırmalı analiz

mlpackage, WWDC 2021'de tanıtılan Core ML modelleri için yeni nesil bir formattır. Tek ikili .mlmodel dosyasının aksine, .mlpackage bir dosya yapısına sahip bir dizindir (paket): model içeriği, okunabilir JSON dosyaları (meta veriler, katman yapılandırması) ve ağırlıklar için ayrı ikili dosyalar olarak saklanır. Bu, depolama, sürümleme ve ML modelleri üzerinde işbirliği yaklaşımını kökten değiştirir.

mlpackage dosya yapısı

.mlpackage paketi şunları içerir: ModelCI/ — sürümlenmiş model yapılandırmasının bulunduğu dizin; Data/ — ikili ağırlık dosyaları (SharedWeights.bin); Metadata.json — ad, yazar, tanım, model sürümü, oluşturma tarihi; Model.json — mimari tanımı, girdiler/çıktılar, katman türleri; Manifests/ — CI/CD için sürüm manifestoları. Bu yapı, git'te modellerle verimli bir şekilde çalışmayı sağlar: meta veriler ve yapılandırma izlenirken, ikili ağırlıklar Git LFS kullanabilir.

mlmodel mlpackage'a nasıl dönüştürülür

.mlmodel'den .mlpackage'a dönüştürme iki şekilde yapılır: Xcode'da derleme sırasında otomatik olarak (Xcode'un kendisi derleme sırasında .mlmodel'i .mlpackage'a dönüştürür) veya Python'da coremltools aracılığıyla manuel olarak. Manuel dönüştürme daha fazla kontrol sağlar ve model meta verilerini güncellemeye, tanım eklemeye ve yazarı ayarlamaya olanak tanır. Dönüştürmeden sonra model .mlpackage olarak kaydedilir ve orijinal .mlmodel yerine kullanılabilir.

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'da otomatik dönüştürme

Bir Xcode projesine .mlmodel dosyası eklendiğinde, sistem otomatik olarak formatını algılar ve derleme sırasında Model Compiler'ı çalıştırır — .mlmodel'i .mlpackage'a çeviren bir araç. Derlenen .mlpackage, derleme dizinine (DerivedData) yerleştirilir. Geliştirici bu süreci fark etmez — tüm Core ML API'leri, orijinal formattan bağımsız olarak modelle tek tip şekilde çalışır. Ancak Xcode, .mlpackage kullanılması önerisiyle .mlmodel eklerken bir uyarı verir.

Dönüştürme sonrası doğrulama

Dönüştürmeden sonra, modelin doğruluğu koruduğundan emin olmak gerekir. coremltools, aynı girdi verilerinde orijinal ve dönüştürülmüş modelin tahminlerini karşılaştırmak için ct.utils.compare_models() yardımcı programını sağlar. Float32 için kabul edilebilir fark 1e-5'i geçmez. Fark bu eşiği aşarsa, modelde yeni formatta desteklenmeyen özel katmanlar veya işlemler olabilir.

Geriye dönük uyumluluk ve destek

.mlmodel'in geriye dönük uyumluluğu, iOS ve macOS'un tüm güncel sürümlerinde sağlanır. Xcode 12 veya daha yenisiyle derlenen bir uygulama, orijinal dosya .mlmodel olsa bile, otomatik olarak modelin .mlpackage sürümünü alır. Ancak, Xcode 15'ten (2023) başlayarak Apple, yeni model türlerinin (dinamik sinir ağları, kontrollü öğrenme) yalnızca .mlpackage formatında kullanılabileceğini ve .mlmodel'in yeni yetenekler almayacağını duyurdu.

iOS 18+ ve macOS 15+'te destek

iOS 18 ve macOS 15'ten (Sequoia) başlayarak Core ML, .mlmodel'in doğrudan yüklenmesini artık desteklemez. Tüm .mlmodel modelleri önceden .mlpackage'a dönüştürülmelidir veya derleme sırasında dönüştürme için Xcode Model Compiler kullanılacaktır. Sistem API'si MLModel(contentsOf:), .mlmodel dosyalarını yalnızca proje derleme aşamasında .mlpackage'a dönüştürülmüşlerse açabilir.

Destek sonu zaman çizelgesi

Apple, .mlmodel desteğinin tamamen kaldırılması için resmi bir tarih açıklamadı, ancak tarihsel bağlam 3-4 yıllık bir geçiş dönemine işaret ediyor. .mlmodel formatı 2017'de tanıtıldı, .mlpackage 2021'de tanıtıldı. Kullanımdan kaldırma uyarıları Xcode 13'te (2021) göründü. 32 bit uygulamalara benzer şekilde (iOS 11 desteği sonlandırdı), .mlmodel'in tam desteği iOS 20-21'de (2026-2027) sona erebilir.

mlmodel ne zaman hala geçerli

Formatın kullanımdan kaldırılmasına rağmen, .mlmodel hala mevcut projelerde ve bazı senaryolarda bulunur. Core ML ile çalışan geliştiriciler, .mlmodel'in ne zaman iş akışının bir parçası olarak kaldığını ve performans kaybı olmadan onunla nasıl doğru şekilde etkileşime gireceklerini anlamalıdır.

Eski — eski projeler

2021'den önce başlatılan mevcut projeler, Swift Package Manager veya doğrudan Xcode aracılığıyla yüklenen düzinelerce .mlmodel modeli içerebilir. Tüm modelleri .mlpackage'a taşımak, özellikle modeller eski bir coremltools sürümü (5.0 öncesi) tarafından oluşturulmuşsa, emek yoğun olabilir. Apple, en yakın işlevsellik güncellemesinde her seferinde bir model olmak üzere kademeli geçiş yapılmasını önerir.

coremltools ile CI/CD hattı

Bazı mevcut CI/CD hatları, varsayılan olarak .mlmodel'e aktaran coremltools sürüm 4.x'i otomatik model dönüştürme için kullanır. coremltools'un 5+ sürümüne güncellenmesi, aktarım formatını .mlpackage olarak değiştirir ve bu da komut dosyalarının ve testlerin güncellenmesini gerektirebilir. Bu gibi durumlarda, ekipler bazen geçişi daha sonraki bir tarihe planlayarak geçici olarak .mlmodel'e aktarmaya devam eder.

Kütüphaneler ve Pods

2021'den önce yayınlanan üçüncü taraf kütüphaneler ve CocoaPod'lar .mlmodel formatında modeller içerebilir. Örneğin, yüz tanıma, görüntü filtreleme veya AR filtreleri için kütüphaneler. Bu tür kütüphaneleri kullanan geliştiriciler, Xcode bunları derleme sırasında otomatik olarak dönüştürdüğü için .mlmodel ile çalışmaya devam edebilir. Ancak, yazarın .mlpackage ile bir güncelleme yayınlayıp yayınlamadığını kontrol etmeniz önerilir.

mlmodel ile ilgili yaygın sorunlar

Kullanımdan kaldırılmış .mlmodel formatıyla çalışırken, geliştiriciler birkaç yaygın sorunla karşılaşır. Bu sorunları ve çözümlerini bilmek, modern projelere Core ML modelleri entegre ederken zaman kaybını önlemeye yardımcı olur. Başlıca sorunlara bakalım.

Xcode kullanımdan kaldırma uyarısı

Xcode 13+'ta .mlmodel eklerken bir uyarı görünür: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” Uyarı, derlemeyi engellemez ancak geçiş gerekliliğini belirtir. Uyarıyı çözmek için, modeli coremltools aracılığıyla dönüştürün veya model oluşturma aracını güncelleyin.

“Model file is not valid” hatası

Eski bir coremltools sürümüyle (3.0 öncesi) oluşturulan .mlmodel dosyası, protobuf codec'lerindeki değişiklikler nedeniyle iOS 16+ yüklü yeni cihazlarda açılmayabilir. Çözüm, modeli Python aracılığıyla yüklemektir: model = ct.models.MLModel(“old.mlmodel”), ardından tekrar kaydetmek: model.save(“fixed.mlmodel”) veya daha iyisi doğrudan .mlpackage'a dönüştürmek.

Özel katman sorunları

Özel katmanlar (kullanıcı tanımlı sinir ağı katmanları) içeren .mlmodel modelleri, ek adımlar olmadan doğrudan .mlpackage'a dönüştürülemez. Önce modeli coremltools'ta yüklemek, yeni formatta hangi katmanların desteklenmediğini kontrol etmek ve bunları .mlpackage için uygulamak gerekir. Özel katman kritik değilse, modelden çıkarmayı deneyebilirsiniz.