/coreml

name: coreml
description: "Integrate Core ML models in iOS apps for on-device machine learning inference. Covers model loading (.mlmodel, .mlpackage, .mlmodelc), predictions with auto-generated classes and MLFeatureProvider, compute unit configuration (CPU, GPU, Neural Engine), MLTensor, VNCoreMLRequest, MLComputePlan, multi-model pipelines, and deployment strategies. Use when loading Core ML models, making predictions, configuring compute units, or profiling model performance."

Core ML Swift Integration

Load, configure, and run Core ML models in iOS apps. This skill covers the Swift side: model loading, prediction, MLTensor, profiling, and deployment.

> **Scope boundary:** Python-side model conversion, optimization (quantization, > palettization, pruning), and framework selection live in the `apple-on-device-ai` > skill. This skill owns Swift integration only.

See [references/coreml-swift-integration.md](references/coreml-swift-integration.md) for complete code patterns including actor-based caching, batch inference, image preprocessing, and testing.

Contents

• [Loading Models](#loading-models)
• [Model Configuration](#model-configuration)
• [Making Predictions](#making-predictions)
• [MLTensor (iOS 18+)](#mltensor-ios-18)
• [Working with MLMultiArray](#working-with-mlmultiarray)
• [Image Preprocessing](#image-preprocessing)
• [Multi-Model Pipelines](#multi-model-pipelines)
• [Vision Integration](#vision-integration)
• [Performance Profiling](#performance-profiling)
• [Model Deployment](#model-deployment)
• [Memory Management](#memory-management)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Loading Models

Auto-Generated Classes

When you add a `.mlmodel` or `.mlpackage` to an app target, Xcode generates a Swift class with typed input/output. Use this whenever possible.

import CoreML

let config = MLModelConfiguration()
config.computeUnits = .all

let model = try MyImageClassifier(configuration: config)

Manual Loading

Load from a URL when the model is downloaded at runtime or stored outside the bundle.

let modelURL = Bundle.main.url(
    forResource: "MyModel", withExtension: "mlmodelc"
)!
let model = try MLModel(contentsOf: modelURL, configuration: config)

Async Loading (iOS 15+)

Load models without blocking the main thread. Prefer this for large models.

let model = try await MLModel.load(
    contentsOf: modelURL,
    configuration: config
)

Compile at Runtime (iOS 16+)

Compile a `.mlpackage` or `.mlmodel` to `.mlmodelc` on device. Useful for models downloaded from a server. Do this once per model version, not on every launch.

let compiledURL = try await MLModel.compileModel(at: packageURL)
let model = try await MLModel.load(contentsOf: compiledURL, configuration: config)

Cache the compiled URL -- recompiling on every launch is a bug. Copy `compiledURL` to a persistent location (e.g., Application Support). When reviewing runtime-loaded models, call out both facts together: async `MLModel.compileModel(at:)` is iOS 16+, and compiled models must be cached so the app does not recompile on every launch.

Model Configuration

`MLModelConfiguration` controls compute units, GPU access, and model parameters.

Compute Units Decision Table

| Value | Uses | When to Choose | |---|---|---| | `.all` | CPU + GPU + Neural Engine | Default. Let the system decide. | | `.cpuOnly` | CPU | Deterministic tests, CPU-only fallbacks, or constrained work after profiling shows accelerator policy, contention, thermal state, or energy budget is the limiting factor. | | `.cpuAndGPU` | CPU + GPU | Need GPU but model has ops unsupported by ANE. | | `.cpuAndNeuralEngine` (iOS 16+) | CPU + Neural Engine | Best energy efficiency for compatible models. |

let config = MLModelConfiguration()
config.computeUnits = .cpuAndNeuralEngine

// Optional fallback for constrained work after profiling and policy review
config.computeUnits = .cpuOnly

Configuration Properties

let config = MLModelConfiguration()
config.computeUnits = .all
config.allowLowPrecisionAccumulationOnGPU = true // faster, slight precision loss

Making Predictions

With Auto-Generated Classes

The generated class provides typed input/output structs.

let model = try MyImageClassifier(configuration: config)
let input = MyImageClassifierInput(image: pixelBuffer)
let output = try model.prediction(input: input)
print(output.classLabel)        // "golden_retriever"
print(output.classLabelProbs)   // ["golden_retriever": 0.95, ...]

With MLDictionaryFeatureProvider

Use when inputs are dynamic or not known at compile time.

let inputFeatures = try MLDictionaryFeatureProvider(dictionary: [
    "image": MLFeatureValue(pixelBuffer: pixelBuffer),
    "confidence_threshold": MLFeatureValue(double: 0.5),
])
let output = try model.prediction(from: inputFeatures)
let label = output.featureValue(for: "classLabel")?.stringValue

Prediction Inside Async Workflows

`MLModel.prediction(...)` is synchronous. In async pipelines, keep model loading async, then run prediction from an actor or non-main task without adding `await` to the prediction call.

let output = try model.prediction(from: inputFeatures)

Batch Prediction

Process multiple inputs in one call for better throughput.

let batchInputs = try MLArrayBatchProvider(array: inputs.map { input in
    try MLDictionaryFeatureProvider(dictionary: ["image": MLFeatureValue(pixelBuffer: input)])
})
let batchOutput = try model.predictions(fromBatch: batchInputs)
for i in 0..<batchOutput.count {
    let result = batchOutput.features(at: i)
    print(result.featureValue(for: "classLabel")?.stringValue ?? "unknown")
}

Use `predictions(fromBatch:)` when batching without explicit `MLPredictionOptions`. Use `predictions(from:options:)` only when passing both an `MLBat