Apple Foundation Models: o framework de LLM no dispositivo, explicado

O framework Foundation Models dá ao seu app acesso direto, gratuito e offline ao mesmo modelo de linguagem de grande porte que roda no dispositivo e impulsiona o Apple Intelligence¹. Sem chave de API, sem cobrança por token, sem ida e volta pela rede, sem nenhum dado saindo do aparelho. Para toda uma classe de recursos que antes exigia um LLM na nuvem e uma revisão de privacidade, o custo agora arredonda para zero. A contrapartida é a capacidade: o modelo no dispositivo é pequeno, a janela de contexto é finita e o framework traça limites rígidos sobre o que faz e o que não faz. Conhecer esses limites é tudo o que importa.

Esta é a referência do framework em si: os tipos que você realmente chama, o recurso que justifica usá-lo e o ponto em que você deve parar e buscar algo maior.

TL;DR

• LanguageModelSession é o ponto de entrada. Crie uma, chame respond(to:) e receba texto de volta. O contexto de múltiplos turnos vive na sessão; tarefas de turno único ganham uma sessão nova a cada vez².
• A geração guiada é a razão para usar este framework. Anote um tipo Swift com @Generable e o modelo devolve aquele tipo, preenchido e com tipagem verificada, em vez de uma string que você precisa interpretar³.
• O protocolo Tool permite que o modelo chame o seu código no meio da geração para buscar dados ou executar uma ação e depois incorporar o resultado à resposta⁴.
• Verifique SystemLanguageModel.default.availability antes de qualquer coisa. O modelo não está presente em aparelhos inelegíveis, com o Apple Intelligence desligado ou enquanto ele está sendo baixado⁵.
• A janela de contexto é real e é pequena. SystemLanguageModel.default.contextSize informa o orçamento de tokens compartilhado entre prompt e resposta⁶. No dispositivo, esse orçamento é de 4K tokens; o modelo do Private Cloud Compute eleva para 32K¹⁴. Planeje em cima disso, ou a sessão lança erro.
• Exige iOS 26 e um aparelho compatível com Apple Intelligence. Abaixo desse piso, o framework não existe. Os betas do iOS 27 estendem a mesma API com entrada de imagem, controle de chamada de ferramentas por requisição e um modelo de servidor no Private Cloud Compute¹²¹³¹⁴.

O que o framework é e o que ele não é

Foundation Models não é um wrapper em volta de um endpoint na nuvem. O modelo mora no aparelho, vem junto com o sistema operacional e roda sobre o Neural Engine. Esse único fato governa cada decisão de design da API e cada decisão que você toma ao usá-la.

O que você ganha: geração de texto, resumo, classificação, extração, reescrita de trechos curtos e saída estruturada — tudo no dispositivo e tudo de graça. O que você não ganha: um modelo de fronteira. A Apple construiu o modelo no dispositivo para tarefas de linguagem bem delimitadas dentro de um app, não para raciocínio aberto, não para análise de documentos longos, não para conhecimento de mundo que você possa sabatinar. A própria Apple diz isso, e o enquadramento importa porque define expectativas que a API, de outro modo, deixaria você violar¹.

O modelo mental que evita dor de cabeça: trate o modelo no dispositivo como um estagiário rápido, privado e gratuito, excelente em dar forma a texto e péssimo em saber fatos. Entregue material e uma tarefa clara. Não faça perguntas que ele não tem como responder.

LanguageModelSession: o ponto de entrada

Toda interação começa com uma sessão.

import FoundationModels

let session = LanguageModelSession()
let response = try await session.respond(to: "Summarize this review in one sentence: \(reviewText)")
print(response.content)

A sessão guarda o estado da conversa. Cada chamada a respond(to:) acrescenta algo à transcrição corrente, então uma sessão que você mantém viva lembra do que veio antes. Num recurso de chat, é exatamente o que você quer. Em tarefas independentes e de uma tacada só (resuma isto, classifique aquilo), crie uma sessão nova a cada chamada, para que contexto velho não vaze para dentro e coma o seu orçamento de tokens².

respond(to:) é async throws. Ele suspende enquanto o modelo trabalha e lança erro quando a requisição excede a janela de contexto, quando o modelo está indisponível ou quando as salvaguardas rejeitam o conteúdo. Cada um desses é um caminho real que você trata, não um caso extremo que você ignora.

Para uma UI responsiva, faça streaming em vez de esperar. streamResponse(to:) entrega saída parcial conforme o modelo a produz, o que transforma três segundos de travamento em texto que aparece enquanto se forma⁷.

Geração guiada: o recurso que justifica o framework

Aqui está a parte que vale o ingresso. A maioria das integrações com LLM gasta um terço do código arrancando JSON válido do modelo e os outros dois terços se defendendo das vezes em que ele falha mesmo assim. O Foundation Models elimina esse trabalho.

Anote um tipo Swift com @Generable, peça à sessão que o gere e o modelo devolve uma instância daquele tipo, preenchida e com tipagem segura³:

@Generable
struct Recipe {
    @Guide(description: "The dish name")
    let title: String

    @Guide(description: "Ingredients, each as 'quantity item'")
    let ingredients: [String]

    @Guide(description: "Total minutes, start to finish", .range(5...240))
    let minutes: Int
}

let session = LanguageModelSession()
let response = try await session.respond(
    to: "A weeknight pasta for two.",
    generating: Recipe.self
)
let recipe = response.content   // a Recipe, not a String

Nada de parsing. Nada de JSONDecoder. Nada de loop de retentativa para saída malformada. A macro @Guide restringe campos individuais: uma descrição que o modelo lê como instrução e limites opcionais, como uma faixa numérica ou uma expressão regular que a saída precisa satisfazer⁸. O framework não pede educadamente ao modelo um número entre 5 e 240; ele restringe a decodificação para que o campo não possa voltar de outro jeito.

A disciplina que isso impõe é o valor real. Você projeta primeiro o tipo de saída, em Swift, com o compilador conferindo. O modelo preenche um contrato que você definiu, em vez de devolver prosa que você tem de submeter a engenharia reversa. Para extração, preenchimento de formulários e qualquer recurso que transforme linguagem em dado, a geração guiada é a diferença entre uma demo e código que vai para produção.

Um controle que vale conhecer: respond(to:generating:) define includeSchemaInPrompt como true por padrão, o que injeta o formato do seu tipo no prompt para enviesar o modelo naquela direção. Deixe ligado, a menos que o modelo já conheça o formato pelo treinamento ou por turnos anteriores da sessão; desligar para economizar tokens num formato que o modelo nunca viu é exatamente como você recebe lixo de volta⁹.

Chamada de ferramentas: deixando o modelo alcançar o seu código

A geração guiada dá forma ao que sai. A chamada de ferramentas muda o que entra. Uma ferramenta é um pedaço do seu código que o modelo pode invocar no meio da geração para buscar informação que ele não tem ou executar uma ação, e então continuar a resposta usando o resultado⁴.

Uma ferramenta implementa o protocolo Tool: um name, uma description que o modelo lê para decidir quando chamá-la, um tipo Arguments marcado com @Generable e um método call(arguments:) que faz o trabalho⁴:

struct FindContacts: Tool {
    let name = "findContacts"
    let description = "Find a specific number of contacts from the address book"

    @Generable
    struct Arguments {
        @Guide(description: "How many contacts to return", .range(1...10))
        let count: Int
    }

    func call(arguments: Arguments) async throws -> [String] {
        // Fetch contacts, return formatted names.
    }
}

let session = LanguageModelSession(tools: [FindContacts()])
let response = try await session.respond(to: "Draft a dinner invite to three of my contacts.")

O fluxo: o modelo decide que precisa de contatos, chama a sua ferramenta com um count validado, você devolve os dados e o modelo escreve o convite usando nomes reais. Os argumentos chegam com tipagem verificada pela mesma maquinaria da geração guiada, então você nunca precisa extrair a intenção do modelo de um texto livre. A descrição da ferramenta é a sua única alavanca sobre quando o modelo vai recorrer a ela, então escreva-a como a documentação de uma função que outro engenheiro (sem nenhum contexto adicional) precisa ler e usar corretamente.

Esta é também a costura em que o Foundation Models encontra o resto da história dos agentes. Uma ferramenta que o modelo no dispositivo chama e um App Intent¹¹ que o Apple Intelligence chama são superfícies diferentes com o mesmo formato: uma capacidade nomeada, descrita e tipada. Projete a capacidade uma vez e você pode expô-la pelos dois caminhos.

Disponibilidade: a verificação que você não pode pular

O modelo nem sempre está lá. Ele não está presente em aparelhos que não suportam o Apple Intelligence, quando o usuário o desligou e durante a janela em que o sistema operacional ainda está baixando os recursos do modelo. Publique um código que assume que o modelo existe e ele vai travar, degradar em silêncio ou congelar para uma parcela dos seus usuários em que você nunca testou.

Verifique SystemLanguageModel.default.availability e trate cada motivo separadamente⁵:

switch SystemLanguageModel.default.availability {
case .available:
    // Show the intelligence feature.
case .unavailable(.deviceNotEligible):
    // Hide it. This device will never have the model.
case .unavailable(.appleIntelligenceNotEnabled):
    // Prompt the user to turn on Apple Intelligence.
case .unavailable(.modelNotReady):
    // Downloading or otherwise not ready yet. Try again later.
case .unavailable(let other):
    // Unknown reason. Fail closed.
}

Os três motivos exigem três respostas de produto diferentes, e confundi-los é a forma mais comum de esses recursos parecerem quebrados. deviceNotEligible é permanente: esconda o recurso, não fique insistindo. appleIntelligenceNotEnabled é uma configuração que o usuário controla: um único aviso é justo. modelNotReady é temporário: tente de novo, não mostre erro. Construa o caminho da indisponibilidade com o mesmo cuidado do caminho feliz, porque para uma fatia real de aparelhos ele é o único caminho.

Quando o modelo está disponível e você sabe que uma requisição está a caminho, prewarm() na sessão aquece o modelo para que a primeira resposta de verdade chegue mais rápido¹⁰. Vale a pena numa tela em que o usuário está prestes a agir; é desperdício se você chamar por especulação.

Na prática: um recurso completo em um único arquivo

As peças acima se compõem num recurso real com menos código do que a maioria das camadas de rede precisa para um único endpoint. O exemplo abaixo é uma tela SwiftUI completa e compilável que transforma anotações livres de reunião em itens de ação estruturados: verificação de disponibilidade, tipo de saída @Generable, uma chamada de geração guiada e os três caminhos de indisponibilidade tratados. Cada símbolo vem da superfície do framework documentada acima²³⁵⁸.

import SwiftUI
import FoundationModels

@Generable
struct ActionItems {
    @Guide(description: "One-sentence summary of the meeting")
    let summary: String

    @Guide(description: "Concrete follow-up tasks, each starting with a verb")
    let tasks: [String]

    @Guide(description: "How urgent the follow-ups are overall", .anyOf(["low", "medium", "high"]))
    let urgency: String
}

struct MeetingNotesView: View {
    @State private var notes = ""
    @State private var result: ActionItems?
    @State private var errorMessage: String?

    var body: some View {
        Form {
            TextField("Paste meeting notes", text: $notes, axis: .vertical)
                .lineLimit(6...12)

            Button("Extract action items") {
                Task { await extract() }
            }
            .disabled(notes.isEmpty)

            if let result {
                Section(result.summary) {
                    ForEach(result.tasks, id: \.self) { Text($0) }
                    Text("Urgency: \(result.urgency)")
                }
            }

            if let errorMessage {
                Text(errorMessage).foregroundStyle(.secondary)
            }
        }
    }

    private func extract() async {
        switch SystemLanguageModel.default.availability {
        case .available:
            do {
                let session = LanguageModelSession()
                let response = try await session.respond(
                    to: "Extract the action items from these notes: \(notes)",
                    generating: ActionItems.self
                )
                result = response.content
            } catch {
                errorMessage = "The model could not process these notes."
            }
        case .unavailable(.appleIntelligenceNotEnabled):
            errorMessage = "Turn on Apple Intelligence in Settings to use this feature."
        case .unavailable(.modelNotReady):
            errorMessage = "The model is still downloading. Try again shortly."
        case .unavailable:
            errorMessage = "This feature needs an Apple Intelligence-capable device."
        }
    }
}

Três detalhes que valem atenção num exemplo tão pequeno. O tipo de saída é a API: ActionItems define exatamente o que o recurso produz, e a restrição @Guide em urgency significa que a string não pode voltar como nada fora dos três valores permitidos⁸. A sessão é criada a cada chamada porque cada extração é independente; uma sessão retida arrastaria as anotações anteriores para dentro do orçamento de tokens². E os caminhos de indisponibilidade produzem três experiências diferentes para o usuário, não um erro genérico — essa é a diferença entre um recurso que degrada com honestidade e um que parece quebrado. Cole o arquivo num projeto iOS 26, rode num aparelho compatível com Apple Intelligence e funciona.

A janela de contexto e o ponto em que ela deixa de bastar

SystemLanguageModel.default.contextSize informa o orçamento de tokens dentro do qual o modelo trabalha, e esse orçamento é compartilhado: prompt e resposta somados precisam caber⁶. O número é pequeno perto de um modelo em nuvem, e você sente isso rápido com entrada real. Um documento longo, um histórico de conversa inteiro, um resultado gordo de ferramenta: qualquer um deles pode estourar o orçamento e fazer respond lançar erro.

Daí vêm dois modos de falha, e prevenir os dois é com você. Primeiro, o avanço lento: uma sessão de múltiplos turnos acumula transcrição até que mais um turno transborde. Controle isso começando sessões novas para trabalhos sem relação entre si e mantendo enxuta a entrada de cada turno. Segundo, a requisição única grande demais: um PDF de 20 páginas não cabe, ponto final. Fatie, resuma os pedaços e depois raciocine sobre os resumos (o map-reduce que quem trabalha com LLM conhece bem), ou aceite que a tarefa tem o formato errado para um modelo no dispositivo.

A janela de contexto é o sinal mais limpo para a decisão que de fato importa neste framework: quando ficar no dispositivo e quando sair. Os números agora são públicos: o modelo no dispositivo trabalha dentro de um orçamento de 4K tokens, e o modelo de servidor do Private Cloud Compute eleva isso para 32K¹⁴. Tudo o que se diz aqui sobre fatiamento vale com esses números anexados.

O que os betas do iOS 27 acrescentam

Tudo acima descreve o framework como ele saiu no iOS 26, e tudo continua valendo. Os betas do iOS 27 estendem a mesma superfície em quatro direções, e nenhuma delas quebra o modelo mental do iOS 26¹².

O prompt aceita imagens. O modelo no dispositivo ganha capacidades de Vision: você insere um anexo de imagem no prompt junto com o texto e o modelo responde sobre os dois. Os novos tipos são Attachment, ImageAttachmentContent e ImageReference, e os anexos aceitam UIImage, NSImage, CGImage, tipos do Core Image, pixel buffers do CoreVideo e URLs de arquivo¹²¹³. As imagens funcionam em qualquer tamanho e proporção, mas gastam do mesmo orçamento de tokens que o seu texto, então a janela de 4K no dispositivo vira a restrição de design bem rápido¹³. O passo a passo completo está em Entrada de imagem no Foundation Models no iOS 27.

A chamada de ferramentas ganha um regulador. GenerationOptions ganha um toolCallingMode que você define por requisição e que controla como o modelo interage com as ferramentas anexadas, e o framework Vision já traz implementações prontas de OCRTool e BarcodeReaderTool que você anexa a uma sessão em vez de escrever seu próprio código de reconhecimento¹⁵. Os detalhes de comportamento estão em controle de chamada de ferramentas no iOS 27.

Um modelo maior, a uma linha de distância. PrivateCloudComputeLanguageModel roda a mesma API contra o modelo de servidor da Apple no Private Cloud Compute, atrás de um entitlement, com a janela de contexto de 32K e um raciocínio que o modelo no dispositivo não tem¹²¹⁴. Geração guiada e ferramentas funcionam sem alteração; trocar de modelo é o argumento model da sessão.

As sessões ganham mais superfície de controle. Os betas acrescentam ContextOptions, TranscriptErrorHandlingPolicy, perfis dinâmicos (DynamicInstructions, LanguageModelSession.DynamicProfile) e um protocolo de provedor de modelo de linguagem customizado (LanguageModel, LanguageModelExecutor) que permite a uma sessão operar um modelo fornecido por você, e não o do sistema¹². O watchOS também entra na lista de plataformas na versão 27.0¹².

O enquadramento a guardar: código de iOS 26 compila e se comporta igual no iOS 27. Os betas ampliam o que um prompt pode carregar e onde o modelo pode rodar; não mudam o que o framework é.

Quando não usar o Foundation Models

O framework é gratuito, privado e offline, o que dá vontade de usá-lo em tudo. Resista. Passe direto por ele quando:

• Você precisa de raciocínio de verdade ou de amplitude de conhecimento de mundo. O modelo no dispositivo é pequeno por design. Raciocínio aberto, geração de código e análise profunda pertencem a um modelo de fronteira na nuvem. Pedir isso ao modelo no dispositivo produz respostas confiantes e erradas.
• A entrada não cabe na janela de contexto e fatiar destruiria o sentido. Algumas tarefas precisam enxergar tudo de uma vez.
• Você precisa de um modelo sob seu controle: um checkpoint específico, um fine-tune, pesos customizados, versionamento determinístico ao longo das atualizações do sistema. A Apple entrega e atualiza o modelo no cronograma dela, não no seu.
• Você está abaixo do iOS 26 ou num aparelho inelegível. O framework simplesmente não está lá, e a verificação de disponibilidade vai dizer isso em toda execução.

Para os casos no dispositivo que o framework não cobre (um modelo customizado, pesos próprios, treinamento no aparelho), as camadas abaixo são o Core ML para um modelo convertido e fixo, o MLX para modelos de pesos abertos e fine-tunes que são seus, e o Core AI do iOS 27 quando você precisa de controle explícito sobre especialização e agendamento. Para os casos que realmente precisam de escala, o Private Cloud Compute ou um LLM na nuvem atrás de uma fronteira de privacidade continua sendo a resposta honesta. O Foundation Models não substitui nenhum deles. É a primeira escolha certa para trabalho de linguagem bem delimitado sobre texto que você já tem em mãos, e a escolha errada para todo o resto.

A habilidade que este framework recompensa não é o artesanato de prompt. É bom gosto quanto ao escopo: alimentar o modelo com tarefas em que ele é bom, projetar tipos @Generable que capturam exatamente o que você precisa e reconhecer o momento em que o trabalho cresce além do aparelho. Construa com esses instintos e o modelo no dispositivo faz uma quantidade surpreendente de trabalho real de graça. Ignore-os e você publica um recurso que quebra para todo usuário cuja entrada passou um token do limite.

Perguntas frequentes

O framework Foundation Models da Apple é gratuito?

Sim. O framework dá ao app acesso direto, gratuito e offline ao mesmo modelo no dispositivo que impulsiona o Apple Intelligence. Não há chave de API, não há cobrança por token e não há ida e volta pela rede¹.

Quais aparelhos e qual versão do iOS o Foundation Models exige?

Ele exige iOS 26 e um aparelho compatível com Apple Intelligence. Abaixo desse piso o framework não existe e, mesmo num sistema suportado, o modelo não está presente em aparelhos inelegíveis, com o Apple Intelligence desligado ou enquanto o modelo é baixado. Sempre verifique SystemLanguageModel.default.availability antes de usar⁵.

Como obter saída estruturada e com tipagem segura em vez de uma string?

Anote um tipo Swift com @Generable e o modelo devolve aquele tipo, preenchido e com tipagem verificada, em vez de uma string que você teria de interpretar. Essa geração guiada é o único recurso que, sozinho, já justifica usar o framework³.

Qual é a janela de contexto do modelo no dispositivo da Apple?

SystemLanguageModel.default.contextSize informa o orçamento de tokens, compartilhado entre o prompt e a resposta gerada⁶. O modelo no dispositivo oferece 4K tokens; o modelo do Private Cloud Compute oferece 32K¹⁴. Documentos longos e históricos longos de múltiplos turnos vão estourar o orçamento no dispositivo, então planeje em cima do limite, ou a sessão lança erro.

O Foundation Models funciona offline? Ele envia dados para a Apple?

Ele roda inteiramente no dispositivo, sobre o Neural Engine. Nenhum dado sai do aparelho e nenhuma ida e volta pela rede é necessária, e é isso que o torna adequado a recursos que antes precisavam de um LLM na nuvem e de uma revisão de privacidade¹.

O modelo no dispositivo pode chamar o meu próprio código no meio da geração?

Sim. O protocolo Tool permite que o modelo invoque o seu código para buscar dados ou executar uma ação durante a geração e depois incorpore o resultado à resposta⁴.

Quando eu não devo usar o Foundation Models?

Passe direto por ele quando precisar de um modelo de fronteira: raciocínio aberto, geração de código, análise de documentos longos ou conhecimento de mundo. A Apple construiu o modelo no dispositivo para tarefas de linguagem bem delimitadas dentro de um app, então pedir inteligência geral a ele produz respostas confiantes e erradas¹.

O que o iOS 27 acrescenta ao Foundation Models?

Os betas do iOS 27 acrescentam entrada de imagem (anexos no prompt, criados a partir de UIImage, CGImage, pixel buffers e mais), controle de chamada de ferramentas por requisição via GenerationOptions, as ferramentas prontas OCRTool e BarcodeReaderTool do Vision e PrivateCloudComputeLanguageModel para rodar a mesma API contra o modelo de servidor da Apple com contexto de 32K^12131415. Código de iOS 26 roda sem alteração.