Apple - CoreML

CoreML実行プロバイダー

Core MLは、Appleが導入した機械学習フレームワークです。パフォーマンスを最大化しながらメモリと電力消費を最小化するために、CPU、GPU、Neural Engineを含む強力なハードウェア技術を最も効率的な方法でシームレスに活用するように設計されています。

要件

CoreML実行プロバイダー（EP）には、iOS 13以上のiOSデバイス、またはmacOS 10.15以上のMacコンピューターが必要です。

最適なパフォーマンスを実現するために、Apple Neural Engineを搭載したAppleデバイスの使用をお勧めします。

インストール

iOS用のCoreML EPを含むONNX Runtimeの事前ビルドバイナリがCocoaPodsに公開されています。

インストール手順についてはこちらを参照してください。

ビルド

iOSデバイス用のビルド手順については、Build for iOSを参照してください。

使用方法

ONNX Runtime APIの詳細はこちらにあります。

CoreML EPは、C、C++、Objective-C、C#、Java APIを介して使用できます。

推論セッションを作成する際に、CoreML EPを明示的に登録する必要があります。例：

Ort::Env env = Ort::Env{ORT_LOGGING_LEVEL_ERROR, "Default"};
Ort::SessionOptions so;
std::unordered_map<std::string, std::string> provider_options;
provider_options["ModelFormat"] = std::to_string("MLProgram");
so.AppendExecutionProvider("CoreML", provider_options);
Ort::Session session(env, model_path, so);

非推奨 ONNX Runtime 1.20.0でAPI OrtSessionOptionsAppendExecutionProvider_CoreMLが非推奨になりました。代わりにOrtSessionOptionsAppendExecutionProviderを使用してください。

Ort::Env env = Ort::Env{ORT_LOGGING_LEVEL_ERROR, "Default"};
Ort::SessionOptions so;
uint32_t coreml_flags = 0;
Ort::ThrowOnError(OrtSessionOptionsAppendExecutionProvider_CoreML(so, coreml_flags));
Ort::Session session(env, model_path, so);

設定オプション（新API）

CoreML EPには、いくつかの実行時オプションが利用できます。

CoreML EPの実行時オプションを使用するには、オプションを表す符号なし整数を作成し、ビット単位OR演算子を使用して各個別オプションを設定します。

ProviderOptionsは、AppendExecutionProviderメソッドに文字列を渡すことで設定できます。

Ort::Env env = Ort::Env{ORT_LOGGING_LEVEL_ERROR, "Default"};
Ort::SessionOptions so;
std::string model_path = "/a/b/c/model.onnx";
std::unordered_map<std::string, std::string> provider_options;
provider_options["ModelFormat"] = "MLProgram";
provider_options["MLComputeUnits"] = "ALL";
provider_options["RequireStaticInputShapes"] = "0";
provider_options["EnableOnSubgraphs"] = "0";
so.AppendExecutionProvider("CoreML", provider_options);
Ort::Session session(env, model_path, so);

CoreML EPの実行時オプションを使用するPython推論サンプルコード：

import onnxruntime as ort
model_path = "model.onnx"
providers = [
    ('CoreMLExecutionProvider', {
        "ModelFormat": "MLProgram", "MLComputeUnits": "ALL",
        "RequireStaticInputShapes": "0", "EnableOnSubgraphs": "0"
    }),
]

session = ort.InferenceSession(model_path, providers=providers)
outputs = ort_sess.run(None, input_feed)

利用可能なオプション（新API）

ModelFormatは以下の値のいずれかです：（デフォルトはNeuralNetwork）

MLProgram：MLProgram形式のモデルを作成します。Core ML 5以降（iOS 15+またはmacOS 12+）が必要です。
NeuralNetwork：NeuralNetwork形式のモデルを作成します。Core ML 3以降（iOS 13+またはmacOS 10.15+）が必要です。

MLComputeUnitsは以下の値のいずれかです：（デフォルトはALL）

CPUOnly：CoreMLをCPUのみで実行するように制限します。
CPUAndNeuralEngine：互換性のあるApple Neural Engine（ANE）を搭載したAppleデバイスでCoreML EPを有効にします。
CPUAndGPU：互換性のあるGPUを搭載したAppleデバイスでCoreML EPを有効にします。
ALL：すべての互換性のあるAppleデバイスでCoreML EPを有効にします。

RequireStaticInputShapesは以下の値のいずれかです：（デフォルトは0）

CoreML EPが静的形状を持つ入力を持つノードのみを受け取ることを許可します。デフォルトでは、CoreML EPは動的形状を持つ入力も許可しますが、動的形状を持つ入力によってパフォーマンスが悪影響を受ける可能性があります。

0：CoreML EPが動的形状を持つ入力を持つノードを受け取ることを許可します。
1：CoreML EPが静的形状を持つ入力を持つノードのみを受け取ることを許可します。

EnableOnSubgraphsは以下の値のいずれかです：（デフォルトは0）

制御フロー演算子（Loop、Scan、If演算子など）の本体内のサブグラフでCoreML EPを実行できるようにします。

0：制御フロー演算子の本体内のサブグラフでCoreML EPの実行を無効にします。
1：制御フロー演算子の本体内のサブグラフでCoreML EPの実行を有効にします。

SpecializationStrategy：この機能はmacOS>=10.15またはiOS>=18.0以降で利用できます。このプロセスはモデルの読み込み時間と予測レイテンシに影響を与える可能性があります。このオプションを使用して、モデルの特殊化戦略を調整してください。詳細についてはApple Docを参照してください。以下の値のいずれかです：（デフォルトはDefault）

Default：
FastPrediction：

ProfileComputePlan：Core ML MLComputePlanをプロファイルします。これは各演算子がディスパッチされるハードウェアと推定実行時間をログに記録します。開発者の使用を意図していますが、パフォーマンスが期待通りでない場合に有用な診断情報を提供します。以下の値のいずれかです：（デフォルトは0）

0：プロファイルを無効にします。
1：プロファイルを有効にします。

AllowLowPrecisionAccumulationOnGPU：Apple Docを参照してください。以下の値のいずれかです：（デフォルトは0）

0：float32データ型を使用してデータを蓄積します。
1：低精度データ（float16）を使用してデータを蓄積します。

ModelCacheDirectory：Core MLモデルキャッシュが保存されるディレクトリへのパス。CoreML EPはキャプチャされたサブグラフをCoreML形式のグラフにコンパイルし、ディスクに保存します。指定されたモデルに対して、キャッシュが有効でない場合、CoreML EPは毎回コンパイルしてディスクに保存するため、複雑なモデルでは大幅な時間（数分でも）がかかる可能性があります。キャッシュパスを提供することで、CoreML形式のモデルを再利用できます。（デフォルトではキャッシュは無効）

""：キャッシュを無効にします。（デフォルトは空文字列）
"/path/to/cache"：キャッシュを有効にします。（キャッシュディレクトリへのパス、存在しない場合は作成されます）

モデルのキャッシュ情報は、キャッシュディレクトリ内のモデルハッシュの下に保存されます。ハッシュは優先順位に従って3つの方法で計算される可能性があります。

モデルのmetadata_propsから読み取ります。これによりユーザーはハッシュを直接制御でき、推奨される使用方法です。キャッシュキーは以下の条件を満たす必要があります：（1）値は英数字のみを含む必要があります。（2）len(value) < 64。EPはこれらの条件を満たすためにキャッシュキーを再ハッシュします。
推論セッションが作成されたモデルURLのハッシュ。
推論セッションがメモリ内バイト（つまり、モデルパスがない）で作成された場合のグラフ入力とノード出力のハッシュ。

モデルが変更された場合、ハッシュ値を変更するか、以前のキャッシュ情報をクリアする必要があります。例えば、モデルURLがハッシュに使用されている場合（上記のオプション2）、更新されたモデルはハッシュ値を変更するために異なるパスから読み込む必要があります。

ONNX Runtimeにはモデルの変更を追跡する仕組みがなく、キャッシュエントリを削除しません。

モデルのメタデータにモデルハッシュを記入する方法の例：

import onnx
import hashlib

# モデルとそのハッシュ値が一対一マッピングであることを保証するために、他のハッシュアルゴリズムを使用できます。
def hash_file(file_path, algorithm='sha256', chunk_size=8192):
    hash_func = hashlib.new(algorithm)
    with open(file_path, 'rb') as file:
        while chunk := file.read(chunk_size):
            hash_func.update(chunk)
    return hash_func.hexdigest()

CACHE_KEY_NAME = "CACHE_KEY"
model_path = "/a/b/c/model.onnx"
m = onnx.load(model_path)

cache_key = m.metadata_props.add()
cache_key.key = CACHE_KEY_NAME
cache_key.value = str(hash_file(model_path))

onnx.save_model(m, model_path)

設定オプション（旧API）

uint32_t coreml_flags = 0;
coreml_flags |= COREML_FLAG_ONLY_ENABLE_DEVICE_WITH_ANE;

利用可能なオプション（非推奨API）

COREML_FLAG_USE_CPU_ONLY

CoreMLをCPUのみで実行するように制限します。

これによりパフォーマンスは低下しますが、精度損失なしに参照出力値を提供するため、検証に有用です。
開発者の使用のみを意図しています。

COREML_FLAG_ENABLE_ON_SUBGRAPH

制御フロー演算子（Loop、Scan、If演算子など）の本体内のサブグラフでCoreML EPを実行できるようにします。

COREML_FLAG_ONLY_ENABLE_DEVICE_WITH_ANE

デフォルトでは、CoreML EPはすべての互換性のあるAppleデバイスで有効になります。

このオプションを設定すると、互換性のあるApple Neural Engine（ANE）を搭載したAppleデバイスでのみCoreML EPが有効になります。注意：このオプションを有効にしても、モデル全体がANEのみを使用して実行されることは保証されません。

詳細については、Which devices have an ANE?を参照してください。

COREML_FLAG_ONLY_ALLOW_STATIC_INPUT_SHAPES

COREML_FLAG_CREATE_MLPROGRAM

MLProgram形式のモデルを作成します。Core ML 5以降（iOS 15+またはmacOS 12+）が必要です。デフォルトは、Core ML 3以降（iOS 13+またはmacOS 10.15+）を必要とするNeuralNetworkモデルが作成されます。

サポートされている演算子

NeuralNetwork

NeuralNetworkモデル（デフォルト）が作成される際にCoreML実行プロバイダーでサポートされている演算子：

演算子	注意
ai.onnx:Add
ai.onnx:ArgMax
ai.onnx:AveragePool	2D Poolのみサポート。
ai.onnx:BatchNormalization
ai.onnx:Cast
ai.onnx:Clip
ai.onnx:Concat
ai.onnx:Conv	1D/2D Convのみサポート。重みとバイアスは定数である必要があります。
ai.onnx:DepthToSpace	DCRモードのDepthToSpaceのみサポート。
ai.onnx:Div
ai.onnx:Flatten
ai.onnx:Gather	スカラー値を持つ入力`indices`はサポートされていません。
ai.onnx:Gemm	入力Bは定数である必要があります。
ai.onnx:GlobalAveragePool	2D Poolのみサポート。
ai.onnx:GlobalMaxPool	2D Poolのみサポート。
ai.onnx:LeakyRelu
ai.onnx:LRN
ai.onnx:MatMul	入力Bは定数である必要があります。
ai.onnx:MaxPool	2D Poolのみサポート。
ai.onnx:Mul
ai.onnx:Pad	定数モードと最後の2次元パディングのみサポート。入力padsとconstant_valueは定数である必要があります。提供される場合、axesは定数である必要があります。
ai.onnx:Pow	両方の入力がfp32の場合のみサポート。
ai.onnx:PRelu	入力slopeは定数である必要があります。入力slopeは形状[C, 1, 1]または1要素を持つ必要があります。
ai.onnx:Reciprocal
ai.onnx.ReduceSum
ai.onnx:Relu
ai.onnx:Reshape
ai.onnx:Resize	4D入力。 `coordinate_transformation_mode` == `asymmetric`。 `mode` == `linear`または`nearest`。 `nearest_mode` == `floor`。 `exclude_outside` == false `scales`または`sizes`は定数である必要があります。
ai.onnx:Shape	デフォルト以外の値を持つ属性`start`はサポートされていません。属性`end`はサポートされていません。
ai.onnx:Sigmoid
ai.onnx:Slice	入力`starts`、`ends`、`axes`、`steps`は定数である必要があります。空のスライスはサポートされていません。
ai.onnx:Softmax
ai.onnx:Split	提供される場合、`splits`は定数である必要があります。
ai.onnx:Squeeze
ai.onnx:Sqrt
ai.onnx:Sub
ai.onnx:Tanh
ai.onnx:Transpose

MLProgram

MLProgramモデル（COREML_FLAG_CREATE_MLPROGRAMフラグが設定されている）が作成される際にCoreML実行プロバイダーでサポートされている演算子：

演算子	注意
ai.onnx:Add
ai.onnx:Argmax
ai.onnx:AveragePool	現在2D Poolのみサポート。必要に応じて3Dと5Dサポートを追加可能。
ai.onnx:Cast
ai.onnx:Clip
ai.onnx:Concat
ai.onnx:Conv	1D/2D Convのみサポート。提供される場合、バイアスは定数である必要があります。
ai.onnx:ConvTranspose	重みとバイアスは定数である必要があります。 SAME_UPPER/SAME_LOWERのpadding_typeはサポートされていません。 kernel_shapeはデフォルト値を持つ必要があります。 output_shapeはサポートされていません。 output_paddingはデフォルト値を持つ必要があります。
ai.onnx:DepthToSpace	’mode’が’CRD’の場合、入力は固定形状を持つ必要があります。
ai.onnx:Div
ai.onnx:Erf
ai.onnx:Gemm	入力Bは定数である必要があります。
ai.onnx:Gelu
ai.onnx:GlobalAveragePool	現在2D Poolのみサポート。必要に応じて3Dと5Dサポートを追加可能。
ai.onnx:GlobalMaxPool	現在2D Poolのみサポート。必要に応じて3Dと5Dサポートを追加可能。
ai.onnx:GridSample	4D入力。 ‘linear’または’zeros’の’mode’。 (mode==linear && padding_mode==reflection && align_corners==0)はサポートされていません。
ai.onnx:GroupNormalization
ai.onnx:InstanceNormalization
ai.onnx:LayerNormalization
ai.onnx:LeakyRelu
ai.onnx:MatMul	現在、transA == 0、alpha == 1.0、beta == 1.0のサポートのみ実装されています。
ai.onnx:MaxPool	現在2D Poolのみサポート。必要に応じて3Dと5Dサポートを追加可能。
ai.onnx:Max
ai.onnx:Mul
ai.onnx:Pow	両方の入力がfp32の場合のみサポート。
ai.onnx:PRelu
ai.onnx:Reciprocal	これは`epislon`（デフォルト1e-4）を要求しますが、onnxは提供しません
ai.onnx:ReduceSum
ai.onnx:ReduceMean
ai.onnx:ReduceMax
ai.onnx:Relu
ai.onnx:Reshape
ai.onnx:Resize	resize_op_builder.ccの実装を参照してください。有効な組み合わせを説明するには順列が多すぎます。
ai.onnx:Round
ai.onnx:Shape
ai.onnx:Slice	starts/ends/axes/stepsは定数初期化子である必要があります。
ai.onnx:Split	提供される場合、`splits`は定数である必要があります。
ai.onnx:Sub
ai.onnx:Sigmoid
ai.onnx:Softmax
ai.onnx:Sqrt
ai.onnx:Squeeze
ai.onnx:Tanh
ai.onnx:Transpose
ai.onnx:Unsqueeze