mlmodel — ما هو، بنية الملف والتحويل إلى mlpackage

ما هو mlmodel؟

mlmodel هو تنسيق ملف ثنائي قدمته Apple في 2017 جنبًا إلى جنب مع إطار Core ML في WWDC 2017. يعتمد التنسيق على تقنية التسلسل protobuf (Protocol Buffers) من Google، مما يضمن حجمًا مضغوطًا (أوزان النموذج بتنسيق Float32) وتحميلًا فعالًا في الذاكرة. كان لملف .mlmodel الامتداد .mlmodel ونوع MIME application/x-Apple-mlmodel.

تاريخ التنسيق

كان تنسيق .mlmodel هو تنسيق Core ML الوحيد من 2017 إلى 2021. خلال هذا الوقت، تم تحويل ملايين النماذج من TensorFlow وKeras وPyTorch وCaffe وscikit-learn ومكتبات أخرى عبر coremltools. أصبحت قيود التنسيق واضحة مع زيادة تعقيد النماذج: لا يدعم protobuf التحكم الملائم في الإصدارات، ويتم تخزين البيانات الوصفية بشكل ثنائي (غير قابل للقراءة في git diff)، ويتطلب إضافة حقول جديدة تغييرات في مخطط protobuf.

الخصائص الرئيسية

يخزن ملف mlmodel النموذج في تمثيل ثنائي مضغوط. يتراوح الحجم من عشرات الكيلوبايتات (الانحدار الخطي) إلى الجيجابايتات (الشبكات العصبية بملايين المعلمات). يدعم التنسيق جميع أنواع نماذج Core ML: الشبكات العصبية (NeuralNetwork، NeuralNetworkClassifier، NeuralNetworkRegressor)، النماذج المجمعة (TreeEnsemble، GradientBoosting)، الانحدارات (LinearRegression، SVM) وخطوط أنابيب المعالجة المسبقة/اللاحقة (OneHotEncoder، FeatureVectorizer).

بنية ملف mlmodel

يتم تحديد البنية الداخلية لملف .mlmodel بواسطة مخطط protobuf الموصوف في إطار CoreML.framework. الأقسام الرئيسية هي: modelDescription — وصف المدخلات والمخرجات والبيانات الوصفية للنموذج؛ modelParameters — معلمات محددة لنوع النموذج (أوزان الشبكة العصبية، tree ensembles، معاملات الانحدار)؛ preprocessing — تكوين المعالجة المسبقة (التحجيم، تسوية الصور)؛ postprocessing — المعالجة اللاحقة (softmax، argmax، قيم العتبة).

قسم modelDescription

يحتوي قسم modelDescription (MLModelDescription) على اسم النموذج والمؤلف والإصدار والوصف والترخيص، بالإضافة إلى وصف تفصيلي لجميع معلمات المدخلات والمخرجات: الاسم ونوع البيانات (Float32، Int32، String، Image) والأبعاد وتنسيق الصورة (BGR، RGB) والقيود الاختيارية (نطاق القيم). كان هذا القسم يُستخدم بواسطة Xcode لإنشاء فئة Swift للنموذج مع مدخلات ومخرجات محددة الأنواع.

قسم modelParameters

يحتوي قسم modelParameters على الأوزان الفعلية ومعلمات النموذج المدرب. للشبكات العصبية، هذه مصفوفة من الطبقات (NeuralNetworkLayer)، تحتوي كل منها على النوع (convolution، pooling، activation، innerProduct) والأوزان والانحيازات (bias) والمعلمات (kernelSize، stride، padding). للنماذج المجمعة — أشجار القرار وعقدها. للانحدارات — المعاملات والجزء المقطوع (intercept). يتم تخزين الأوزان بتنسيق Float32 (4 بايت لكل قيمة).

قسم preprocessing

يصف قسم preprocessing خطوات المعالجة المسبقة لبيانات الإدخال قبل إدخالها في النموذج. يدعم Core ML: التحجيم (Scaler) — التسوية عبر المتوسط والانحراف المعياري؛ تحويل الصور (ImagePreprocessing) — تغيير الحجم والقص وتسوية قنوات الألوان وتحويل BGR→RGB؛ OneHotEncoder — ترميز السمات الفئوية؛ FeatureVectorizer — دمج سمات متعددة في متجه واحد.

mlmodel ضد mlpackage: تحليل مقارن

mlpackage هو تنسيق الجيل التالي لنماذج Core ML، تم تقديمه في WWDC 2021. على عكس ملف .mlmodel الثنائي الواحد، فإن .mlpackage هو دليل (حزمة) بهيكل ملفات: يتم تخزين محتوى النموذج كملفات JSON قابلة للقراءة (البيانات الوصفية، تكوين الطبقات) وملفات ثنائية منفصلة للأوزان. هذا يغير جذريًا نهج التخزين والتحكم في الإصدارات والعمل المشترك على نماذج ML.

هيكل ملفات mlpackage

تحتوي حزمة .mlpackage على: ModelCI/ — دليل مع تكوين النموذج المرقم؛ Data/ — ملفات أوزان ثنائية (SharedWeights.bin)؛ Metadata.json — الاسم والمؤلف والوصف وإصدار النموذج وتاريخ الإنشاء؛ Model.json — وصف البنية والمدخلات/المخرجات وأنواع الطبقات؛ Manifests/ — بيانات الإصدارات لـ CI/CD. يسمح هذا الهيكل بالعمل بكفاءة مع النموذج في git: يتم تتبع البيانات الوصفية والتكوين، بينما يمكن أن تستخدم الأوزان الثنائية Git LFS.

كيفية تحويل mlmodel إلى mlpackage

يتم التحويل من .mlmodel إلى .mlpackage بطريقتين: تلقائيًا أثناء البناء في Xcode (يقوم Xcode نفسه بتحويل .mlmodel إلى .mlpackage أثناء التجميع) أو يدويًا عبر coremltools في Python. يمنح التحويل اليدوي تحكمًا أكبر ويتيح تحديث البيانات الوصفية للنموذج وإضافة وصف وتعيين المؤلف. بعد التحويل، يتم حفظ النموذج كـ .mlpackage ويمكن استخدامه بدلاً من .mlmodel الأصلي.

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

عند إضافة ملف .mlmodel إلى مشروع Xcode، يكتشف النظام تنسيقه تلقائيًا وأثناء البناء يشغل مترجم النماذج — وهي أداة تقوم بترجمة .mlmodel إلى .mlpackage. يتم وضع .mlpackage المترجم في دليل البناء (DerivedData). لا يلاحظ المطور هذه العملية — جميع واجهات برمجة تطبيقات Core ML تعمل مع النموذج بشكل موحد بغض النظر عن التنسيق الأصلي. ومع ذلك، يصدر Xcode تحذيرًا عند إضافة .mlmodel مع توصية باستخدام .mlpackage.

التحقق بعد التحويل

بعد التحويل، من الضروري التأكد من أن النموذج حافظ على الدقة. توفر coremltools أداة ct.utils.compare_models() لمقارنة تنبؤات النموذج الأصلي والمحول على نفس بيانات الإدخال. التباين المقبول لا يزيد عن 1e-5 لـ Float32. إذا تجاوز التباين هذا الحد، فمن المحتمل أن النموذج يحتوي على طبقات مخصصة أو عمليات غير مدعومة في التنسيق الجديد.

التوافق مع الإصدارات السابقة والدعم

يتم ضمان التوافق مع الإصدارات السابقة لـ .mlmodel على جميع الإصدارات الحالية من iOS وmacOS. التطبيق المترجم مع Xcode 12 أو أحدث يتلقى تلقائيًا إصدار .mlpackage من النموذج، حتى إذا كان الملف الأصلي .mlmodel. ومع ذلك، اعتبارًا من Xcode 15 (2023)، أعلنت Apple أن أنواع النماذج الجديدة (الشبكات العصبية الديناميكية، التعلم المتحكم به) ستكون متاحة فقط بتنسيق .mlpackage، ولن يتلقى .mlmodel إمكانيات جديدة.

الدعم في iOS 18+ وmacOS 15+

اعتبارًا من iOS 18 وmacOS 15 (Sequoia)، لم يعد Core ML يدعم تحميل .mlmodel مباشرة. يجب تحويل جميع نماذج .mlmodel مسبقًا إلى .mlpackage، أو سيتم استخدام مترجم نماذج Xcode للتحويل أثناء البناء. لا يزال بإمكان واجهة برمجة التطبيقات النظامية MLModel(contentsOf:) فتح ملفات .mlmodel فقط إذا تم تحويلها إلى .mlpackage في مرحلة بناء المشروع.

الجدول الزمني لإنهاء الدعم

لم تعلن Apple رسميًا عن تاريخ للإزالة الكاملة لدعم .mlmodel، لكن السياق التاريخي يشير إلى فترة انتقالية من 3 إلى 4 سنوات. تم تقديم تنسيق .mlmodel في 2017، و.mlpackage في 2021. ظهرت تحذيرات الإهمال في Xcode 13 (2021). قياسًا على التطبيقات ذات 32 بت (أوقفت iOS 11 الدعم)، يمكن توقع إنهاء الدعم الكامل لـ .mlmodel في iOS 20-21 (2026-2027).

متى لا يزال mlmodel ملائمًا

على الرغم من إهمال التنسيق، لا يزال .mlmodel موجودًا في المشاريع الحالية وبعض السيناريوهات. يحتاج المطورون الذين يعملون مع Core ML إلى فهم متى يظل .mlmodel جزءًا من سير العمل وكيفية التفاعل معه بشكل صحيح دون فقدان الأداء.

القديم — المشاريع القديمة

قد تحتوي المشاريع الحالية التي بدأت قبل 2021 على عشرات النماذج .mlmodel المحملة عبر Swift Package Manager أو مباشرة في Xcode. قد يكون ترحيل جميع النماذج إلى .mlpackage مكلفًا من حيث الوقت، خاصة إذا تم إنشاء النماذج بإصدار قديم من coremltools (قبل 5.0). توصي Apple بالترحيل التدريجي، نموذجًا واحدًا في كل مرة، أثناء أقرب تحديث للوظائف.

خط أنابيب CI/CD مع coremltools

تستخدم بعض خطوط أنابيب CI/CD الحالية coremltools الإصدار 4.x للتحويل التلقائي للنماذج، والذي يصدر افتراضيًا إلى .mlmodel. يؤدي تحديث coremltools إلى الإصدار 5+ إلى تغيير تنسيق التصدير إلى .mlpackage، مما قد يتطلب تحديث البرامج النصية والاختبارات. في مثل هذه الحالات، تحتفظ الفرق أحيانًا مؤقتًا بالتصدير إلى .mlmodel، مع التخطيط للترحيل في تاريخ لاحق.

المكتبات وPods

قد تحتوي المكتبات وCocoaPods التابعة لجهات خارجية المنشورة قبل 2021 على نماذج بتنسيق .mlmodel. على سبيل المثال، مكتبات التعرف على الوجه، أو تصفية الصور، أو مرشحات AR. يمكن للمطورين الذين يستخدمون هذه المكتبات مواصلة العمل مع .mlmodel لأن Xcode يحولها تلقائيًا أثناء البناء. ومع ذلك، يوصى بالتحقق مما إذا كان المؤلف قد أصدر تحديثًا مع .mlpackage.

المشكلات الشائعة مع mlmodel

عند العمل مع التنسيق المهمل .mlmodel، يواجه المطورون عدة مشكلات شائعة. معرفة هذه المشكلات وحلولها يساعد على تجنب إضاعة الوقت عند دمج نماذج Core ML في المشاريع الحديثة. دعنا نلقي نظرة على أهمها.

تحذير Xcode بشأن الإهمال

عند إضافة .mlmodel في Xcode 13+ يظهر تحذير: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” لا يمنع التحذير البناء ولكنه يشير إلى الحاجة إلى الترحيل. لإزالة التحذير، قم بتحويل النموذج عبر coremltools أو قم بتحديث أداة إنشاء النموذج.

خطأ “Model file is not valid”

قد لا يتم فتح ملف .mlmodel الذي تم إنشاؤه بإصدار قديم من coremltools (قبل 3.0) على الأجهزة الجديدة التي تعمل بنظام iOS 16+ بسبب تغييرات في برامج ترميز protobuf. الحل هو تحميل النموذج عبر Python: model = ct.models.MLModel(“old.mlmodel”)، ثم حفظه مرة أخرى: model.save(“fixed.mlmodel”)، أو الأفضل تحويله مباشرة إلى .mlpackage.

مشكلات الطبقات المخصصة

نماذج .mlmodel التي تحتوي على طبقات مخصصة (طبقات شبكة عصبية معرفة من قبل المستخدم) لا يمكن تحويلها مباشرة إلى .mlpackage دون خطوات إضافية. يجب أولاً تحميل النموذج في coremltools والتحقق من أي الطبقات غير مدعومة في التنسيق الجديد وتنفيذها لـ .mlpackage. إذا كانت الطبقة المخصصة غير حرجة، يمكنك محاولة إزالتها من النموذج.