Integración de Core ML con Swift
Carga, configura y ejecuta modelos Core ML en aplicaciones iOS. Este skill cubre el lado de Swift: carga de modelos, predicción, MLTensor, creación de perfiles e implementación. Está dirigido a iOS 26+ con Swift 6.3, con compatibilidad hacia atrás hasta iOS 14 a menos que se indique lo contrario.
Límite del alcance: La conversión de modelos del lado de Python, la optimización (cuantización, paletización, poda) y la selección de frameworks residen en el skill
apple-on-device-ai. Este skill solo se encarga de la integración con Swift.
Consulta references/coreml-swift-integration.md para patrones de código completos que incluyen caché basada en actores, inferencia por lotes, preprocesamiento de imágenes y pruebas.
Contenido
- Carga de Modelos
- Configuración del Modelo
- Realización de Predicciones
- MLTensor (iOS 18+)
- Trabajo con MLMultiArray
- Preprocesamiento de Imágenes
- Pipelines de Múltiples Modelos
- Integración con Vision
- Creación de Perfiles de Rendimiento
- Implementación del Modelo
- Gestión de la Memoria
- Errores Comunes
- Lista de Verificación de Revisión
- Referencias
Carga de Modelos
Clases Autogeneradas
Cuando arrastras un .mlpackage o .mlmodelc a Xcode, este genera una clase Swift
con entradas/salidas tipadas. Úsala siempre que sea posible.
import CoreML
let config = MLModelConfiguration()
config.computeUnits = .all
let model = try MyImageClassifier(configuration: config)
Carga Manual
Carga desde una URL cuando el modelo se descarga en tiempo de ejecución o se almacena fuera del paquete.
let modelURL = Bundle.main.url(
forResource: "MyModel", withExtension: "mlmodelc"
)!
let model = try MLModel(contentsOf: modelURL, configuration: config)
Carga Asíncrona (iOS 16+)
Carga modelos sin bloquear el hilo principal. Prefiere esto para modelos grandes.
let model = try await MLModel.load(
contentsOf: modelURL,
configuration: config
)
Compilar en Tiempo de Ejecución
Compila un .mlpackage o .mlmodel a .mlmodelc en el dispositivo. Útil para
modelos descargados desde un servidor.
let compiledURL = try await MLModel.compileModel(at: packageURL)
let model = try MLModel(contentsOf: compiledURL, configuration: config)
Almacena en caché la URL compilada: recompilar en cada inicio desperdicia tiempo.
Copia compiledURL a una ubicación persistente (por ejemplo, Application Support).
Configuración del Modelo
MLModelConfiguration controla las unidades de cómputo, el acceso a la GPU y los parámetros del modelo.
Tabla de Decisión de Unidades de Cómputo
| Valor | Usa | Cuándo Elegir |
|---|---|---|
.all | CPU + GPU + Neural Engine | Valor predeterminado. Deja que el sistema decida. |
.cpuOnly | CPU | Tareas en segundo plano, sesiones de audio o cuando la GPU está ocupada. |
.cpuAndGPU | CPU + GPU | Necesitas GPU pero el modelo tiene operaciones no compatibles con ANE. |
.cpuAndNeuralEngine | CPU + Neural Engine | Mejor eficiencia energética para modelos compatibles. |
let config = MLModelConfiguration()
config.computeUnits = .cpuAndNeuralEngine
// Permitir inferencia en segundo plano de baja prioridad
config.computeUnits = .cpuOnly
Propiedades de Configuración
let config = MLModelConfiguration()
config.computeUnits = .all
config.allowLowPrecisionAccumulationOnGPU = true // más rápido, ligera pérdida de precisión
Realización de Predicciones
Con Clases Autogeneradas
La clase generada proporciona estructuras de entrada/salida tipadas.
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, ...]
Con MLDictionaryFeatureProvider
Úsalo cuando las entradas sean dinámicas o no se conozcan en tiempo de compilación.
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
Predicción Asíncrona (iOS 17+)
let output = try await model.prediction(from: inputFeatures)
Predicción por Lotes
Procesa múltiples entradas en una sola llamada para un mejor rendimiento.
let batchInputs = try MLArrayBatchProvider(array: inputs.map { input in
try MLDictionaryFeatureProvider(dictionary: ["image": MLFeatureValue(pixelBuffer: input)])
})
let batchOutput = try model.predictions(from: batchInputs)
for i in 0..<batchOutput.count {
let result = batchOutput.features(at: i)
print(result.featureValue(for: "classLabel")?.stringValue ?? "unknown")
}
Predicción con Estado (iOS 18+)
Usa MLState para modelos que mantienen el estado entre predicciones (modelos de secuencia,
LLMs, acumuladores de audio). Crea el estado una vez y pásalo a cada llamada de predicción.
let state = model.makeState()
// Cada predicción lleva adelante el estado interno del modelo
for frame in audioFrames {
let input = try MLDictionaryFeatureProvider(dictionary: [
"audio_features": MLFeatureValue(multiArray: frame)
])
let output = try await model.prediction(from: input, using: state)
let classification = output.featureValue(for: "label")?.stringValue
}
El estado no es Sendable: úsalo desde un único actor o tarea.
Llama a model.makeState() para crear estados independientes para flujos concurrentes.
MLTensor (iOS 18+)
MLTensor es un array multidimensional nativo de Swift para pre/post procesamiento.
Las operaciones se ejecutan de forma perezosa: llama a .shapedArray(of:) para materializar los resultados.
import CoreML
// Creación
let tensor = MLTensor([1.0, 2.0, 3.0, 4.0])
let zeros = MLTensor(zeros: [3, 224, 224], scalarType: Float.self)
// Cambio de forma
let reshaped = tensor.reshaped(to: [2, 2])
// Operaciones matemáticas
let softmaxed = tensor.softmax()
let normalized = (tensor - tensor.mean()) / tensor.standardDeviation()
// Interoperabilidad con MLMultiArray
let multiArray = try MLMultiArray([1.0, 2.0, 3.0, 4.0])
let fromMultiArray = MLTensor(multiArray)
let backToArray = tensor.shapedArray(of: Float.self)
Trabajo con MLMultiArray
MLMultiArray es el tipo de intercambio de datos principal para entradas y salidas de modelos que no son imágenes.
Úsalo cuando la clase autogenerada espere características de tipo array.
// Crear un array 3D: [lote, secuencia, características]
let array = try MLMultiArray(shape: [1, 128, 768], dataType: .float32)
// Escribir valores
for i in 0..<128 {
array[[0, i, 0] as [NSNumber]] = NSNumber(value: Float(i))
}
// Leer valores
let value = array[[0, 0, 0] as [NSNumber]].floatValue
// Crear desde un puntero de datos para interoperabilidad sin copia
let data: [Float] = [1.0, 2.0, 3.0]
let fromData = try MLMultiArray(dataPointer: UnsafeMutableRawPointer(mutating: data),
shape: [3],
dataType: .float32,
strides: [1])
Consulta references/coreml-swift-integration.md para patrones avanzados de MLMultiArray que incluyen tokenización de NLP y extracción de características de audio.
Preprocesamiento de Imágenes
Los modelos de imágenes esperan entrada CVPixelBuffer. Usa la conversión CGImage para fotos
de la cámara o la biblioteca de fotos. Vision's VNCoreMLRequest maneja esto
automáticamente; la conversión manual solo es necesaria para la predicción directa de MLModel.
import CoreVideo
func createPixelBuffer(from cgImage: CGImage, width: Int, height: Int) -> CVPixelBuffer? {
var pixelBuffer: CVPixelBuffer?
let attrs: [CFString: Any] = [
kCVPixelBufferCGImageCompatibilityKey: true,
kCVPixelBufferCGBitmapContextCompatibilityKey: true,
]
CVPixelBufferCreate(kCFAllocatorDefault, width, height,
kCVPixelFormatType_32ARGB, attrs as CFDictionary, &pixelBuffer)
guard let buffer = pixelBuffer else { return nil }
CVPixelBufferLockBaseAddress(buffer, [])
let context = CGContext(
data: CVPixelBufferGetBaseAddress(buffer),
width: width, height: height,
bitsPerComponent: 8, bytesPerRow: CVPixelBufferGetBytesPerRow(buffer),
space: CGColorSpaceCreateDeviceRGB(),
bitmapInfo: CGImageAlphaInfo.noneSkipFirst.rawValue
)
context?.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
CVPixelBufferUnlockBaseAddress(buffer, [])
return buffer
}
Para patrones adicionales de preprocesamiento (normalización, recorte centrado), consulta references/coreml-swift-integration.md.
Pipelines de Múltiples Modelos
Encadena modelos cuando el preprocesamiento o posprocesamiento requiera un modelo separado.
// Inferencia secuencial: preprocesador -> modelo principal -> posprocesador
let preprocessed = try preprocessor.prediction(from: rawInput)
let mainOutput = try mainModel.prediction(from: preprocessed)
let finalOutput = try postprocessor.prediction(from: mainOutput)
Para pipelines gestionados por Xcode, usa el tipo de modelo de pipeline en el .mlpackage.
Cada submodelo se ejecuta en su unidad de cómputo óptima.
Integración con Vision
Usa Vision para ejecutar modelos de imágenes de Core ML con preprocesamiento automático de imágenes (redimensionamiento, normalización, espacio de color, orientación).
Moderno: CoreMLRequest (iOS 18+)
import Vision
import CoreML
let model = try MLModel(contentsOf: modelURL, configuration: config)
let request = CoreMLRequest(model: .init(model))
let results = try await request.perform(on: cgImage)
if let classification = results.first as? ClassificationObservation {
print("\(classification.identifier): \(classification.confidence)")
}
Heredado: VNCoreMLRequest
let vnModel = try VNCoreMLModel(for: model)
let request = VNCoreMLRequest(model: vnModel) { request, error in
guard let results = request.results as? [VNRecognizedObjectObservation] else { return }
for observation in results {
let label = observation.labels.first?.identifier ?? "unknown"
let confidence = observation.labels.first?.confidence ?? 0
let boundingBox = observation.boundingBox // coordenadas normalizadas
print("\(label): \(confidence) at \(boundingBox)")
}
}
request.imageCropAndScaleOption = .scaleFill
let handler = VNImageRequestHandler(cvPixelBuffer: pixelBuffer)
try handler.perform([request])
Para patrones completos del framework Vision (reconocimiento de texto, detección de códigos de barras, escaneo de documentos), consulta el skill
vision-framework.
Creación de Perfiles de Rendimiento
MLComputePlan (iOS 17.4+)
Inspecciona qué dispositivo de cómputo usará cada operación antes de ejecutar las predicciones.
let computePlan = try await MLComputePlan.load(
contentsOf: modelURL, configuration: config
)
guard case let .program(program) = computePlan.modelStructure else { return }
guard let mainFunction = program.functions["main"] else { return }
for operation in mainFunction.block.operations {
let deviceUsage = computePlan.deviceUsage(for: operation)
let estimatedCost = computePlan.estimatedCost(of: operation)
print("\(operation.operatorName): \(deviceUsage?.preferredComputeDevice ?? "unknown")")
}
Instruments
Usa la plantilla de instrumento Core ML en Instruments para perfilar:
- Tiempo de carga del modelo
- Latencia de predicción (desglose por operación)
- Asignación de dispositivos de cómputo (CPU/GPU/ANE por operación)
- Asignación de memoria
Ejecuta fuera del depurador para obtener resultados precisos (Xcode: Product > Profile).
Implementación del Modelo
Paquete vs Recursos Bajo Demanda
| Estrategia | Ventajas | Desventajas |
|---|---|---|
| Incluir en el paquete | Disponibilidad inmediata, funciona sin conexión | Aumenta el tamaño de descarga de la aplicación |
| Recursos bajo demanda | Descarga inicial más pequeña | Requiere descarga antes del primer uso |
| Background Assets (iOS 16+) | Descarga anticipada | Configuración más compleja |
| CloudKit / servidor | Máxima flexibilidad | Requiere red, configuración más larga |
Consideraciones de Tamaño
- Límite de App Store: 4 GB para el paquete de la aplicación
- Límite de descarga celular: 200 MB (se puede solicitar una excepción)
- Usa etiquetas ODR para modelos > 50 MB
- Precompila a
.mlmodelcpara evitar la compilación en el dispositivo
// Carga de recursos bajo demanda
let request = NSBundleResourceRequest(tags: ["ml-model-v2"])
try await request.beginAccessingResources()
let modelURL = Bundle.main.url(forResource: "LargeModel", withExtension: "mlmodelc")!
let model = try await MLModel.load(contentsOf: modelURL, configuration: config)
// Llama a request.endAccessingResources() cuando termines
Gestión de la Memoria
- Descargar en segundo plano: Libera las referencias al modelo cuando la aplicación entra en segundo plano para liberar memoria de GPU/ANE. Vuelve a cargar al regresar al primer plano.
- Usa
.cpuOnlypara tareas en segundo plano: El procesamiento en segundo plano no puede usar GPU o ANE; establecer.cpuOnlyevita la degradación silenciosa y la contención de recursos. - Comparte instancias de modelo: Nunca crees múltiples instancias de
MLModela partir del mismo modelo compilado. Usa un actor para proporcionar acceso compartido. - Monitorea la presión de memoria: Los modelos grandes (>100 MB) pueden activar advertencias de memoria.
Regístrate para
UIApplication.didReceiveMemoryWarningNotificationy libera los modelos en caché cuando haya presión.
Consulta references/coreml-swift-integration.md para un gestor de modelos basado en actores con carga consciente del ciclo de vida y expulsión de caché.
Errores Comunes
NO HAGAS: Cargar modelos en el hilo principal.
HACER: Usa la API asíncrona MLModel.load(contentsOf:configuration:) o carga en un actor de fondo.
Por qué: Los modelos grandes pueden tardar segundos en cargarse, congelando la interfaz de usuario.
NO HAGAS: Recompilar .mlpackage a .mlmodelc en cada inicio de la aplicación.
HACER: Compila una vez con MLModel.compileModel(at:) y almacena en caché la URL compilada de forma persistente.
Por qué: La compilación es costosa. Almacena en caché el .mlmodelc en Application Support.
NO HAGAS: Codificar .cpuOnly a menos que tengas una razón específica.
HACER: Usa .all y deja que el sistema elija la unidad de cómputo óptima.
...