mlmodel — その概要、ファイル構造、mlpackageへの変換方法

mlmodelとは？

mlmodelは、Appleが2017年にWWDC 2017でCore MLフレームワークとともに発表したバイナリファイル形式です。この形式はGoogleのprotobuf（Protocol Buffers）シリアライゼーション技術に基づいており、コンパクトなサイズ（Float32でのモデル重み）と効率的なメモリ読み込みを実現しました。.mlmodelファイルの拡張子は.mlmodel、MIMEタイプはapplication/x-Apple-mlmodelでした。

形式の歴史

.mlmodel形式は、2017年から2021年まで唯一のCore ML形式でした。この間、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ファイルの内部構造は、CoreML.frameworkフレームワークで定義されたprotobufスキーマによって決定されます。主要なセクションは次のとおりです：modelDescription — モデルの入力、出力、メタデータの説明；modelParameters — モデルタイプの特定のパラメータ（ニューラルネットワークの重み、ツリーアンサンブル、回帰係数）；preprocessing — 前処理設定（スケーリング、画像正規化）；postprocessing — 後処理（softmax、argmax、しきい値）。

modelDescriptionセクション

modelDescriptionセクション（MLModelDescription）には、モデル名、作成者、バージョン、説明、ライセンス、およびすべての入力パラメータと出力パラメータの詳細な説明（名前、データ型（Float32、Int32、String、Image）、次元数、画像形式（BGR、RGB）、オプションの制約（値の範囲））が含まれます。このセクションは、Xcodeが型指定された入力と出力を持つSwiftモデルクラスを生成するために使用されていました。

modelParametersセクション

modelParametersセクションには、学習済みモデルの実際の重みとパラメータが含まれます。ニューラルネットワークの場合、これはレイヤー（NeuralNetworkLayer）の配列であり、各レイヤーにはタイプ（convolution、pooling、activation、innerProduct）、重み、バイアス、パラメータ（kernelSize、stride、padding）が含まれます。アンサンブルモデルの場合 — 決定木とそのノード。回帰の場合 — 係数と切片。重みはFloat32（値あたり4バイト）で保存されます。

preprocessingセクション

preprocessingセクションでは、モデルに入力データを供給する前の前処理手順について説明します。Core MLがサポートするもの：スケーリング（Scaler） — 平均と標準偏差による正規化；画像変換（ImagePreprocessing） — リサイズ、クロップ、カラーチャンネルの正規化、BGR→RGB変換；OneHotEncoder — カテゴリ特徴のエンコーディング；FeatureVectorizer — 複数の特徴を1つのベクトルに結合。

mlmodel vs mlpackage：比較分析

mlpackageは、WWDC 2021で発表されたCore MLモデルの次世代形式です。単一のバイナリ.mlmodelファイルとは異なり、.mlpackageはファイル構造を持つディレクトリ（パッケージ）です：モデルの内容は、読み取り可能なJSONファイル（メタデータ、レイヤー設定）と重み用の個別のバイナリファイルとして保存されます。これにより、ストレージ、バージョン管理、MLモデルでのコラボレーションへのアプローチが根本的に変わります。

mlpackageのファイル構造

.mlpackageパッケージには以下が含まれます：ModelCI/ — バージョン管理されたモデル設定のディレクトリ；Data/ — バイナリ重みファイル（SharedWeights.bin）；Metadata.json — 名前、作成者、説明、モデルバージョン、作成日；Model.json — アーキテクチャの説明、入出力、レイヤータイプ；Manifests/ — CI/CD用のバージョンマニフェスト。この構造により、gitでのモデル操作が効率的になります：メタデータと設定は追跡され、バイナリの重みはGit LFSを使用できます。

mlmodelをmlpackageに変換する方法

.mlmodelから.mlpackageへの変換は、2つの方法で行われます：Xcodeでのビルド時に自動的に（Xcode自体がコンパイル中に.mlmodelを.mlpackageに変換します）、またはPythonでcoremltoolsを介して手動で行います。手動変換ではより細かい制御が可能で、モデルのメタデータの更新、説明の追加、作成者の設定ができます。変換後、モデルは.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プロジェクトに追加すると、システムは自動的にその形式を検出し、ビルド中にModel Compilerを実行します — .mlmodelを.mlpackageに変換するツールです。コンパイルされた.mlpackageはビルドディレクトリ（DerivedData）に配置されます。開発者はこのプロセスに気づきません — すべてのCore ML APIは元の形式に関係なく、モデルと一貫して動作します。ただし、Xcodeは.mlmodelを追加する際に.mlpackageの使用を推奨する警告を表示します。

変換後の検証

変換後、モデルが精度を維持していることを確認する必要があります。coremltoolsは、同一の入力データで元のモデルと変換されたモデルの予測を比較するためのct.utils.compare_models()ユーティリティを提供します。Float32の許容誤差は1e-5以下です。誤差がこのしきい値を超える場合、モデルに新しい形式でサポートされていないカスタムレイヤーや操作が含まれている可能性があります。

後方互換性とサポート

.mlmodelの後方互換性は、iOSおよびmacOSの現在のすべてのバージョンで保証されています。Xcode 12以降でコンパイルされたアプリケーションは、元のファイルが.mlmodelであっても、自動的にモデルの.mlpackageバージョンを取得します。ただし、Xcode 15（2023）以降、Appleは新しいモデルタイプ（動的ニューラルネットワーク、制御学習）が.mlpackage形式でのみ利用可能になり、.mlmodelは新機能を受け取らないことを発表しました。

iOS 18+およびmacOS 15+でのサポート

iOS 18およびmacOS 15（Sequoia）以降、Core MLは.mlmodelの直接読み込みをサポートしなくなりました。すべての.mlmodelモデルは事前に.mlpackageに変換する必要があるか、ビルド中にXcode Model Compilerが変換に使用されます。システムAPI MLModel(contentsOf:)は、プロジェクトのビルド段階で.mlpackageに変換された場合にのみ.mlmodelファイルを開くことができます。

サポート終了の時期

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年より前に開始された既存のプロジェクトには、Swift Package ManagerまたはXcodeに直接ロードされた数十の.mlmodelモデルが含まれている場合があります。すべてのモデルを.mlpackageに移行するには労力がかかる可能性があり、特にモデルが古いバージョンのcoremltools（5.0以前）で生成された場合は顕著です。Appleは、機能の更新時に1つのモデルずつ段階的に移行することを推奨しています。

coremltoolsを使用したCI/CDパイプライン

一部の既存のCI/CDパイプラインは、自動モデル変換にcoremltoolsバージョン4.xを使用しており、デフォルトで.mlmodelにエクスポートします。coremltoolsをバージョン5+に更新すると、エクスポート形式が.mlpackageに変わり、スクリプトやテストの更新が必要になる場合があります。そのような場合、チームは移行を後日に計画して、一時的に.mlmodelへのエクスポートを維持することがあります。

ライブラリとPods

2021年より前に公開されたサードパーティのライブラリやCocoaPodsには、.mlmodel形式のモデルが含まれている場合があります。例えば、顔認識、画像フィルタリング、ARフィルタ用のライブラリなどです。これらのライブラリを使用する開発者は、Xcodeがビルド時に自動的に変換するため、.mlmodelで引き続き作業できます。ただし、作者が.mlpackageによるアップデートをリリースしているかどうかを確認することをお勧めします。

mlmodelの一般的な問題

非推奨の.mlmodel形式を扱う際、開発者はいくつかの一般的な問題に直面します。これらの問題とその解決策を知ることで、最新のプロジェクトにCore MLモデルを統合する際の時間の無駄を防ぐことができます。主なものを見てみましょう。

Xcodeの非推奨警告

Xcode 13+で.mlmodelを追加すると、警告が表示されます：“‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” この警告はビルドを妨げませんが、移行の必要性を示しています。警告を解決するには、coremltoolsを介してモデルを変換するか、モデル作成ツールを更新してください。

“Model file is not valid”エラー

古いバージョンのcoremltools（3.0以前）で作成された.mlmodelファイルは、protobufコーデックの変更により、iOS 16+の新しいデバイスで開けない場合があります。解決策は、Pythonでモデルを読み込むことです：model = ct.models.MLModel(“old.mlmodel”)、その後再度保存します：model.save(“fixed.mlmodel”)、または直接.mlpackageに変換することをお勧めします。

カスタムレイヤーの問題

カスタムレイヤー（ユーザー定義のニューラルネットワークレイヤー）を含む.mlmodelモデルは、追加の手順なしでは直接.mlpackageに変換できません。最初にcoremltoolsでモデルを読み込み、新しい形式でサポートされていないレイヤーを確認し、それらを.mlpackage用に実装する必要があります。カスタムレイヤーが重要でない場合は、モデルから削除してみることもできます。