Adaptadores personalizados de Foundation Models: cuándo entrenar uno

La documentación de adaptadores de Apple define el camino con precisión: usa el modelo base del sistema para la mayoría de los casos de ingeniería de prompts, generación guiada y herramientas; entrena un Adapter personalizado solo cuando la tarea requiera especialización de los pesos del modelo y el equipo se sienta cómodo entrenando modelos fundacionales en Python.¹⁴

La propia documentación de Apple sobre el mismo tipo dice textualmente: “Adapters consume a large amount of storage space and isn’t recommended for most apps.”¹ El artículo anterior de este grupo, Casos de uso de Foundation Models, cubrió los rieles que la mayoría de las apps debería seguir. Este artículo es el tercer riel: el ciclo de vida operativo de entrenar, empaquetar y distribuir un adaptador personalizado, y la guía explícita de Apple sobre cuándo no hacerlo.

TL;DR

• El toolkit de Apple identifica el método de entrenamiento como LoRA: los pesos base permanecen congelados mientras se entrenan los pesos del adaptador.²
• Cada adaptador está vinculado a una única versión del modelo del sistema. Cuando Apple actualiza el modelo base, vuelves a entrenar el adaptador.³
• La recomendación de Apple, en sus palabras: “Use the base system model for most prompt engineering, guided generation, and tools. If you need to specialize the model, train a custom Adapter… Use custom adapters only if you’re comfortable training foundation models in Python.”¹
• Los archivos de adaptador son grandes, no deberían incluirse en el paquete principal de la app y se entregan a demanda mediante asset packs alojados y Background Assets.²³
• Apple dice que solo consideres usar adaptadores cuando la ingeniería de prompts o las llamadas a herramientas no resuelvan la tarea, o cuando un servidor ya ajustado LLM, la experiencia en una materia, la adherencia a un estilo/formato/política o un objetivo de latencia justifiquen el costo.²

Qué es realmente un adaptador

SystemLanguageModel.Adapter es un struct, disponible en iOS, iPadOS, Mac Catalyst, macOS y visionOS, todos en versión 26.0+.⁴ La descripción del tipo según Apple:

“Use the base system model for most prompt engineering, guided generation, and tools. If you need to specialize the model, train a custom Adapter to alter the system model weights and optimize it for your custom task. Use custom adapters only if you’re comfortable training foundation models in Python.”⁴

El mecanismo está documentado. La guía de entrenamiento de adaptadores de Apple lo plantea directamente:²

“The system model uses a parameter-efficient fine-tuning (PEFT) approach known as LoRA (Low-Rank Adaptation). In LoRA, the original model weights are frozen, and small trainable weight matrices called ‘adapters’ are embedded through the model’s network. During training, only adapter weights are updated, significantly reducing the number of parameters to train.”

LoRA es una técnica pública con un historial de papers publicados.⁵ La superficie documentada de Apple es el toolkit, la exportación a .fmadapter, el empaquetado en asset packs, la entrega mediante Background Assets y la carga en tiempo de ejecución a través de SystemLanguageModel.Adapter.²³⁴

La superficie API del tipo

Apple lista esta superficie de Adapter:⁴

• init(fileURL: URL) throws: “Creates an adapter from the file URL.”
• init(name: String) throws: “Creates an adapter downloaded from the background assets framework.”
• func compile() async throws: “Prepares an adapter before being used with a LanguageModelSession. You should call this if your adapter has a draft model.”
• var creatorDefinedMetadata: [String : Any]: “Values read from the creator defined field of the adapter’s metadata.”
• static func removeObsoleteAdapters() throws: “Remove all obsolete adapters that are no longer compatible with current system models.”
• static func compatibleAdapterIdentifiers(name: String) -> [String]: “Get all compatible adapter identifiers compatible with current system models.”
• enum AssetError: tipo de error para fallos relacionados con assets.

SystemLanguageModel tiene un inicializador asociado para adaptadores: convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails), con la descripción “Creates the base version of the model with an adapter.”⁶

La clave de autorización exclusiva para despliegue es com.apple.developer.foundation-model-adapter: “A Boolean value that indicates whether the app can enable custom adapters for the Foundation Models framework.”⁶ No la necesitas para entrenar ni para pruebas locales en Xcode; sí la necesitas antes de publicar en la App Store.³

La rúbrica de Apple sobre “cuándo considerar un adaptador”

La página del toolkit expone señales concretas de adopción:²

• “You have a dataset suitable for use with an LLM” o ya usas un servidor con un LLM ajustado y quieres paridad en el dispositivo.
• “You need the model to become a subject-matter expert.”
• “You need the model to adhere to a specific style, format, or policy.”
• “Prompt engineering isn’t achieving the required accuracy or consistency for your task.”
• “You want lower latency at inference. If your prompt-engineered solutions require lengthy prompts with examples for every call, an adapter specialized for that task offers minimal prompting.”

La misma guía también lista los costos que asumes:²

• Un dataset de pares prompt y respuesta que demuestre la habilidad objetivo.
• Un proceso para evaluar la calidad de tus adaptadores.
• Un proceso para cargar tus adaptadores en tu app desde un servidor.

Y el impuesto de almacenamiento: “Each adapter will take approximately 160 MB of storage space in your app. Like other big assets, adapters shouldn’t be part of your app’s main bundle because with multiple adapter versions your app will become too big for people to install.”²

La recomendación del framework, repetida por Apple en dos lugares distintos, es ir por defecto a la ingeniería de prompts más las llamadas a herramientas, y recurrir a los adaptadores solo cuando la rúbrica anterior se cumpla.

Entrenamiento, según el modelo de Apple

Apple dice que el toolkit contiene código de muestra en Python, assets del modelo para una versión específica del modelo del sistema, utilidades de exportación a .fmadapter y utilidades de empaquetado en asset packs.²

Los requisitos del dataset son pares prompt/respuesta en jsonl, aproximadamente 100-1.000 muestras para tareas básicas y más de 5.000 para tareas complejas. Schema.md cubre la generación guiada y los campos de seguridad de IA.²

Requisitos de hardware: “Mac with Apple silicon and at least 32GB memory, or Linux GPU machines.” Python 3.11 o posterior.²

La regla de calidad de datos de Apple es simple: la calidad supera a la cantidad.²

El entrenamiento se invoca desde el punto de entrada train_adapter del toolkit:

python -m examples.train_adapter \
  --train-data /path/to/train.jsonl \
  --eval-data /path/to/valid.jsonl \
  --epochs 5 \
  --learning-rate 1e-3 \
  --batch-size 4 \
  --checkpoint-dir /path/to/my_checkpoints/

Opcionalmente, después de entrenar el adaptador, puedes entrenar un draft model que lo acompañe.² Un draft model es una versión más pequeña del modelo base del sistema que habilita la decodificación especulativa, una técnica publicada de aceleración de inferencia.⁷ La forma en que Apple lo plantea: “If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.”²

La restricción de versión única

El hecho operativamente más consecuente sobre los adaptadores es su vinculación a una versión específica del modelo del sistema:³

“Each adapter is compatible with a single specific system model version. You must train a new adapter for every new base model version. A runtime error occurs if your app runs on a person’s device without a compatible adapter.”

Consultada el 4 de mayo de 2026, la tabla del toolkit de Apple lista Beta 0.1.0 y Beta 0.2.0 como retiradas, y la 26.0.0 como la primera versión completa del toolkit. La regla de cadencia de Apple es un toolkit por cada actualización del modelo del sistema.² Declaración completa: “A new toolkit will be released for every system model update. The system model is shared across iOS, macOS, and visionOS, and system model updates will occur as part of those platforms’ OS updates (though not every OS update will have a model update).”²

La implicación operativa: los equipos de apps que distribuyen adaptadores se suscriben a un ciclo de actualización del modelo que corre al ritmo de Apple. Cada actualización del modelo base es una función forzante para reentrenar, reevaluar y republicar.

Empaquetado como asset packs

La regla de Apple: los archivos de adaptador son demasiado grandes para el paquete de la app; alójalos a través de App Store Connect o de tu propio servidor, y luego descarga el adaptador compatible con el dispositivo a demanda.³

El toolkit produce paquetes .fmadapter, que el toolkit también empaqueta como asset packs de Background Assets. La herramienta de línea de comandos ba-package de Xcode 16 o posterior hace el trabajo de empaquetado; el toolkit la invoca.³

Opciones de hospedaje:³

• Alojado por Apple, gestionado. Apple aloja el asset; el sistema operativo gestiona el ciclo de vida de la descarga.
• Autoalojado, gestionado. Tú alojas en tu servidor; el sistema operativo gestiona el ciclo de vida de la descarga.
• Autoalojado, no gestionado. Alojas y gestionas el ciclo de vida tú mismo.

Las claves Info.plist requeridas varían según la opción de hospedaje:³ el modelo Apple-Hosted Managed necesita BAHasManagedAssetPacks, BAAppGroupID y BAUsesAppleHosting; Self-Hosted Managed necesita las dos primeras; Self-Hosted Unmanaged no necesita ninguna. Cada ruta tiene también un objetivo de extensión de descarga de assets que Xcode genera.

Elegir el adaptador correcto en tiempo de ejecución

Cuando se genera el archivo BackgroundDownloadHandler.swift de la extensión de descarga de assets, Xcode conecta un callback shouldDownload(_:). El cuerpo de ejemplo de Apple para los assets de adaptador:³

func shouldDownload(_ assetPack: AssetPack) -> Bool {
    if assetPack.id.hasPrefix("mygameshader") {
        return true
    }
    return SystemLanguageModel.Adapter.isCompatible(assetPack)
}

La muestra de Apple es la única verificación documentada en tiempo de ejecución. La expresión SystemLanguageModel.Adapter.isCompatible(assetPack) es lo que la muestra retorna para los asset packs de adaptador; trata la llamada como opaca más allá de lo que muestra el ejemplo.³

Carga y seguimiento de descargas

Una vez que el asset está en el dispositivo, la ruta de carga es:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

let adapter = try SystemLanguageModel.Adapter(name: "myAdapter")

La construcción dispara una descarga si el dispositivo no tiene un adaptador compatible en caché. La nota de Apple sobre la experiencia de usuario: “Because adapters can have a large data size they can take some time to download, especially if a person is on Wi-Fi or a cell network. If a person doesn’t have a network connection, they aren’t able to use your adapter right away.”³

La secuencia de estados proviene de AssetPackManager:³

let assetpackIDList = SystemLanguageModel.Adapter.compatibleAdapterIdentifiers(name: name)
if let assetPackID = assetpackIDList.first {
    let statusUpdates = AssetPackManager.shared.statusUpdates(forAssetPackWithID: assetPackID)
    for await status in statusUpdates {
        switch status {
        case .began(let assetPack): ...
        case .paused(let assetPack): ...
        case .downloading(let assetPack, let progress): ...
        case .finished(let assetPack): ...
        case .failed(let assetPack, let error): ...
        @unknown default: ...
        }
    }
}

Los cinco casos documentados de DownloadStatusUpdate: .began, .paused, .downloading, .finished, .failed.³ La rama @unknown default del framework es obligatoria porque Apple puede agregar casos en futuras versiones de SDK.

Después de que el estado llegue a .finished, el adaptador está listo para conectarse a una sesión:

let adaptedModel = SystemLanguageModel(adapter: adapter)
let session = LanguageModelSession(model: adaptedModel)

El draft model y su límite de tasa

Si tu adaptador se distribuyó con un draft model, llamar a adapter.compile() lo prepara para ser usado. La documentación de Apple lo señala como un paso separado y costoso en términos computacionales:³

“The first time a device downloads a new version of your adapter, a call to compile() fully compiles your draft model and saves it to the device. During subsequent launches of your app, a call to compile() checks for a saved compiled draft model and returns it immediately if it exists.”

Hay un límite de tasa publicado:³

“Rate limiting protects device resources that are shared between all apps and processes. If the framework determines that a new compilation is necessary, it rate-limits the compilation process on all platforms, excluding macOS, to three draft model compilations per-app, per-day.”

El límite de tasa excluye a macOS; en otras plataformas, la nueva compilación de draft model está limitada a tres compilaciones por app por día.³ Apple recomienda ejecutar la compilación dentro de una tarea programada con Background Tasks, para que el trabajo no bloquee el lanzamiento de la app.³

La advertencia de Apple sobre las pruebas en Xcode: lanzar a través de Xcode cambia el UUID de la app, por lo que la compilación completa se ejecuta en cada lanzamiento y puede activar el límite de tasa.³

Pruebas y la restricción del simulador

La prueba de adaptadores requiere un dispositivo físico. Apple es explícito: “Testing adapters requires a physical device and isn’t supported on Simulator.”³

Para pruebas locales en Xcode, inicializas desde una URL de archivo en lugar de un nombre:³

let localURL = URL(filePath: "absolute/path/to/my_adapter.fmadapter")
let adapter = try SystemLanguageModel.Adapter(fileURL: localURL)

Para publicar, Apple dice que importes archivos de adaptador solo para pruebas locales, los elimines antes del lanzamiento y descargues los adaptadores a demanda.³

Lo que este camino te cuesta en términos operativos

Juntando el ciclo de vida, una app que distribuye un adaptador personalizado se compromete con:

1. Infraestructura de entrenamiento de Python. Una Mac con Apple silicon y al menos 32 GB de memoria, o una máquina Linux GPU.²
2. Una cadencia de reentrenamiento marcada por Apple. Cada actualización del modelo del sistema implica un nuevo adaptador y una nueva versión del toolkit.³
3. Una infraestructura de servicio. Asset packs alojados por Apple a través de App Store Connect, o tu propio servidor ejecutando una integración de descarga de assets.³
4. Adaptadores por versión en almacenamiento. Múltiples versiones del modelo base en circulación significa múltiples adaptadores alojados, con el dispositivo descargando el correspondiente.³
5. Una puerta de autorización. El Account Holder de tu membresía del Apple Developer Program la solicita; no puedes publicar sin aprobación.²
6. El impuesto de 160 MB por versión de adaptador. No en el paquete de la app, sino en el dispositivo del usuario después de la descarga.²
7. Pruebas en dispositivo físico. El simulador no ejecuta adaptadores.³

Ese es el costo operativo en su forma más directa. El beneficio, cuando las señales de adopción se cumplen, es: el modelo en el dispositivo se especializa para la tarea con un mínimo de prompting y menor latencia. Para apps que ya pagan por inferencia ajustada en servidor y quieren paridad en el dispositivo, ese es el intercambio en términos directos.

Conclusiones

1. Los adaptadores son LoRA, según la técnica documentada por Apple. Pesos base congelados, pequeñas matrices entrenables a través de la red del modelo, solo se actualizan los pesos del adaptador durante el entrenamiento.²
2. Un adaptador por versión del modelo del sistema, sin excepciones. Planifica el reentrenamiento atado a los lanzamientos del SO.³
3. El flujo .fmadapter es de extremo a extremo. Entrenar en Python, empaquetar con el toolkit, alojar como un asset pack de Background Assets, cargar por nombre en tu app, compilar el draft model en una tarea en segundo plano.
4. La propia Apple recomienda que la mayoría de las apps no tomen este camino. Dos páginas distintas de la documentación de Apple lo desaconsejan para la mayoría de los casos de uso.¹ Lee la rúbrica en la página del toolkit; la respuesta por defecto es “no”.
5. Prueba en hardware. El simulador no ejecuta adaptadores. Construye el plan de pruebas en torno a sesiones en dispositivo físico y la franja de compilación del framework Background Tasks.

El grupo completo del ecosistema Apple: la rúbrica de decisión para la especialización integrada; el protocolo Tool en el núcleo del framework; la división del flujo de trabajo agéntico entre LLMs en la app y de tooling; App Intents vs MCP para la pregunta más amplia de enrutamiento. El hub está en la serie del ecosistema Apple. Para un contexto más amplio sobre iOS con agentes de IA, consulta la guía de desarrollo de agentes iOS.

Preguntas frecuentes

¿Cómo sé si mi app realmente necesita un adaptador personalizado?

Apple recomienda el modelo base para la mayoría de los casos de ingeniería de prompts, generación guiada y herramientas, y la guía del toolkit dice que los adaptadores tienen requisitos elevados de entrenamiento y reentrenamiento. La respuesta por defecto es no, a menos que apliquen las señales de adaptador de Apple.²⁴

¿Qué bloquea realmente la autorización?

Apple documenta la autorización como requerida al desplegar adaptadores, no para entrenar ni para pruebas locales.²³

¿Qué tamaño tienen los adaptadores y dónde se almacenan?

El número documentado por Apple: “Each adapter will take approximately 160 MB of storage space in your app.”² Los adaptadores no viven en el paquete de la app. Apple los enruta a través de Background Assets, alojados ya sea en servidores de Apple (gestionado) o en tu propio servidor (gestionado o no gestionado), y el dispositivo descarga la versión que corresponde a su modelo del sistema actual.³

¿Qué pasa cuando Apple actualiza el modelo base?

Cuando Apple actualiza el modelo base, entrena un adaptador compatible con esa versión del modelo; de lo contrario, la app puede generar un error en tiempo de ejecución en un dispositivo sin un adaptador compatible.²³

¿Cuál es la relación entre los adaptadores y .contentTagging?

.contentTagging lo gestiona Apple y está integrado en el framework: un caso de uso especializado internamente, no el tipo formal Adapter que entrena un desarrollador. El tipo formal es lo que cubre este artículo; los casos de uso se cubren en el artículo complementario.

¿Tengo que entrenar un draft model?

Apple solo documenta esta consecuencia de omitir el entrenamiento del draft model: la decodificación especulativa no estará disponible para ese caso de uso del adaptador.²

Referencias