CoreML 执行提供程序

Core ML 是 Apple 引入的机器学习框架。它旨在无缝利用强大的硬件技术，包括 CPU、GPU 和神经引擎，以最有效的方式最大限度地提高性能，同时最大限度地减少内存和功耗。

目录

要求

CoreML 执行提供程序 (EP) 需要运行 iOS 13 或更高版本的 iOS 设备，或者运行 macOS 10.15 或更高版本的 Mac 电脑。

建议使用配备 Apple 神经引擎的 Apple 设备以获得最佳性能。

安装

预构建的带有 CoreML EP 的 ONNX Runtime 二进制文件已发布到 CocoaPods。

有关安装说明，请参阅此处。

构建

有关 iOS 设备的构建说明，请参阅为 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);

已弃用 API OrtSessionOptionsAppendExecutionProvider_CoreML 在 ONNX Runtime 1.20.0 中。请改用 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 运算符设置每个单独的选项。

可以通过将字符串传递给 AppendExecutionProvider 方法来设置 ProviderOptions。

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"] = std::to_string("MLProgram");
provider_options["MLComputeUnits"] = std::to_string("ALL");
provider_options["RequireStaticInputShapes"] = std::to_string("0");
provider_options["EnableOnSubgraphs"] = std::to_string("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 神经引擎 (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）

启用 CoreML EP 以在控制流运算符（即 Loop、Scan 或 If 运算符）的主体中的子图上运行。

  • 0：禁用 CoreML EP 以在控制流运算符的主体中的子图上运行。
  • 1：启用 CoreML EP 以在控制流运算符的主体中的子图上运行。

SpecializationStrategy：此功能自 macOS>=10.15 或 iOS>=18.0 起可用。此过程可能会影响模型加载时间和预测延迟。使用此选项为您的模型定制专业化策略。导航到 Apple 文档 以获取更多信息。可以是以下值之一：（默认为 Default）

  • Default:
  • FastPrediction:

ProfileComputePlan：分析 Core ML MLComputePlan。这将记录每个运算符调度到的硬件以及估计的执行时间。专为开发人员使用而设计，但在性能未达到预期时提供有用的诊断信息。可以是以下值之一：（默认为 0）

  • 0：禁用分析。
  • 1：启用分析。

AllowLowPrecisionAccumulationOnGPU：请参阅 Apple 文档。可以是以下值之一：（默认为 0）

  • 0：使用 float32 数据类型来累积数据。
  • 1：使用低精度数据 (float16) 来累积数据。

ModelCacheDirectory：Core ML 模型缓存存储目录的路径。CoreML EP 将捕获的子图编译为 CoreML 格式图并保存到磁盘。对于给定的模型，如果未启用缓存，CoreML EP 将每次编译并保存到磁盘，这对于复杂的模型可能会花费大量时间（甚至几分钟）。通过提供缓存路径，可以重复使用 CoreML 格式的模型。（默认禁用缓存）。

  • ""：禁用缓存。（默认为空字符串）
  • "/path/to/cache"：启用缓存。（缓存目录的路径，如果不存在将创建）

模型的缓存信息存储在缓存目录中模型哈希下。哈希可以通过三种方式计算，按优先级顺序排列。

  1. 从模型 metadata_props 读取。这为用户提供了一种直接控制哈希的方法，是推荐的用法。缓存键应满足：（1）该值必须仅包含字母数字字符。（2）len(value) < 64。EP 将重新哈希缓存键以满足这些条件。
  2. 使用创建推理会话的模型 url 的哈希。
  3. 如果使用内存字节创建推理会话（即没有模型路径），则图输入和节点输出的哈希。

至关重要的是，如果模型发生更改，则哈希值必须更改，或者您必须清除以前的缓存信息。例如，如果模型 url 用于哈希（上面的选项 2），则必须从不同的路径加载更新的模型以更改哈希值。

ONNX Runtime 没有跟踪模型更改的机制，也不会删除缓存条目。

以下是如何在模型的元数据中填充模型哈希的示例

import onnx
import hashlib

# You can use any other hash algorithms to ensure the model and its hash-value is a one-one mapping. 
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

启用 CoreML EP 以在控制流运算符（即 Loop、Scan 或 If 运算符）的主体中的子图上运行。

COREML_FLAG_ONLY_ENABLE_DEVICE_WITH_ANE

默认情况下，CoreML EP 将为所有兼容的 Apple 设备启用。

设置此选项将仅为配备兼容 Apple 神经引擎 (ANE) 的 Apple 设备启用 CoreML EP。请注意，启用此选项并不能保证整个模型仅使用 ANE 执行。

有关更多信息，请参阅 哪些设备具有 ANE？

COREML_FLAG_ONLY_ALLOW_STATIC_INPUT_SHAPES

仅允许 CoreML EP 接受具有静态形状输入的节点。默认情况下，CoreML EP 也将允许具有动态形状的输入，但是，具有动态形状的输入可能会对性能产生负面影响。

COREML_FLAG_CREATE_MLPROGRAM

创建 MLProgram 格式模型。需要 Core ML 5 或更高版本（iOS 15+ 或 macOS 12+）。默认情况下，将创建 NeuralNetwork 模型，因为它需要 Core ML 3 或更高版本（iOS 13+ 或 macOS 10.15+）。

支持的运算符

NeuralNetwork

当创建 NeuralNetwork 模型（默认）时，CoreML 执行提供程序支持的运算符

运算符 注意
ai.onnx:Add  
ai.onnx:ArgMax  
ai.onnx:AveragePool 仅支持 2D 池化。
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 池化。
ai.onnx:GlobalMaxPool 仅支持 2D 池化。
ai.onnx:LeakyRelu  
ai.onnx:LRN  
ai.onnx:MatMul 输入 B 应为常量。
ai.onnx:MaxPool 仅支持 2D 池化。
ai.onnx:Mul  
ai.onnx:Pad 仅支持常量模式和最后两个维度填充。
输入 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 池化。如果需要，可以添加 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 池化。如果需要，可以添加 3D 和 5D 支持。
ai.onnx:GlobalMaxPool 目前仅支持 2D 池化。如果需要，可以添加 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 池化。如果需要，可以添加 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