Casos de uso do Foundation Models: General vs Content Tagging

A documentação da Apple para SystemLanguageModel começa com o modelo base, depois os casos de uso e, por fim, os adapters. SystemLanguageModel.default é o modelo base; SystemLanguageModel.UseCase documenta general e contentTagging; adapters customizados são o caminho treinado pelo desenvolvedor, abordado separadamente.¹²³

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

TL;DR

• SystemLanguageModel.UseCase é uma struct com duas propriedades estáticas: .general e .contentTagging.³ Nenhum outro caso de uso está documentado.
• .general é o padrão. Recorra a ele primeiro. Prompts, instruções, geração guiada e chamada de tools rodam todos sobre .general; a especialização é a última alavanca a puxar.
• .contentTagging pertence ao guia de content tagging da Apple: identificar tópicos, ações, objetos e emoções no texto de entrada, e recuar para .general quando os limites declarados pela Apple não couberem.⁵
• O terceiro trilho (adapters customizados, o tipo Adapter, o entitlement, o toolkit) é onde mora a complexidade operacional. Outro post.

O que é, de fato, o SystemLanguageModel

A Apple descreve SystemLanguageModel como o modelo de linguagem on-device para tarefas de geração de texto, com default como modelo base. A disponibilidade é estado de runtime: elegibilidade do dispositivo, configurações do Apple Intelligence e prontidão do modelo, tudo importa antes de um app exibir UI apoiada pelo modelo.¹

A documentação da Apple lista as plataformas do modelo (iOS, iPadOS, Mac Catalyst, macOS, visionOS, todas 26.0+) e duas versões atuais do modelo: uma para os releases 26.0–26.3 e outra para 26.4. A Apple atualiza o modelo on-device em atualizações rotineiras do OS.¹

A disponibilidade é verificada em runtime. SystemLanguageModel.availability é um enum Availability com os seguintes cases, 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

O guia geral da Apple diz que o modelo on-device suporta geração e compreensão de texto para as tarefas abaixo, incluindo Generate tags from text.⁴

A lista do que evitar da Apple é separada: matemática básica, criação de código e raciocínio lógico.⁴

Note que “generate tags from text” aparece na tabela de bom desempenho para o modelo geral. Esse é um contexto importante para a decisão de especialização logo abaixo.

O trilho geral é onde a Apple documenta prompts, instruções, geração guiada, chamada de tools e opções de geração.⁴

A janela de contexto é de 4.096 tokens para o modelo do 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 instruções, prompts e saídas contam todos para o limite. Quando uma sessão excede o limite, o framework lança LanguageModelSession.GenerationError.exceededContextWindowSize(_:).⁴

O segundo trilho: .contentTagging

SystemLanguageModel.UseCase está 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 cases documentados. Se um artigo nomeia um terceiro caso de uso, o artigo está inventando.

.contentTagging tem um formato diferente de .general. O guia da Apple descreve o modelo contentTagging como aquele que “identifies topics, actions, objects, and emotions in input text” e produz tags como “one to a few lowercase words.”⁵ O modelo é construído para avaliar a entrada em vez de responder de forma conversacional: “It isn’t a typical language model that responds to a query from a person: instead, it evaluates and groups the input you provide.”⁵

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 initializer 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 contentTagging integra com Generable, então você pode definir um tipo Swift que captura o formato de tags que 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
)

Observação comportamental da Apple: “For very short input queries, topic and emotion tagging instructions provide the best results. Actions or object lists will be too specific, and may repeat the words in the query.”⁵ O modelo contentTagging também “respects the output format you want, even in the absence of instructions”, então o formato Generable carrega mais peso do que um system prompt extenso carregaria.

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

A Apple dá a regra de decisão diretamente. Use .general para tags fora de ações, objetos, emoções ou tópicos; para hashtags; para fluxos de tagging via tool calling; e para restrições além de maximumCount.⁵

As quatro frases exatas do guia contentTagging da Apple:⁵

1. “If you’re tagging content that’s not an action, object, emotion, or topic, use general instead.”
2. “Use the general model to generate content like hashtags for social media posts.”
3. “If you adopt the tool calling API, and want to generate tags, use general and pass the Tool output to the content tagging model.”
4. “If you have a complex set of constraints on tagging that are more complicated than the maximum count support of the tagging model, use general instead.”

Escolha .contentTagging somente quando a tarefa for tagging de texto nas quatro categorias documentadas pela Apple e as restrições de saída couberem em maximumCount. Se nem .general nem .contentTagging couberem, deixe a decisão sobre adapter customizado para o post sobre o ciclo de vida do adapter.⁵

O que a Apple não publicou

A Apple documenta .contentTagging como um modelo de content tagging adaptado, mas não publica o mecanismo de adaptação, deltas de benchmark ou propriedades estáticas adicionais de UseCase. Trate qualquer coisa além de general e contentTagging como não verificada até que developer.apple.com documente.³⁵

O próprio enquadramento da Apple sobre versionamento: “Apple will periodically update SystemLanguageModel in routine OS updates to improve the on-device model’s abilities and performance.”¹ Trate a superfície como versionada.

Conclusões

1. Dois casos de uso documentados. A página UseCase da Apple documenta general e contentTagging; não assuma um terceiro valor.³
2. Padrão para .general. Prompts + tools + geração guiada lidam com a maioria dos casos de uso 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 couber. Tópicos, ações, objetos, emoções. Tags em minúsculas com uma a poucas palavras. Restrições no nível de maximumCount. Qualquer coisa além disso, recue.
4. Leia as regras “use general instead” da Apple. São quatro frases concretas no guia contentTagging.⁵ Cada uma é um limite real.
5. O caminho do adapter customizado é uma decisão separada. Superfície diferente, ciclo de vida diferente, post diferente.

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

FAQ

Quantos valores existem em SystemLanguageModel.UseCase?

Duas propriedades estáticas conforme documentação atual: .general e .contentTagging.³ Se você vir um terceiro valor referenciado em um tutorial ou em uma resposta gerada por LLM, verifique-o em developer.apple.com antes de adotá-lo.

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

Use .contentTagging quando a tarefa for 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 correta: tagging que não se encaixa nessas quatro categorias, geração de hashtags, pipelines de tags que passam por tool calls e restrições de tagging mais ricas do que maximumCount.⁵

O modelo contentTagging aceita instruções arbitrárias como o modelo geral aceita?

Ele aceita instruções, mas o design do modelo é avaliar a entrada em vez de responder a queries no estilo de usuário. O guia da Apple observa que o modelo contentTagging “respects the output format you want, even in the absence of instructions”, então 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 do sistema.⁴ A razão token por 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:?

A Apple documenta init(useCase:guardrails:) e publica código de exemplo de content tagging que chama SystemLanguageModel(useCase: .contentTagging). Não verifiquei o parâmetro guardrails com valor padrão compilando contra o SDK do iOS 26.¹⁵

Referências