mlmodel — apa itu, struktur file dan konversi ke mlpackage

Apa itu mlmodel?

mlmodel — adalah format file biner yang diperkenalkan oleh Apple pada tahun 2017 bersama dengan framework Core ML di WWDC 2017. Format ini didasarkan pada teknologi serialisasi protobuf (Protocol Buffers) dari Google, yang memastikan ukuran yang ringkas (bobot model dalam Float32) dan pemuatan yang efisien ke memori. File .mlmodel memiliki ekstensi .mlmodel dan tipe MIME application/x-Apple-mlmodel.

Sejarah format

Format .mlmodel adalah satu-satunya format Core ML dari tahun 2017 hingga 2021. Selama waktu ini, jutaan model dari TensorFlow, Keras, PyTorch, Caffe, scikit-learn, dan pustaka lainnya dikonversi melalui coremltools. Keterbatasan format menjadi jelas seiring dengan meningkatnya kompleksitas model: protobuf tidak mendukung penomoran versi yang nyaman, metadata disimpan dalam bentuk biner (tidak dapat dibaca di git diff), dan penambahan bidang baru memerlukan perubahan skema protobuf.

Karakteristik utama

File mlmodel menyimpan model dalam representasi biner yang ringkas. Ukurannya bervariasi dari puluhan kilobyte (regresi linear) hingga gigabyte (jaringan saraf dengan jutaan parameter). Format ini mendukung semua jenis model Core ML: jaringan saraf (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), model ensemble (TreeEnsemble, GradientBoosting), regresi (LinearRegression, SVM), dan pipeline pra/pasca-pemrosesan (OneHotEncoder, FeatureVectorizer).

Struktur file mlmodel

Struktur internal file .mlmodel ditentukan oleh skema protobuf yang dijelaskan dalam framework CoreML.framework. Bagian utamanya: modelDescription — deskripsi input, output, dan metadata model; modelParameters — parameter spesifik jenis model (bobot jaringan saraf, tree ensembles, koefisien regresi); preprocessing — konfigurasi pra-pemrosesan (penskalaan, normalisasi gambar); postprocessing — pasca-pemrosesan (softmax, argmax, nilai ambang).

Bagian modelDescription

Bagian modelDescription (MLModelDescription) berisi nama model, penulis, versi, deskripsi, lisensi, serta deskripsi terperinci dari semua parameter input dan output: nama, tipe data (Float32, Int32, String, Image), dimensi, format gambar (BGR, RGB), batasan opsional (rentang nilai). Bagian ini digunakan oleh Xcode untuk menghasilkan kelas Swift model dengan input dan output yang bertipe.

Bagian modelParameters

Bagian modelParameters berisi bobot dan parameter aktual dari model terlatih. Untuk jaringan saraf, ini adalah array lapisan (NeuralNetworkLayer), yang masing-masing berisi tipe (convolution, pooling, activation, innerProduct), bobot (weights), bias (bias), parameter (kernelSize, stride, padding). Untuk model ensemble — pohon keputusan dan simpul-simpulnya. Untuk regresi — koefisien dan intercept. Bobot disimpan dalam Float32 (4 byte per nilai).

Bagian preprocessing

Bagian preprocessing menjelaskan langkah-langkah pra-pemrosesan data input sebelum dikirim ke model. Core ML mendukung: penskalaan (Scaler) — normalisasi melalui rata-rata dan deviasi standar; transformasi gambar (ImagePreprocessing) — perubahan ukuran, crop, normalisasi saluran warna, konversi BGR→RGB; OneHotEncoder — pengodean fitur kategorikal; FeatureVectorizer — penggabungan beberapa fitur menjadi satu vektor.

mlmodel vs mlpackage: analisis perbandingan

mlpackage — adalah format generasi baru untuk model Core ML, diperkenalkan di WWDC 2021. Berbeda dengan file biner tunggal .mlmodel, .mlpackage adalah direktori (paket) dengan struktur file: konten model disimpan dalam bentuk file JSON yang dapat dibaca (metadata, konfigurasi lapisan) dan file biner terpisah untuk bobot. Ini secara fundamental mengubah pendekatan terhadap penyimpanan, penomoran versi, dan kolaborasi pada model ML.

Struktur file mlpackage

Paket .mlpackage berisi: ModelCI/ — direktori dengan konfigurasi model yang diberi versi; Data/ — file biner bobot (SharedWeights.bin); Metadata.json — nama, penulis, deskripsi, versi model, tanggal pembuatan; Model.json — deskripsi arsitektur model, input/output, tipe lapisan; Manifests/ — manifes versi untuk CI/CD. Struktur seperti ini memungkinkan kerja yang efisien dengan model di git: metadata dan konfigurasi dilacak, sedangkan bobot biner dapat menggunakan Git LFS.

Cara mengonversi mlmodel ke mlpackage

Konversi .mlmodel ke .mlpackage dilakukan dengan dua cara: secara otomatis saat membangun di Xcode (Xcode sendiri mengonversi .mlmodel ke .mlpackage selama proses kompilasi) atau secara manual melalui coremltools di Python. Konversi manual memberikan kontrol yang lebih besar dan memungkinkan pembaruan metadata model, menambahkan deskripsi, dan menetapkan penulis. Setelah konversi, model disimpan dalam .mlpackage dan dapat digunakan sebagai pengganti .mlmodel asli.

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

Konversi otomatis di Xcode

Saat menambahkan file .mlmodel ke proyek Xcode, sistem secara otomatis menentukan formatnya dan saat membangun (build) menjalankan Model Compiler — alat yang menerjemahkan .mlmodel ke .mlpackage. .mlpackage yang dikompilasi ditempatkan ke direktori build (DerivedData). Pengembang tidak menyadari proses ini — semua API Core ML bekerja dengan model secara seragam terlepas dari format aslinya. Namun, Xcode mengeluarkan peringatan saat menambahkan .mlmodel dengan rekomendasi untuk menggunakan .mlpackage.

Verifikasi setelah konversi

Setelah konversi, perlu memastikan bahwa model mempertahankan akurasi. coremltools menyediakan utilitas ct.utils.compare_models() untuk membandingkan prediksi model asli dan model yang dikonversi pada data input yang sama. Selisih yang diizinkan — tidak lebih dari 1e-5 untuk Float32. Jika selisih terlampaui, kemungkinan model memiliki custom layers atau operasi yang tidak didukung dalam format baru.

Kompatibilitas mundur dan dukungan

Kompatibilitas mundur .mlmodel disediakan di semua versi iOS dan macOS saat ini. Aplikasi yang dikompilasi dengan Xcode 12 atau lebih baru secara otomatis mendapatkan versi .mlpackage dari model, bahkan jika file aslinya adalah .mlmodel. Namun, mulai dari Xcode 15 (2023) Apple mengumumkan bahwa jenis model baru (jaringan saraf dinamis, pembelajaran terkontrol) hanya akan tersedia dalam format .mlpackage, dan .mlmodel tidak akan menerima kemampuan baru.

Dukungan di iOS 18+ dan macOS 15+

Mulai dari iOS 18 dan macOS 15 (Sequoia), Core ML tidak lagi mendukung pemuatan .mlmodel secara langsung. Semua model .mlmodel harus dikonversi terlebih dahulu ke .mlpackage, atau Xcode Model Compiler akan digunakan untuk konversi selama build. API sistem MLModel(contentsOf:) masih dapat membuka file .mlmodel hanya jika file tersebut telah dikonversi ke .mlpackage pada tahap build proyek.

Batas waktu berakhirnya dukungan

Apple belum secara resmi mengumumkan tanggal penghapusan total dukungan untuk .mlmodel, tetapi konteks historis menunjukkan 3-4 tahun masa transisi. Format .mlmodel diperkenalkan pada 2017, .mlpackage — pada 2021. Peringatan depresiasi muncul di Xcode 13 (2021). Dengan analogi aplikasi 32-bit (iOS 11 menghentikan dukungan), dapat diharapkan bahwa dukungan penuh untuk .mlmodel akan dihentikan di iOS 20-21 (2026-2027).

Kapan mlmodel masih relevan

Meskipun formatnya usang, .mlmodel masih ditemukan di proyek yang sudah ada dan beberapa skenario. Penting bagi pengembang yang bekerja dengan Core ML untuk memahami kapan .mlmodel tetap menjadi bagian dari alur kerja dan bagaimana berinteraksi dengannya dengan benar tanpa kehilangan performa.

Warisan — proyek lama

Proyek yang ada, yang dimulai sebelum tahun 2021, mungkin berisi puluhan model .mlmodel, yang dimuat melalui Swift Package Manager atau langsung di Xcode. Migrasi semua model ke .mlpackage bisa memakan waktu, terutama jika model dihasilkan oleh versi coremltools lama (sebelum 5.0). Apple merekomendasikan migrasi bertahap, satu model pada satu waktu, pada pembaruan fungsionalitas terdekat.

Pipeline CI/CD dengan coremltools

Beberapa pipeline CI/CD yang ada menggunakan coremltools versi 4.x untuk konversi model otomatis, yang secara default mengekspor ke .mlmodel. Memperbarui coremltools ke versi 5+ mengubah format ekspor menjadi .mlpackage, yang mungkin memerlukan pembaruan skrip dan pengujian. Dalam kasus seperti itu, tim terkadang sementara membiarkan ekspor ke .mlmodel sambil merencanakan migrasi untuk nanti.

Pustaka dan Pods

Pustaka pihak ketiga dan CocoaPods, yang diterbitkan sebelum tahun 2021, mungkin berisi model dalam format .mlmodel. Misalnya, pustaka untuk pengenalan wajah, filter gambar, atau filter AR. Pengembang yang menggunakan pustaka tersebut dapat terus bekerja dengan .mlmodel, karena Xcode mengonversinya secara otomatis saat build. Namun, disarankan untuk memeriksa apakah penulis telah merilis pembaruan dengan .mlpackage.

Masalah umum dengan mlmodel

Saat bekerja dengan format .mlmodel yang usang, pengembang menghadapi beberapa masalah umum. Mengetahui masalah-masalah ini dan solusinya memungkinkan menghindari pemborosan waktu saat mengintegrasikan model Core ML ke proyek modern. Mari kita bahas yang utama.

Peringatan depresiasi dari Xcode

Saat menambahkan .mlmodel di Xcode 13+, muncul peringatan: “'mlmodel' format is deprecated. Use 'mlpackage' instead.” Peringatan ini tidak memblokir build, tetapi menunjukkan perlunya migrasi. Untuk menghilangkan peringatan, konversikan model melalui coremltools atau perbarui alat pembuatan model.

Kesalahan “Model file is not valid”

File .mlmodel yang dibuat oleh versi coremltools lama (sebelum 3.0) mungkin tidak dapat dibuka di perangkat baru dengan iOS 16+ karena perubahan pada codec protobuf. Solusinya — muat model melalui Python: model = ct.models.MLModel("old.mlmodel"), lalu simpan lagi: model.save("fixed.mlmodel"), atau lebih baik langsung konversi ke .mlpackage.

Masalah dengan lapisan khusus

Model .mlmodel yang berisi custom layers (lapisan jaringan saraf khusus) tidak dapat dikonversi langsung ke .mlpackage tanpa langkah tambahan. Pertama, perlu memuat model ke coremltools, memeriksa lapisan mana yang tidak didukung oleh format baru, dan mengimplementasikannya untuk .mlpackage. Jika lapisan khusus tidak penting, Anda dapat mencoba menghapusnya dari model.