Foundation Models — przypadki użycia: general vs content tagging

Dokumentacja SystemLanguageModel od Apple zaczyna się od modelu bazowego, następnie przechodzi do przypadków użycia, a potem do adapterów. SystemLanguageModel.default to model bazowy; SystemLanguageModel.UseCase dokumentuje general oraz contentTagging; własne adaptery to ścieżka trenowana przez programistę, omawiana osobno.¹²³

Wcześniejszy wpis o protokole Tool opisywał, jak skłonić domyślny model do wykonywania użytecznej pracy. Pytanie, na które odpowiada ten wpis, jest następne: kiedy domyślny model z promptingiem i narzędziami wystarczy, a kiedy przypadek użycia .contentTagging od Apple zasługuje na swoje miejsce? Ścieżka własnych adapterów to osobny wpis; cykl życia zarządzany przez programistę ma zbyt dużą powierzchnię, aby dzielić ją z kryterium decyzyjnym.

TL;DR

• SystemLanguageModel.UseCase to struktura z dwoma statycznymi właściwościami: .general i .contentTagging.³ Żadne inne przypadki użycia nie są udokumentowane.
• .general jest domyślny. Po niego należy sięgać w pierwszej kolejności. Prompting, instrukcje, guided generation oraz wywoływanie narzędzi — wszystko to działa na bazie .general; specjalizacja to ostatnia dźwignia, po którą warto sięgnąć.
• .contentTagging należy do przewodnika content-tagging Apple: identyfikuje tematy, akcje, obiekty i emocje w tekście wejściowym, a następnie pozwala wrócić do .general, gdy podane przez Apple granice nie pasują.⁵
• Trzecia szyna (własne adaptery, typ Adapter, uprawnienie, toolkit) to miejsce, gdzie kryje się złożoność operacyjna. Inny wpis.

Czym właściwie jest SystemLanguageModel

Apple opisuje SystemLanguageModel jako model językowy działający na urządzeniu, przeznaczony do zadań generowania tekstu, z default jako modelem bazowym. Dostępność jest stanem runtime: zarówno kwalifikowalność urządzenia, ustawienia Apple Intelligence, jak i gotowość modelu mają znaczenie, zanim aplikacja pokaże UI oparty na modelu.¹

Dokumentacja Apple wymienia platformy modelu (iOS, iPadOS, Mac Catalyst, macOS, visionOS, wszystkie 26.0+) oraz dwie aktualne wersje modelu: jedna dla wydań OS 26.0–26.3 i druga dla 26.4. Apple aktualizuje model on-device w ramach rutynowych aktualizacji systemu.¹

Dostępność jest sprawdzana w runtime. SystemLanguageModel.availability jest enumem Availability z następującymi przypadkami, jak udokumentowano w przykładowym kodzie 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 to wygodny getter, który zwraca true tylko wtedy, gdy system jest w pełni gotowy.¹ Należy zawsze sprawdzać przed wywołaniem.

Pierwsza szyna: prompting modelu general

Ogólny przewodnik Apple stwierdza, że model on-device wspiera generowanie tekstu i jego rozumienie dla poniższych zadań, w tym Generate tags from text.⁴

Lista rzeczy, których należy unikać, jest osobna: podstawowa matematyka, generowanie kodu i rozumowanie logiczne.⁴

Warto zauważyć, że “generate tags from text” pojawia się w tabeli czego model robi dobrze dla modelu general. To istotny kontekst dla decyzji o specjalizacji, omawianej poniżej.

Szyna general to miejsce, gdzie Apple dokumentuje prompty, instrukcje, guided generation, wywoływanie narzędzi oraz opcje generowania.⁴

Okno kontekstu wynosi 4096 tokenów dla modelu systemowego.⁴ Apple zaznacza, że jeden token odpowiada trzem lub czterem znakom w językach takich jak angielski, hiszpański czy niemiecki, oraz jednemu tokenowi na znak w językach takich jak japoński, chiński czy koreański. Instrukcje, prompty i wyjścia — wszystko to liczy się do limitu. Gdy sesja go przekroczy, framework rzuca LanguageModelSession.GenerationError.exceededContextWindowSize(_:).⁴

Druga szyna: .contentTagging

SystemLanguageModel.UseCase jest udokumentowany jako struct (nie enum) z dwiema statycznymi właściwościami:³

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

Nie ma żadnych innych udokumentowanych przypadków. Jeśli jakiś artykuł wymienia trzeci przypadek użycia, to artykuł sobie go zmyśla.

.contentTagging ma inny kształt niż .general. Przewodnik Apple opisuje model contentTagging jako taki, który “identifies topics, actions, objects, and emotions in input text” i produkuje tagi w formie “one to a few lowercase words”.⁵ Model jest zbudowany do oceniania danych wejściowych, a nie do prowadzenia rozmowy: “It isn’t a typical language model that responds to a query from a person: instead, it evaluates and groups the input you provide.”⁵

Ładowanie modelu z .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.
        """
)

Udokumentowany inicjalizator wygodny to init(useCase:guardrails:).¹ Przykładowy kod Apple wywołuje go bez argumentu guardrails, co sugeruje, że guardrails ma wartość domyślną w miejscu wywołania.

Model contentTagging integruje się z Generable, zatem można zdefiniować typ Swift, który ujmuje kształt tagów, jakich się oczekuje:

@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
)

Uwaga Apple dotycząca zachowania: “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.”⁵ Model contentTagging również “respects the output format you want, even in the absence of instructions”, więc kształt Generable niesie większą wagę niż rozbudowany prompt systemowy.

Drzewo decyzyjne (słowami samego Apple)

Apple podaje regułę decyzyjną wprost. Należy używać .general dla tagów spoza akcji, obiektów, emocji czy tematów; dla hashtagów; dla przepływów tagowania z wywoływaniem narzędzi; oraz dla ograniczeń wykraczających poza maximumCount.⁵

Cztery dokładne zdania z przewodnika contentTagging 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.”

.contentTagging warto wybrać tylko wtedy, gdy zadaniem jest tagowanie tekstu w czterech udokumentowanych przez Apple kategoriach, a ograniczenia wyjścia mieszczą się w maximumCount. Jeśli ani .general, ani .contentTagging nie pasują, decyzję o własnym adapterze należy zostawić wpisowi o cyklu życia adapterów.⁵

Czego Apple nie opublikowało

Apple dokumentuje .contentTagging jako zaadaptowany model content-tagging, ale nie publikuje mechanizmu adaptacji, różnic w benchmarkach ani dodatkowych statycznych właściwości UseCase. Wszystko poza general i contentTagging należy traktować jako niezweryfikowane do czasu, aż developer.apple.com to udokumentuje.³⁵

Własne ujęcie Apple kwestii wersjonowania: “Apple will periodically update SystemLanguageModel in routine OS updates to improve the on-device model’s abilities and performance.”¹ Powierzchnię należy traktować jako wersjonowaną.

Wnioski

1. Dwa udokumentowane przypadki użycia. Strona UseCase Apple dokumentuje general i contentTagging; nie należy zakładać trzeciej wartości.³
2. Domyślnie .general. Prompting + narzędzia + guided generation pokrywa większość zastosowań, do których model on-device został zaprojektowany. Specjalizacja to ostatnia dźwignia, nie pierwsza.
3. .contentTagging warto wybierać tylko wtedy, gdy udokumentowany przez Apple kształt pasuje. Tematy, akcje, obiekty, emocje. Tagi z jednego do kilku małych liter słów. Ograniczenia na poziomie maximumCount. Cokolwiek więcej — wracamy do general.
4. Należy przeczytać reguły Apple “use general instead”. Są to cztery konkretne zdania w przewodniku contentTagging.⁵ Każde z nich to realna granica.
5. Ścieżka własnego adaptera to osobna decyzja. Inna powierzchnia, inny cykl życia, inny wpis.

Pełny klaster Apple Ecosystem: protokół on-device LLM i Tool dla prymitywów frameworka; podział agentic workflow między LLMy in-app i developer-tooling; App Intents vs MCP dla pytania o routing w obrębie wszystkich trzech. Hub znajduje się w Apple Ecosystem Series. Szerszy kontekst iOS-z-AI-agentami opisuje iOS Agent Development guide.

FAQ

Ile jest wartości SystemLanguageModel.UseCase?

Dwie statyczne właściwości, jak obecnie udokumentowano: .general i .contentTagging.³ Jeśli w jakimś tutorialu lub odpowiedzi wygenerowanej przez LLM pojawi się trzecia wartość, należy ją zweryfikować na developer.apple.com przed użyciem.

Kiedy warto użyć .contentTagging zamiast po prostu promptować .general?

.contentTagging warto użyć wtedy, gdy zadaniem jest identyfikacja tematów, akcji, obiektów lub emocji w tekście wejściowym i zwracanie krótkich tagów małymi literami. Przewodnik Apple wymienia cztery scenariusze, w których to .general jest właściwą odpowiedzią: tagowanie, które nie pasuje do tych czterech kategorii, generowanie hashtagów, potoki tagowania prowadzące przez wywołania narzędzi oraz ograniczenia tagowania bogatsze niż maximumCount.⁵

Czy model contentTagging akceptuje dowolne instrukcje, tak jak model general?

Akceptuje instrukcje, ale jego konstrukcja przewiduje ocenianie danych wejściowych, a nie odpowiadanie na zapytania w stylu użytkownika. Przewodnik Apple zaznacza, że model contentTagging “respects the output format you want, even in the absence of instructions”, zatem to kształt @Generable z adnotacjami @Guide niesie ograniczenie, a nie długi prompt.⁵

Jakie jest okno kontekstu dla modelu on-device?

4096 tokenów dla modelu systemowego.⁴ Stosunek tokenów do znaków wynosi w przybliżeniu od trzech do czterech znaków na token w angielskim/hiszpańskim/niemieckim oraz jeden token na znak w japońskim/chińskim/koreańskim.⁴ Framework rzuca LanguageModelSession.GenerationError.exceededContextWindowSize(_:), gdy sesja przekroczy limit.⁴

Dlaczego przykładowy kod Apple wywołuje SystemLanguageModel(useCase:) bez guardrails:?

Apple dokumentuje init(useCase:guardrails:) i publikuje przykładowy kod content-tagging, który wywołuje SystemLanguageModel(useCase: .contentTagging). Domyślnego parametru guardrails nie zweryfikowałem przez kompilację względem SDK iOS 26.¹⁵

Bibliografia