Casos de uso dos Foundation Models: quando especializar e quando apenas usar prompts

O modelo on-device do Foundation Models não é uma coisa única. A Apple disponibiliza um SystemLanguageModel padrão para prompts gerais e uma especialização gerenciada pela Apple para marcação de conteúdo.¹ O framework também permite que desenvolvedores treinem e carreguem seus próprios adapters.² Três trilhos, uma árvore de decisão e uma página de documentação que nomeia exatamente dois valores de UseCase.

O post anterior sobre o protocolo Tool cobriu como fazer o modelo padrão executar um trabalho útil. A pergunta que este post responde é a próxima: quando o modelo padrão com prompts e tools é suficiente, e quando o use case .contentTagging da Apple merece seu lugar? O caminho de adapter customizado é um post separado; o ciclo de vida gerenciado pelo desenvolvedor tem superfície de complexidade demais para compartilhar com o critério de decisão.

TL;DR

• SystemLanguageModel.UseCase é uma struct com duas propriedades estáticas: .general e .contentTagging.³ Nenhum outro use case está documentado.
• .general é o padrão. Recorra a ele primeiro. Prompts, instructions, guided generation e tool calling vivem todos em cima de .general; a especialização é a última alavanca a ser puxada.
• .contentTagging é construído para uma tarefa específica: identificar tópicos, ações, objetos e emoções no texto de entrada e retornar tags de uma a poucas palavras em minúsculas.⁴ O próprio guia da Apple diz quando usar .general em vez disso.
• O terceiro trilho (adapters customizados, o tipo Adapter, a entitlement, o toolkit) é onde mora a complexidade operacional. Post diferente.

O que SystemLanguageModel realmente é

SystemLanguageModel é uma final class no framework FoundationModels, disponível em iOS 26.0+, iPadOS 26.0+, Mac Catalyst 26.0+, macOS 26.0+ e visionOS 26.0+.¹ A Apple a descreve como “um large language model on-device capaz de tarefas de geração de texto.”

Dois fatos moldam como usá-lo. Primeiro, SystemLanguageModel.default retorna a versão base do modelo.¹ Esse é o ponto de entrada para tudo que não é especializado. Segundo, a Apple atualiza o modelo em atualizações do OS: até o momento da escrita, a documentação da Apple lista duas versões de modelo, uma para iOS, iPadOS, macOS e visionOS 26.0–26.3 e outra para 26.4.¹ Apps não fixam uma versão específica; o framework retorna qualquer modelo que o OS esteja executando no momento.

A disponibilidade é verificada em runtime. SystemLanguageModel.availability é um enum Availability com os seguintes casos, conforme documentado no código de exemplo da Apple:¹

struct GenerativeView: View {
    private var model = SystemLanguageModel.default

    var body: some View {
        switch model.availability {
        case .available:
            // Show your intelligence UI.
        case .unavailable(.deviceNotEligible):
            // Show an alternative UI.
        case .unavailable(.appleIntelligenceNotEnabled):
            // Ask the person to turn on Apple Intelligence.
        case .unavailable(.modelNotReady):
            // The model isn't ready because it's downloading or because
            // of other system reasons.
        case .unavailable(let other):
            // The model is unavailable for an unknown reason.
        }
    }
}

isAvailable é um getter de conveniência que retorna true apenas quando o sistema está totalmente pronto.¹ Sempre verifique antes de chamar.

O primeiro trilho: faça prompt no modelo geral

A Apple posiciona o modelo padrão como a ferramenta certa para uma ampla gama de tarefas. O guia geral do framework enumera capacidades que a Apple diz que o modelo on-device lida bem:⁴

A Apple também é explícita sobre o que o modelo on-device não é apropriado:⁴

Note que “gerar tags a partir de texto” aparece na tabela de bom em para o modelo geral. Esse é um contexto importante para a decisão de especialização abaixo.

O trilho padrão tem o toolkit completo disponível: instructions, prompts, guided generation via Generable, tool calling via o protocolo Tool, opções de geração como temperatura. A maioria dos apps que adotarem o Foundation Models viverão neste trilho e nunca tocarão um especificador de use case.

A janela de contexto é de 4.096 tokens para o modelo de sistema.⁴ A Apple observa que um token corresponde a três ou quatro caracteres em idiomas como inglês, espanhol ou alemão, e um token por caractere em idiomas como japonês, chinês ou coreano. As instructions, prompts e saídas todos contam para o limite. Quando uma sessão excede esse limite, o framework lança LanguageModelSession.GenerationError.exceededContextWindowSize(_:).⁴

O segundo trilho: .contentTagging

SystemLanguageModel.UseCase é documentado como uma struct (não um enum) com duas propriedades estáticas:³

static let general: SystemLanguageModel.UseCase
static let contentTagging: SystemLanguageModel.UseCase

Não há outros casos documentados. Se um artigo nomear um terceiro use case, o artigo está inventando.

.contentTagging tem um formato diferente de .general. O guia da Apple descreve o modelo de contentTagging como aquele que “identifica tópicos, ações, objetos e emoções no texto de entrada” e produz tags como “uma a poucas palavras em minúsculas.”⁵ O modelo é construído para avaliar entrada em vez de responder conversacionalmente: “Não é um modelo de linguagem típico que responde a uma consulta de uma pessoa: em vez disso, ele avalia e agrupa a entrada que você fornece.”⁵

Carregando o modelo com .contentTagging:

let model = SystemLanguageModel(useCase: .contentTagging)
let session = LanguageModelSession(
    model: model,
    instructions: """
        Provide the two tags that are most significant in the context of topics.
        """
)

O inicializador de conveniência documentado é init(useCase:guardrails:).¹ O código de exemplo da Apple o chama sem o argumento guardrails, o que sugere que guardrails carrega um valor padrão no ponto de chamada.

O modelo de contentTagging integra com Generable, então você pode definir um tipo Swift que captura o formato das tags que você deseja:

@Generable
struct ContentTaggingResult {
    @Guide(
        description: "Most important actions in the input text.",
        .maximumCount(2)
    )
    let actions: [String]

    @Guide(
        description: "Most important emotions in the input text.",
        .maximumCount(3)
    )
    let emotions: [String]

    @Guide(
        description: "Most important objects in the input text.",
        .maximumCount(5)
    )
    let objects: [String]

    @Guide(
        description: "Most important topics in the input text.",
        .maximumCount(2)
    )
    let topics: [String]
}

let response = try await session.respond(
    to: prompt,
    generating: ContentTaggingResult.self
)

O guia da Apple inclui uma nota comportamental útil: “Para consultas de entrada muito curtas, instructions de marcação de tópico e emoção fornecem os melhores resultados. Listas de ações ou objetos serão muito específicas e podem repetir as palavras na consulta.”⁵ O modelo de contentTagging também “respeita o formato de saída que você quer, mesmo na ausência de instructions”, então o formato Generable carrega mais peso do que um system prompt verboso carregaria.

A árvore de decisão (nas próprias palavras da Apple)

A parte interessante do API do use case é que a documentação da Apple é explícita sobre quando não especializar. Do guia de contentTagging:⁵

1. “Se você está marcando conteúdo que não é uma ação, objeto, emoção ou tópico, use general em vez disso.”
2. “Use o modelo general para gerar conteúdo como hashtags para posts de mídia social.”
3. “Se você adota o API de tool calling e quer gerar tags, use general e passe a saída do Tool para o modelo de content tagging.”
4. “Se você tem um conjunto complexo de restrições de marcação que são mais complicadas que o suporte de maximum count do modelo de tagging, use general em vez disso.”

Leia esses quatro juntos. O modelo de contentTagging é estreitamente delimitado: tópicos, ações, objetos, emoções. Todo o resto (geração de hashtags, pipelines de tags que envolvem tool calls, saída de tags com restrições mais ricas que maximumCount) pertence ao modelo geral.

O critério pragmático de decisão para um app que acha que quer tagging:

Padrão para .general. Ele lida com a ampla gama de tarefas de geração que a tabela da Apple descreve, incluindo “gerar tags a partir de texto.” A maioria dos apps para por aqui.

Recorra a .contentTagging apenas quando a entrada é em formato de texto, a saída é um pequeno conjunto de tags de uma ou poucas palavras que se enquadram nitidamente nas quatro categorias da Apple (tópicos/ações/objetos/emoções) e as restrições se encaixam em maximumCount. O exemplo que a Apple dá é o padrão: um app social que quer tags por post para alimentar um dashboard de tópicos, um cliente de email que quer auto-rotulagem, uma loja de conteúdo que quer sinais agregados de tendência.

Adie para um adapter customizado apenas quando nenhum dos trilhos serve e o use case é valioso o suficiente para absorver o custo operacional de treinar e distribuir um adapter vinculado a uma versão específica de modelo do sistema. O caminho de adapter customizado é documentado separadamente; a complexidade do ciclo de vida (versão do toolkit, ciclo de re-treinamento, distribuição) merece seu próprio tratamento.

O que a Apple não publicou

Algumas coisas que você verá especuladas que não estão na superfície documentada:

• O mecanismo que a Apple usa para especializar o modelo para .contentTagging. O guia de contentTagging da Apple descreve o framework como fornecendo “um modelo de linguagem de sistema on-device adaptado que se especializa em content tagging.”⁵ A Apple não publica o mecanismo de especialização, e o verbo “adaptado” nessa frase não deve ser confundido com o tipo SystemLanguageModel.Adapter gerenciado pelo desenvolvedor, que é um trilho separado.
• Outros valores de use case. A struct tem duas propriedades estáticas até o momento da documentação atual; qualquer terceiro caso precisaria ser distribuído em uma futura atualização do OS.
• Uma garantia de que .general e .contentTagging sempre coexistirão. A Apple diz “A Apple atualizará periodicamente o SystemLanguageModel em atualizações de rotina do OS para melhorar as habilidades e o desempenho do modelo on-device.”¹ Trate a superfície como versionada.
• Números específicos de qualidade para .contentTagging versus .general em benchmarks de tagging. A Apple posiciona a escolha como adequação à tarefa, não como leaderboard de qualidade.

Se um post (este ou qualquer outro) faz uma alegação quantitativa sobre mecânica de adapter que não está em developer.apple.com, trate a alegação como errada por padrão.

O que os dois trilhos realmente entregam

O segundo trilho não é “o modelo fica melhor.” É “o modelo é construído para uma tarefa e a Apple documentou quando escolhê-lo.” Isso muda a economia:

1. Menor superfície de prompt engineering para tarefas de tagging. O modelo de contentTagging “respeita o formato de saída que você quer, mesmo na ausência de instructions.”⁵ Você pode se apoiar em @Generable e maximumCount em vez de um prompt de múltiplos parágrafos que o modelo geral precisaria.
2. Formato semântico restrito. O modelo encontra similaridade entre termos de entrada e produz tags semanticamente consistentes (exemplo da Apple: “greet” emerge como a tag de tópico para “hi”, “hello”, “yo”).⁵ Isso é exatamente o que análise agregada sobre conteúdo gerado por usuário precisa.
3. Um critério de decisão documentado. A Apple diz quando a especialização deles serve e quando recuar. Esse critério é a parte mais valiosa do API do use case: é uma resposta opinativa a uma pergunta que desenvolvedores de apps de outra forma litigariam a partir de princípios fundamentais.

O custo também é claro: .contentTagging está vinculado a um formato de tarefa. Qualquer coisa fora desse formato volta para .general e vive ou morre no design de prompt e Generable.

Conclusões

1. Dois trilhos hoje, possivelmente mais depois. .general e .contentTagging são as únicas duas propriedades estáticas de UseCase que a Apple documentou. Não escreva código que assuma outras.
2. Padrão para .general. Prompts + tools + guided generation lida com a maioria dos use cases para os quais o modelo on-device foi projetado. A especialização é a última alavanca, não a primeira.
3. Escolha .contentTagging apenas quando o formato documentado da Apple servir. Tópicos, ações, objetos, emoções. Tags em minúsculas de uma a poucas palavras. Restrições no nível de maximumCount. Qualquer coisa além disso, recue.
4. Leia as regras de “use general em vez disso” da Apple. São quatro frases concretas no guia de contentTagging.⁵ Cada uma é um limite real.
5. O caminho de adapter customizado é uma decisão separada. Superfície diferente, ciclo de vida diferente, post diferente.

O cluster completo do Apple Ecosystem: o LLM on-device e protocolo Tool para os primitivos do framework; a divisão de fluxo de trabalho agentic entre LLMs in-app e developer-tooling; App Intents vs MCP para a questão de roteamento entre os três. O hub está em Apple Ecosystem Series. Para contexto mais amplo de iOS-com-AI-agents, veja o iOS Agent Development guide.

FAQ

Quantos valores de SystemLanguageModel.UseCase existem?

Duas propriedades estáticas conforme documentado atualmente: .general e .contentTagging.³ Se você ver um terceiro valor referenciado em um tutorial ou em uma resposta gerada por LLM, verifique contra developer.apple.com antes de adotá-lo.

Quando devo usar .contentTagging em vez de apenas fazer prompt em .general?

Use .contentTagging quando a tarefa é identificar tópicos, ações, objetos ou emoções no texto de entrada e retornar tags curtas em minúsculas. O guia da Apple lista quatro cenários em que .general é a resposta certa: marcação que não se encaixa nessas quatro categorias, geração de hashtags, pipelines de tags que passam por tool calls e restrições de marcação mais ricas que maximumCount.⁵

O modelo de contentTagging aceita instructions arbitrárias como o modelo geral aceita?

Aceita instructions, mas o design do modelo é avaliar entrada em vez de responder a consultas em estilo de usuário. O guia da Apple observa que o modelo de contentTagging “respeita o formato de saída que você quer, mesmo na ausência de instructions”, portanto um formato @Generable com anotações @Guide carrega a restrição, não um prompt longo.⁵

Qual é a janela de contexto para o modelo on-device?

4.096 tokens para o modelo de sistema.⁴ A proporção token-para-caractere é de aproximadamente três a quatro caracteres por token em inglês/espanhol/alemão e um token por caractere em japonês/chinês/coreano. O framework lança LanguageModelSession.GenerationError.exceededContextWindowSize(_:) quando a sessão excede o limite.

Por que o código de exemplo da Apple chama SystemLanguageModel(useCase:) sem guardrails:?

O inicializador de conveniência documentado é init(useCase:guardrails:).¹ O guia de contentTagging da Apple o chama sem o argumento guardrails, o que sugere que guardrails carrega um valor padrão no ponto de chamada. A forma de dois argumentos é a superfície documentada; a forma de um argumento é o que o código de exemplo publicado pela Apple mostra.

Referências