mlmodel — nó là gì, cấu trúc tệp và chuyển đổi sang mlpackage

mlmodel là gì?

mlmodel là định dạng tệp nhị phân được Apple giới thiệu vào năm 2017 cùng với framework Core ML tại WWDC 2017. Định dạng này dựa trên công nghệ tuần tự hóa protobuf (Protocol Buffers) của Google, đảm bảo kích thước nhỏ gọn (trọng số mô hình ở Float32) và tải vào bộ nhớ hiệu quả. Tệp .mlmodel có phần mở rộng .mlmodel và loại MIME application/x-Apple-mlmodel.

Lịch sử định dạng

Định dạng .mlmodel là định dạng Core ML duy nhất từ năm 2017 đến 2021. Trong thời gian này, hàng triệu mô hình từ TensorFlow, Keras, PyTorch, Caffe, scikit-learn và các thư viện khác đã được chuyển đổi qua coremltools. Các hạn chế của định dạng trở nên rõ ràng khi độ phức tạp của mô hình tăng lên: protobuf không hỗ trợ quản lý phiên bản thuận tiện, siêu dữ liệu được lưu trữ dưới dạng nhị phân (không đọc được trong git diff) và việc thêm trường mới yêu cầu thay đổi lược đồ protobuf.

Các đặc điểm chính

Tệp mlmodel lưu trữ mô hình dưới dạng biểu diễn nhị phân nhỏ gọn. Kích thước dao động từ vài chục kilobyte (hồi quy tuyến tính) đến gigabyte (mạng nơ-ron với hàng triệu tham số). Định dạng hỗ trợ tất cả các loại mô hình Core ML: mạng nơ-ron (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), mô hình tổ hợp (TreeEnsemble, GradientBoosting), hồi quy (LinearRegression, SVM) và đường ống tiền/xử lý hậu kỳ (OneHotEncoder, FeatureVectorizer).

Cấu trúc tệp mlmodel

Cấu trúc bên trong của tệp .mlmodel được xác định bởi lược đồ protobuf được mô tả trong framework CoreML.framework. Các phần chính là: modelDescription — mô tả đầu vào, đầu ra và siêu dữ liệu của mô hình; modelParameters — các tham số cụ thể của loại mô hình (trọng số mạng nơ-ron, tổ hợp cây, hệ số hồi quy); preprocessing — cấu hình tiền xử lý (chia tỷ lệ, chuẩn hóa hình ảnh); postprocessing — hậu xử lý (softmax, argmax, giá trị ngưỡng).

Phần modelDescription

Phần modelDescription (MLModelDescription) chứa tên mô hình, tác giả, phiên bản, mô tả, giấy phép, cũng như mô tả chi tiết về tất cả các tham số đầu vào và đầu ra: tên, loại dữ liệu (Float32, Int32, String, Image), số chiều, định dạng hình ảnh (BGR, RGB), các ràng buộc tùy chọn (phạm vi giá trị). Phần này được Xcode sử dụng để tạo lớp Swift của mô hình với đầu vào và đầu ra được định kiểu.

Phần modelParameters

Phần modelParameters chứa trọng số và tham số thực tế của mô hình đã huấn luyện. Đối với mạng nơ-ron, đây là một mảng các lớp (NeuralNetworkLayer), mỗi lớp chứa loại (convolution, pooling, activation, innerProduct), trọng số, độ lệch (bias) và các tham số (kernelSize, stride, padding). Đối với mô hình tổ hợp — cây quyết định và các nút của chúng. Đối với hồi quy — hệ số và điểm chặn. Trọng số được lưu trữ ở Float32 (4 byte mỗi giá trị).

Phần preprocessing

Phần preprocessing mô tả các bước tiền xử lý dữ liệu đầu vào trước khi đưa vào mô hình. Core ML hỗ trợ: chia tỷ lệ (Scaler) — chuẩn hóa qua giá trị trung bình và độ lệch chuẩn; biến đổi hình ảnh (ImagePreprocessing) — thay đổi kích thước, cắt xén, chuẩn hóa kênh màu, chuyển đổi BGR→RGB; OneHotEncoder — mã hóa các đặc điểm phân loại; FeatureVectorizer — kết hợp nhiều đặc điểm thành một vectơ.

mlmodel vs mlpackage: phân tích so sánh

mlpackage là định dạng thế hệ tiếp theo cho các mô hình Core ML, được giới thiệu tại WWDC 2021. Không giống như tệp nhị phân .mlmodel đơn lẻ, .mlpackage là một thư mục (gói) có cấu trúc tệp: nội dung mô hình được lưu trữ dưới dạng tệp JSON có thể đọc được (siêu dữ liệu, cấu hình lớp) và các tệp nhị phân riêng biệt cho trọng số. Điều này thay đổi căn bản cách tiếp cận lưu trữ, quản lý phiên bản và cộng tác trên các mô hình ML.

Cấu trúc tệp của mlpackage

Gói .mlpackage chứa: ModelCI/ — thư mục với cấu hình mô hình được quản lý phiên bản; Data/ — tệp trọng số nhị phân (SharedWeights.bin); Metadata.json — tên, tác giả, mô tả, phiên bản mô hình, ngày tạo; Model.json — mô tả kiến trúc, đầu vào/đầu ra, loại lớp; Manifests/ — bảng kê phiên bản cho CI/CD. Cấu trúc này cho phép làm việc hiệu quả với mô hình trong git: siêu dữ liệu và cấu hình được theo dõi, trong khi trọng số nhị phân có thể sử dụng Git LFS.

Cách chuyển đổi mlmodel sang mlpackage

Chuyển đổi từ .mlmodel sang .mlpackage được thực hiện theo hai cách: tự động trong quá trình xây dựng trong Xcode (Xcode tự chuyển đổi .mlmodel thành .mlpackage trong quá trình biên dịch) hoặc thủ công qua coremltools trong Python. Chuyển đổi thủ công mang lại nhiều quyền kiểm soát hơn và cho phép cập nhật siêu dữ liệu mô hình, thêm mô tả và đặt tác giả. Sau khi chuyển đổi, mô hình được lưu dưới dạng .mlpackage và có thể được sử dụng thay cho .mlmodel gốc.

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

Chuyển đổi tự động trong Xcode

Khi thêm tệp .mlmodel vào dự án Xcode, hệ thống tự động phát hiện định dạng của nó và trong quá trình xây dựng sẽ chạy Model Compiler — một công cụ chuyển đổi .mlmodel thành .mlpackage. Tệp .mlpackage đã biên dịch được đặt trong thư mục xây dựng (DerivedData). Nhà phát triển không nhận thấy quá trình này — tất cả API Core ML đều hoạt động với mô hình một cách thống nhất bất kể định dạng gốc. Tuy nhiên, Xcode đưa ra cảnh báo khi thêm .mlmodel với khuyến nghị sử dụng .mlpackage.

Xác minh sau khi chuyển đổi

Sau khi chuyển đổi, cần đảm bảo mô hình giữ được độ chính xác. coremltools cung cấp tiện ích ct.utils.compare_models() để so sánh dự đoán của mô hình gốc và mô hình đã chuyển đổi trên cùng dữ liệu đầu vào. Sai lệch chấp nhận được không quá 1e-5 đối với Float32. Nếu sai lệch vượt quá ngưỡng này, mô hình có thể có các lớp tùy chỉnh hoặc hoạt động không được hỗ trợ trong định dạng mới.

Tương thích ngược và hỗ trợ

Tương thích ngược của .mlmodel được đảm bảo trên tất cả các phiên bản hiện tại của iOS và macOS. Ứng dụng được biên dịch với Xcode 12 trở lên tự động nhận phiên bản .mlpackage của mô hình, ngay cả khi tệp gốc là .mlmodel. Tuy nhiên, bắt đầu từ Xcode 15 (2023), Apple đã thông báo rằng các loại mô hình mới (mạng nơ-ron động, học có kiểm soát) sẽ chỉ khả dụng ở định dạng .mlpackage và .mlmodel sẽ không nhận được các khả năng mới.

Hỗ trợ trong iOS 18+ và macOS 15+

Bắt đầu từ iOS 18 và macOS 15 (Sequoia), Core ML không còn hỗ trợ tải trực tiếp .mlmodel. Tất cả các mô hình .mlmodel phải được chuyển đổi trước sang .mlpackage hoặc Xcode Model Compiler sẽ được sử dụng để chuyển đổi trong quá trình xây dựng. API hệ thống MLModel(contentsOf:) chỉ có thể mở tệp .mlmodel nếu chúng được chuyển đổi sang .mlpackage ở giai đoạn xây dựng dự án.

Lịch trình kết thúc hỗ trợ

Apple chưa chính thức công bố ngày loại bỏ hoàn toàn hỗ trợ .mlmodel, nhưng bối cảnh lịch sử cho thấy giai đoạn chuyển tiếp kéo dài 3-4 năm. Định dạng .mlmodel được giới thiệu vào năm 2017, .mlpackage vào năm 2021. Cảnh báo lỗi thời xuất hiện trong Xcode 13 (2021). Tương tự như các ứng dụng 32 bit (iOS 11 đã ngừng hỗ trợ), hỗ trợ đầy đủ cho .mlmodel có thể kết thúc vào iOS 20-21 (2026-2027).

Khi nào mlmodel vẫn còn phù hợp

Mặc dù định dạng đã lỗi thời, .mlmodel vẫn được tìm thấy trong các dự án hiện có và một số trường hợp. Các nhà phát triển làm việc với Core ML cần hiểu khi nào .mlmodel vẫn là một phần của quy trình làm việc và cách tương tác chính xác với nó mà không làm giảm hiệu suất.

Kế thừa — các dự án cũ

Các dự án hiện có bắt đầu trước năm 2021 có thể chứa hàng chục mô hình .mlmodel được tải qua Swift Package Manager hoặc trực tiếp trong Xcode. Việc di chuyển tất cả các mô hình sang .mlpackage có thể tốn nhiều công sức, đặc biệt nếu các mô hình được tạo bởi phiên bản cũ của coremltools (trước 5.0). Apple khuyến nghị di chuyển dần dần, từng mô hình một, trong lần cập nhật chức năng gần nhất.

Đường ống CI/CD với coremltools

Một số đường ống CI/CD hiện có sử dụng coremltools phiên bản 4.x để chuyển đổi mô hình tự động, theo mặc định xuất ra .mlmodel. Việc cập nhật coremltools lên phiên bản 5+ sẽ thay đổi định dạng xuất sang .mlpackage, điều này có thể yêu cầu cập nhật tập lệnh và kiểm thử. Trong những trường hợp như vậy, các nhóm đôi khi tạm thời giữ xuất sang .mlmodel, lên kế hoạch di chuyển vào thời điểm sau.

Thư viện và Pods

Các thư viện và CocoaPods của bên thứ ba được xuất bản trước năm 2021 có thể chứa các mô hình ở định dạng .mlmodel. Ví dụ: thư viện nhận dạng khuôn mặt, lọc hình ảnh hoặc bộ lọc AR. Các nhà phát triển sử dụng các thư viện này có thể tiếp tục làm việc với .mlmodel vì Xcode tự động chuyển đổi chúng trong quá trình xây dựng. Tuy nhiên, nên kiểm tra xem tác giả đã phát hành bản cập nhật với .mlpackage chưa.

Các vấn đề thường gặp với mlmodel

Khi làm việc với định dạng .mlmodel lỗi thời, các nhà phát triển gặp phải một số vấn đề phổ biến. Biết được những vấn đề này và giải pháp của chúng giúp tránh lãng phí thời gian khi tích hợp các mô hình Core ML vào các dự án hiện đại. Hãy xem xét những vấn đề chính.

Cảnh báo lỗi thời của Xcode

Khi thêm .mlmodel trong Xcode 13+, một cảnh báo xuất hiện: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” Cảnh báo không chặn quá trình xây dựng nhưng cho thấy sự cần thiết phải di chuyển. Để giải quyết cảnh báo, hãy chuyển đổi mô hình qua coremltools hoặc cập nhật công cụ tạo mô hình.

Lỗi “Model file is not valid”

Tệp .mlmodel được tạo bằng phiên bản cũ của coremltools (trước 3.0) có thể không mở được trên các thiết bị mới chạy iOS 16+ do thay đổi trong bộ giải mã protobuf. Giải pháp là tải mô hình qua Python: model = ct.models.MLModel(“old.mlmodel”), sau đó lưu lại: model.save(“fixed.mlmodel”), hoặc tốt hơn là chuyển đổi trực tiếp sang .mlpackage.

Vấn đề với lớp tùy chỉnh

Các mô hình .mlmodel chứa lớp tùy chỉnh (lớp mạng nơ-ron do người dùng định nghĩa) không thể chuyển đổi trực tiếp sang .mlpackage mà không có các bước bổ sung. Trước tiên, bạn cần tải mô hình trong coremltools, kiểm tra lớp nào không được hỗ trợ trong định dạng mới và triển khai chúng cho .mlpackage. Nếu lớp tùy chỉnh không quan trọng, bạn có thể thử xóa nó khỏi mô hình.