Adaptadores customizados do Foundation Models: quando treinar um

A documentação de adaptadores da Apple define o caminho de forma restrita: use o modelo base do sistema para a maior parte de prompt engineering, geração guiada e tools; treine um Adapter customizado apenas quando a tarefa exigir especialização dos pesos do modelo e a equipe estiver confortável com treinamento de modelos em Python.¹⁴

A própria documentação da Apple sobre o mesmo tipo cita textualmente: “Adapters consume a large amount of storage space and isn’t recommended for most apps.”¹ O post anterior deste cluster, Foundation Models Use Cases, cobriu os trilhos pelos quais a maioria dos apps deve seguir. Este post é o terceiro trilho: o ciclo de vida operacional de treinar, empacotar e enviar um adaptador customizado, e a orientação explícita da Apple sobre quando não fazer isso.

TL;DR

• O toolkit da Apple identifica o método de treinamento como LoRA: os pesos base permanecem congelados enquanto os pesos do adaptador são treinados.²
• Cada adaptador é vinculado a uma única versão do modelo do sistema. Quando a Apple atualiza o modelo base, você retreina o adaptador.³
• A recomendação da Apple, em suas palavras: “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.”¹
• Arquivos de adaptador são grandes, não devem ser enviados no bundle principal do app e são entregues sob demanda por meio de asset packs hospedados e Background Assets.²³
• A Apple diz para considerar adaptadores apenas após prompt engineering ou tool calling falharem na tarefa, ou quando um LLM servidor existente já fine-tuned, expertise em domínio específico, aderência a estilo/formato/política, ou meta de latência justificarem o custo.²

O que é, de fato, um adaptador

SystemLanguageModel.Adapter é uma struct, disponível no iOS, iPadOS, Mac Catalyst, macOS e visionOS, todos 26.0+.⁴ A descrição da Apple sobre o tipo:

“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.”⁴

O mecanismo está documentado. O guia de treinamento de adaptadores da Apple afirma diretamente:²

“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 é uma técnica pública com histórico de papers publicados.⁵ A superfície documentada pela Apple é o toolkit, exportação .fmadapter, empacotamento em asset packs, entrega via Background Assets e carregamento em runtime através de SystemLanguageModel.Adapter.²³⁴

A superfície de API do tipo

A Apple lista esta superfície 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 erro para falhas relacionadas a assets.

SystemLanguageModel tem um inicializador correspondente para adaptadores: convenience init(adapter: SystemLanguageModel.Adapter, guardrails: SystemLanguageModel.Guardrails), com a descrição “Creates the base version of the model with an adapter.”⁶

A chave de entitlement somente para deployment é com.apple.developer.foundation-model-adapter: “A Boolean value that indicates whether the app can enable custom adapters for the Foundation Models framework.”⁶ Você não precisa dela para treinamento ou para testes locais no Xcode; precisa antes de publicar na App Store.³

A rubrica da Apple para “quando considerar um adaptador”

A página do toolkit apresenta sinais concretos de adoção:²

• “You have a dataset suitable for use with an LLM” ou você já usa um LLM fine-tuned no servidor e quer paridade on-device.
• “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.”

O mesmo guia também lista os custos que você assume:²

• Um dataset de pares de prompt e resposta que demonstrem a habilidade alvo.
• Um processo para avaliar a qualidade dos seus adaptadores.
• Um processo para carregar seus adaptadores no app a partir de um servidor.

E o imposto de armazenamento: “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.”²

A recomendação do framework, reafirmada pela Apple em dois lugares distintos, é optar por padrão por prompt engineering mais tool calling e recorrer a adaptadores apenas quando a rubrica acima for atendida.

Treinamento, no formato da Apple

A Apple diz que o toolkit contém código de exemplo em Python, assets de modelo para uma versão específica do modelo do sistema, utilitários de exportação .fmadapter e utilitários de empacotamento de asset packs.²

Os requisitos de dataset são pares prompt/response em jsonl, aproximadamente 100-1.000 amostras para tarefas básicas e 5.000+ para tarefas complexas. Schema.md cobre a geração guiada e os campos de AI-safety.²

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

A regra de qualidade de dados da Apple é simples: qualidade supera quantidade.²

O treinamento é invocado pelo entry point train_adapter do 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, após treinar o adaptador, você pode treinar um draft model correspondente.² Um draft model é uma versão menor do modelo base do sistema que habilita speculative decoding, uma técnica publicada de aceleração de inferência.⁷ O enquadramento da Apple: “If you choose not to train the draft model, speculative decoding will not be available for your adapter’s use case.”²

A restrição de versão única

O fato operacionalmente mais consequente sobre adaptadores é o vínculo a uma versão específica do modelo do 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.”

Recuperado em 4 de maio de 2026, a tabela do toolkit da Apple lista Beta 0.1.0 e Beta 0.2.0 como removidas, e 26.0.0 como a primeira versão completa do toolkit. A regra de cadência da Apple é um toolkit por atualização do modelo do sistema.² Declaração 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).”²

A implicação operacional: equipes de apps que enviam adaptadores assinam um ciclo de vida de atualização de modelo que roda na cadência da Apple. Cada incremento do modelo base é um forcing function para retreinamento, reavaliação e republicação.

Empacotamento como asset packs

A regra da Apple: arquivos de adaptador são grandes demais para o bundle do app; hospede-os via App Store Connect ou seu servidor, e baixe o adaptador compatível com o dispositivo sob demanda.³

O toolkit produz pacotes .fmadapter, que o toolkit também empacota como asset packs do Background Assets. A ferramenta de linha de comando ba-package do Xcode 16 ou superior faz o empacotamento; o toolkit a invoca.³

Opções de hospedagem:³

• Apple-Hosted, Managed. A Apple hospeda o asset; o sistema operacional gerencia o ciclo de vida do download.
• Self-Hosted, Managed. Você hospeda no seu servidor; o sistema operacional gerencia o ciclo de vida do download.
• Self-Hosted, Unmanaged. Você mesmo hospeda e gerencia o ciclo de vida.

As chaves obrigatórias do Info.plist diferem por opção de hospedagem:³ Apple-Hosted Managed precisa de BAHasManagedAssetPacks, BAAppGroupID e BAUsesAppleHosting; Self-Hosted Managed precisa das duas primeiras; Self-Hosted Unmanaged não precisa de nenhuma. Cada caminho também tem um target de extension de asset-downloader que o Xcode gera.

Escolhendo o adaptador certo em runtime

Quando o BackgroundDownloadHandler.swift da extension de asset-downloader é gerado, o Xcode conecta um callback shouldDownload(_:). O exemplo da Apple para assets de adaptador:³

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

O exemplo da Apple é a única verificação de runtime documentada. A expressão SystemLanguageModel.Adapter.isCompatible(assetPack) é o que o exemplo retorna para asset packs de adaptador; trate a chamada como opaca além do que o exemplo mostra.³

Carregamento e acompanhamento de downloads

Uma vez que o asset está no dispositivo, o caminho de carregamento é:³

SystemLanguageModel.Adapter.removeObsoleteAdapters()

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

A construção dispara um download se o dispositivo não tem um adaptador compatível em cache. A nota da Apple sobre UX: “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.”³

A sequência de status vem do 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: ...
        }
    }
}

Os cinco casos documentados de DownloadStatusUpdate: .began, .paused, .downloading, .finished, .failed.³ O branch @unknown default do framework é obrigatório porque a Apple pode adicionar casos em versões futuras do SDK.

Após o status atingir .finished, o adaptador está pronto para ser conectado a uma session:

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

O draft model e seu rate limit

Se seu adaptador foi enviado com um draft model, chamar adapter.compile() o prepara para uso. A documentação da Apple destaca isso como um passo separado e computacionalmente caro:³

“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.”

Há um rate limit 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.”

O rate limit exclui o macOS; em outras plataformas, novas compilações de draft model são limitadas a três compilações por app por dia.³ A Apple recomenda executar a compilação dentro de uma task agendada via Background Tasks para que o trabalho não bloqueie o launch do app.³

O aviso da Apple sobre testes no Xcode: lançar pelo Xcode altera o UUID do app, então a compilação completa roda a cada launch e pode estourar o rate limit.³

Testes e a restrição do Simulator

Testar adaptadores requer um dispositivo físico. A Apple é explícita: “Testing adapters requires a physical device and isn’t supported on Simulator.”³

Para testes locais no Xcode, você inicializa a partir de um file URL em vez de um nome:³

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

Para publicação, a Apple diz para importar arquivos de adaptador apenas para testes locais, removê-los antes do release e baixar adaptadores sob demanda.³

O que esse caminho custa em termos operacionais

Juntando o ciclo de vida, um app que envia um adaptador customizado se inscreve em:

1. Infraestrutura de treinamento em Python. Um Mac com Apple silicon e no mínimo 32 GB de memória, ou uma máquina Linux GPU.²
2. Uma cadência de retreinamento no relógio da Apple. Toda atualização do modelo do sistema significa um adaptador novo e uma versão nova do toolkit.³
3. Uma stack de serving. Asset packs hospedados pela Apple via App Store Connect, ou seu próprio servidor rodando uma integração de asset-downloader.³
4. Adaptadores por versão em armazenamento. Múltiplas versões do modelo base em uso significa múltiplos adaptadores hospedados, com o dispositivo puxando o correspondente.³
5. Um portão de entitlement. O Account Holder da sua filiação ao Apple Developer Program o solicita; você não pode publicar sem aprovação.²
6. O imposto de 160 MB por versão de adaptador. Não no bundle do app, mas no dispositivo do usuário após o download.²
7. Testes em dispositivo físico. O Simulator não roda adaptadores.³

Esse é o custo operacional de forma direta. O benefício, quando os sinais de adoção se confirmam, é: o modelo on-device se torna especializado para a tarefa com prompting mínimo e menor latência. Para apps que já pagam por inferência fine-tuned no servidor e querem paridade on-device, essa é a troca em termos diretos.

Pontos principais

1. Adaptadores são LoRA, pela técnica documentada da Apple. Pesos base congelados, pequenas matrizes treináveis através da rede do modelo, apenas os pesos do adaptador atualizam durante o treinamento.²
2. Um adaptador por versão do modelo do sistema, sem exceções. Planeje retreinamento atrelado aos releases do OS.³
3. O fluxo .fmadapter é ponta a ponta. Treine em Python, empacote com o toolkit, hospede como asset pack do Background Assets, carregue por nome no app, compile o draft model em uma task de background.
4. A própria Apple recomenda que a maioria dos apps não siga esse caminho. Duas páginas distintas da documentação da Apple desencorajam isso para a maioria dos casos de uso.¹ Leia a rubrica na página do toolkit; a resposta é “não” por padrão.
5. Teste em hardware. O Simulator não roda adaptadores. Construa o plano de teste em torno de sessions em dispositivo físico e do slot de compilação do framework Background Tasks.

O cluster completo do Apple Ecosystem: a rubrica de decisão para especialização built-in; o Tool protocol no núcleo do framework; a divisão do agentic workflow entre LLMs in-app e de tooling; App Intents vs MCP para a questão mais ampla de roteamento. O hub está em Apple Ecosystem Series. Para contexto mais amplo de iOS com AI agents, veja o iOS Agent Development guide.

FAQ

Como saber se meu app realmente precisa de um adaptador customizado?

A Apple recomenda o modelo base para a maior parte de prompt engineering, geração guiada e tools, e o guia do toolkit diz que adaptadores têm requisitos íngremes de treinamento e retreinamento. A resposta padrão é não, a menos que os sinais de adaptador da Apple se apliquem.²⁴

O que o entitlement de fato libera?

A Apple documenta o entitlement como obrigatório ao fazer deploy de adaptadores, não para treinamento ou testes locais.²³

Qual o tamanho dos adaptadores e onde eles ficam?

O número documentado pela Apple: “Each adapter will take approximately 160 MB of storage space in your app.”² Adaptadores não ficam no bundle do app. A Apple os entrega via Background Assets, hospedados em servidores da Apple (managed) ou no seu próprio servidor (managed ou unmanaged), e o dispositivo baixa a versão correspondente ao seu modelo de sistema atual.³

O que acontece quando a Apple atualiza o modelo base?

Quando a Apple atualiza o modelo base, treine um adaptador compatível para essa versão de modelo; caso contrário, o app pode encontrar um runtime error em um dispositivo sem adaptador compatível.²³

Qual a relação entre adaptadores e .contentTagging?

.contentTagging é gerenciado pela Apple e embutido no framework: um caso de uso especializado internamente, não o tipo formal Adapter que um desenvolvedor treina. O tipo formal é o que este post cobre; os casos de uso são cobertos no post complementar.

Preciso treinar um draft model?

A Apple documenta apenas esta consequência de pular o treinamento do draft model: speculative decoding fica indisponível para esse caso de uso do adaptador.²

Referências