CoreML Execution Provider
Core ML ist ein von Apple eingeführtes Machine-Learning-Framework. Es wurde entwickelt, um die leistungsstarke Hardwaretechnologie, einschließlich CPU, GPU und Neural Engine, auf effizienteste Weise nahtlos zu nutzen, um die Leistung zu maximieren und gleichzeitig den Speicher- und Stromverbrauch zu minimieren.
Inhalt
- Voraussetzungen
- Installieren
- Erstellen
- Verwendung
- Konfigurationsoptionen (NEUE API)
- Konfigurationsoptionen (Alte API)
- Unterstützte Operatoren
Voraussetzungen
Der CoreML Execution Provider (EP) erfordert iOS-Geräte mit iOS 13 oder höher oder Mac-Computer mit macOS 10.15 oder höher.
Es wird empfohlen, Apple-Geräte mit Apple Neural Engine für optimale Leistung zu verwenden.
Installieren
Vorkompilierte Binärdateien von ONNX Runtime mit CoreML EP für iOS werden über CocoaPods veröffentlicht.
Installationsanweisungen finden Sie hier.
Build
Anweisungen zum Erstellen für iOS-Geräte finden Sie unter Build für iOS.
Verwendung
Details zur ONNX Runtime API finden Sie hier.
Der CoreML EP kann über die C-, C++-, Objective-C-, C#- und Java-APIs verwendet werden.
Der CoreML EP muss beim Erstellen der Inferenzsitzung explizit registriert werden. Zum Beispiel
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);
Veraltet APIs OrtSessionOptionsAppendExecutionProvider_CoreML in ONNX Runtime 1.20.0. Bitte verwenden Sie stattdessen 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);
Konfigurationsoptionen (NEUE API)
Es stehen mehrere Laufzeitoptionen für den CoreML EP zur Verfügung.
Um die Laufzeitoptionen des CoreML EP zu nutzen, erstellen Sie eine vorzeichenlose Ganzzahl, die die Optionen darstellt, und setzen Sie jede einzelne Option mithilfe des bitweisen OR-Operators.
ProviderOptions können durch Übergabe einer Zeichenkette an die Methode AppendExecutionProvider gesetzt werden.
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);
Python-Inferenz-Beispielcode zur Verwendung der CoreML EP-Laufzeitoptionen
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)
Verfügbare Optionen (NEUE API)
ModelFormat kann einer der folgenden Werte sein: (Standardmäßig NeuralNetwork)
MLProgram: Erstellt ein Modell im MLProgram-Format. Erfordert Core ML 5 oder neuer (iOS 15+ oder macOS 12+).NeuralNetwork: Erstellt ein Modell im NeuralNetwork-Format. Erfordert Core ML 3 oder neuer (iOS 13+ oder macOS 10.15+).
MLComputeUnits kann einer der folgenden Werte sein: (Standardmäßig ALL)
CPUOnly: Beschränkt CoreML auf die Ausführung auf der CPU.CPUAndNeuralEngine: Aktiviert CoreML EP für Apple-Geräte mit einer kompatiblen Apple Neural Engine (ANE).CPUAndGPU: Aktiviert CoreML EP für Apple-Geräte mit einer kompatiblen GPU.ALL: Aktiviert CoreML EP für alle kompatiblen Apple-Geräte.
RequireStaticInputShapes kann einer der folgenden Werte sein: (Standardmäßig 0)
Erlaubt dem CoreML EP nur, Knoten mit Eingaben mit statischen Formen zu verarbeiten. Standardmäßig erlaubt der CoreML EP auch Eingaben mit dynamischen Formen, die Leistung kann jedoch durch Eingaben mit dynamischen Formen negativ beeinflusst werden.
0: Erlaubt dem CoreML EP, Knoten mit Eingaben mit dynamischen Formen zu verarbeiten.1: Erlaubt dem CoreML EP nur, Knoten mit Eingaben mit statischen Formen zu verarbeiten.
EnableOnSubgraphs kann einer der folgenden Werte sein: (Standardmäßig 0)
Ermöglicht dem CoreML EP die Ausführung auf einem Subgraphen im Körper eines Kontrollflussoperators (d. h. eines Loop, Scan oder If Operator).
0: Deaktiviert die Ausführung des CoreML EP auf einem Subgraphen im Körper eines Kontrollflussoperators.1: Aktiviert die Ausführung des CoreML EP auf einem Subgraphen im Körper eines Kontrollflussoperators.
SpecializationStrategy: Diese Funktion ist ab macOS >= 10.15 oder iOS >= 18.0 verfügbar. Dieser Prozess kann die Ladezeit des Modells und die Vorhersagelatenz beeinflussen. Verwenden Sie diese Option, um die Spezialisierungsstrategie für Ihr Modell anzupassen. Weitere Informationen finden Sie in der Apple-Dokumentation. Kann einer der folgenden Werte sein: (Standardmäßig Default)
Default:FastPrediction:
ProfileComputePlan: Profilert den Core ML MLComputePlan. Dies protokolliert die Hardware, an die jeder Operator gesendet wird, und die geschätzte Ausführungszeit. Dies ist für die Entwickler gedacht, liefert aber nützliche Diagnoseinformationen, wenn die Leistung nicht wie erwartet ausfällt. Kann einer der folgenden Werte sein: (Standardmäßig 0)
0: Profiling deaktivieren.1: Profiling aktivieren.
AllowLowPrecisionAccumulationOnGPU: siehe Apple Doc. Kann einer der folgenden Werte sein: (Standardmäßig 0)
0: Verwenden Sie den Datentyp float32 zur Akkumulation von Daten.1: Verwenden Sie Daten mit niedriger Präzision (float16) zur Akkumulation von Daten.
ModelCacheDirectory: Der Pfad zum Verzeichnis, in dem der Core ML-Modell-Cache gespeichert wird. CoreML EP kompiliert den erfassten Subgraphen in einen Graphen im CoreML-Format und speichert ihn auf der Festplatte. Für das gegebene Modell, wenn das Caching nicht aktiviert ist, kompiliert und speichert CoreML EP jedes Mal, was erhebliche Zeit (sogar Minuten) für ein kompliziertes Modell kosten kann. Durch Angabe eines Cache-Pfads kann das Modell im CoreML-Format wiederverwendet werden. (Cache standardmäßig deaktiviert).
"": Cache deaktivieren. (Standardmäßig leere Zeichenkette)"/path/to/cache": Cache aktivieren. (Pfad zum Cache-Verzeichnis, wird erstellt, falls nicht vorhanden)
Die zwischengespeicherten Informationen für das Modell werden unter einem Modell-Hash im Cache-Verzeichnis gespeichert. Es gibt drei Möglichkeiten, wie der Hash berechnet werden kann, in der Reihenfolge der Präferenz.
- Aus den Model-Metadaten-Props lesen. Dies gibt dem Benutzer eine Möglichkeit, den Hash direkt zu steuern und ist die empfohlene Verwendung. Der Cache-Schlüssel muss Folgendes erfüllen: (1) Der Wert darf nur alphanumerische Zeichen enthalten. (2) Länge des Werts < 64. EP wird den Cache-Schlüssel neu hashen, um diese Bedingungen zu erfüllen.
- Hash der Modell-URL, mit der die Inferenzsitzung erstellt wurde.
- Hash der Graphen-Eingaben und Knoten-Ausgaben, wenn die Inferenzsitzung mit In-Memory-Bytes erstellt wurde (d. h. es gab keinen Modellpfad).
Es ist entscheidend, dass sich der Hash-Wert ändert, wenn sich das Modell ändert, oder Sie müssen die vorherigen Cache-Informationen löschen. z. B. wenn die Modell-URL für den Hash verwendet wird (Option 2 oben), muss das aktualisierte Modell von einem anderen Pfad geladen werden, um den Hash-Wert zu ändern.
ONNX Runtime verfügt NICHT über einen Mechanismus zur Verfolgung von Modelländerungen und löscht die Cache-Einträge nicht.
Hier ist ein Beispiel, wie der Modell-Hash in den Metadaten des Modells eingetragen wird
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)
Konfigurationsoptionen (Alte API)
uint32_t coreml_flags = 0;
coreml_flags |= COREML_FLAG_ONLY_ENABLE_DEVICE_WITH_ANE;
Verfügbare Optionen (Veraltete API)
COREML_FLAG_USE_CPU_ONLY
Beschränkt CoreML auf die Ausführung auf der CPU.
Dies verringert die Leistung, liefert aber Referenzausgabewerte ohne Präzisionsverlust, was für die Validierung nützlich ist.
Nur für Entwickler gedacht.
COREML_FLAG_ENABLE_ON_SUBGRAPH
Ermöglicht dem CoreML EP die Ausführung auf einem Subgraphen im Körper eines Kontrollflussoperators (d. h. eines Loop, Scan oder If Operator).
COREML_FLAG_ONLY_ENABLE_DEVICE_WITH_ANE
Standardmäßig wird der CoreML EP für alle kompatiblen Apple-Geräte aktiviert.
Das Setzen dieser Option aktiviert den CoreML EP nur für Apple-Geräte mit einer kompatiblen Apple Neural Engine (ANE). Hinweis: Das Aktivieren dieser Option garantiert nicht, dass das gesamte Modell ausschließlich über ANE ausgeführt wird.
Weitere Informationen finden Sie unter Welche Geräte haben eine ANE?
COREML_FLAG_ONLY_ALLOW_STATIC_INPUT_SHAPES
Erlaubt dem CoreML EP nur, Knoten mit Eingaben mit statischen Formen zu verarbeiten. Standardmäßig erlaubt der CoreML EP auch Eingaben mit dynamischen Formen, die Leistung kann jedoch durch Eingaben mit dynamischen Formen negativ beeinflusst werden.
COREML_FLAG_CREATE_MLPROGRAM
Erstellt ein Modell im MLProgram-Format. Erfordert Core ML 5 oder neuer (iOS 15+ oder macOS 12+). Standardmäßig wird ein NeuralNetwork-Modell erstellt, da dies Core ML 3 oder neuer (iOS 13+ oder macOS 10.15+) erfordert.
Unterstützte Operatoren
NeuralNetwork
Operatoren, die vom CoreML Execution Provider unterstützt werden, wenn ein NeuralNetwork-Modell (Standard) erstellt wird
| Operator | Hinweis |
|---|---|
| ai.onnx:Add | |
| ai.onnx:ArgMax | |
| ai.onnx:AveragePool | Nur 2D-Pooling wird unterstützt. |
| ai.onnx:BatchNormalization | |
| ai.onnx:Cast | |
| ai.onnx:Clip | |
| ai.onnx:Concat | |
| ai.onnx:Conv | Nur 1D/2D Conv wird unterstützt. Gewichte und Bias müssen konstant sein. |
| ai.onnx:DepthToSpace | Nur die DCR-Modus-Tiefe-zu-Raum-Konvertierung wird unterstützt. |
| ai.onnx:Div | |
| ai.onnx:Flatten | |
| ai.onnx:Gather | Eingabe indices mit Skalarwert wird nicht unterstützt. |
| ai.onnx:Gemm | Eingabe B muss konstant sein. |
| ai.onnx:GlobalAveragePool | Nur 2D-Pooling wird unterstützt. |
| ai.onnx:GlobalMaxPool | Nur 2D-Pooling wird unterstützt. |
| ai.onnx:LeakyRelu | |
| ai.onnx:LRN | |
| ai.onnx:MatMul | Eingabe B muss konstant sein. |
| ai.onnx:MaxPool | Nur 2D-Pooling wird unterstützt. |
| ai.onnx:Mul | |
| ai.onnx:Pad | Nur Konstantmodus und Padding für die letzten beiden Dimensionen werden unterstützt. Eingabe-Pads und konstante Werte müssen konstant sein. Falls vorhanden, sollten Achsen konstant sein. |
| ai.onnx:Pow | Unterstützt nur Fälle, in denen beide Eingaben fp32 sind. |
| ai.onnx:PRelu | Eingabe-Slope muss konstant sein. Die Eingabe-Slope muss entweder die Form [C, 1, 1] haben oder 1 Element enthalten. |
| ai.onnx:Reciprocal | |
| ai.onnx.ReduceSum | |
| ai.onnx:Relu | |
| ai.onnx:Reshape | |
| ai.onnx:Resize | 4D-Eingabe.coordinate_transformation_mode == asymmetric.mode == linear oder nearest.nearest_mode == floor.exclude_outside == falsescales oder sizes müssen konstant sein. |
| ai.onnx:Shape | Attribut start mit einem nicht standardmäßigen Wert wird nicht unterstützt.Attribut end wird nicht unterstützt. |
| ai.onnx:Sigmoid | |
| ai.onnx:Slice | Eingaben starts, ends, axes und steps müssen Konstanten sein. Leeres Slice wird nicht unterstützt. |
| ai.onnx:Softmax | |
| ai.onnx:Split | Falls vorhanden, müssen splits konstant sein. |
| ai.onnx:Squeeze | |
| ai.onnx:Sqrt | |
| ai.onnx:Sub | |
| ai.onnx:Tanh | |
| ai.onnx:Transpose |
MLProgram
Operatoren, die vom CoreML Execution Provider unterstützt werden, wenn ein MLProgram-Modell (COREML_FLAG_CREATE_MLPROGRAM Flag ist gesetzt) erstellt wird
| Operator | Hinweis |
|---|---|
| ai.onnx:Add | |
| ai.onnx:Argmax | |
| ai.onnx:AveragePool | Nur 2D-Pooling wird derzeit unterstützt. 3D- und 5D-Unterstützung kann bei Bedarf hinzugefügt werden. |
| ai.onnx:Cast | |
| ai.onnx:Clip | |
| ai.onnx:Concat | |
| ai.onnx:Conv | Nur 1D/2D Conv wird unterstützt. Bias muss, falls vorhanden, konstant sein. |
| ai.onnx:ConvTranspose | Gewicht und Bias müssen konstant sein. padding_type von SAME_UPPER/SAME_LOWER wird nicht unterstützt. kernel_shape muss Standardwerte haben. output_shape wird nicht unterstützt. output_padding muss Standardwerte haben. |
| ai.onnx:DepthToSpace | Wenn 'mode' 'CRD' ist, muss die Eingabe eine feste Form haben. |
| ai.onnx:Div | |
| ai.onnx:Erf | |
| ai.onnx:Gemm | Eingabe B muss konstant sein. |
| ai.onnx:Gelu | |
| ai.onnx:GlobalAveragePool | Nur 2D-Pooling wird derzeit unterstützt. 3D- und 5D-Unterstützung kann bei Bedarf hinzugefügt werden. |
| ai.onnx:GlobalMaxPool | Nur 2D-Pooling wird derzeit unterstützt. 3D- und 5D-Unterstützung kann bei Bedarf hinzugefügt werden. |
| ai.onnx:GridSample | 4D-Eingabe. 'mode' von 'linear' oder 'zeros'. (mode==linear && padding_mode==reflection && align_corners==0) wird nicht unterstützt. |
| ai.onnx:GroupNormalization | |
| ai.onnx:InstanceNormalization | |
| ai.onnx:LayerNormalization | |
| ai.onnx:LeakyRelu | |
| ai.onnx:MatMul | Nur Unterstützung für transA == 0, alpha == 1.0 und beta == 1.0 ist derzeit implementiert. |
| ai.onnx:MaxPool | Nur 2D-Pooling wird derzeit unterstützt. 3D- und 5D-Unterstützung kann bei Bedarf hinzugefügt werden. |
| ai.onnx:Max | |
| ai.onnx:Mul | |
| ai.onnx:Pow | Unterstützt nur Fälle, in denen beide Eingaben fp32 sind. |
| ai.onnx:PRelu | |
| ai.onnx:Reciprocal | Dies fragt nach einem epislon (Standard 1e-4), das ONNX nicht bereitstellt |
| ai.onnx:ReduceSum | |
| ai.onnx:ReduceMean | |
| ai.onnx:ReduceMax | |
| ai.onnx:Relu | |
| ai.onnx:Reshape | |
| ai.onnx:Resize | Siehe resize_op_builder.cc Implementierung. Es gibt zu viele Permutationen, um die gültigen Kombinationen zu beschreiben. |
| ai.onnx:Round | |
| ai.onnx:Shape | |
| ai.onnx:Slice | starts/ends/axes/steps müssen konstante Initialisierer sein. |
| ai.onnx:Split | Falls vorhanden, müssen splits konstant sein. |
| ai.onnx:Sub | |
| ai.onnx:Sigmoid | |
| ai.onnx:Softmax | |
| ai.onnx:Sqrt | |
| ai.onnx:Squeeze | |
| ai.onnx:Tanh | |
| ai.onnx:Transpose | |
| ai.onnx:Unsqueeze |