Foundation Models 사용 사례: General vs Content Tagging

Apple의 SystemLanguageModel 문서는 기본 모델, 사용 사례, 어댑터 순으로 시작합니다. SystemLanguageModel.default는 기본 모델이며, SystemLanguageModel.UseCase는 general과 contentTagging을 문서화하고, 커스텀 어댑터는 별도로 다루는 개발자 학습 경로입니다.¹²³

Tool 프로토콜에 관한 이전 글에서는 기본 모델로 유용한 작업을 수행하는 방법을 다뤘습니다. 이 글이 답하는 질문은 그다음 단계입니다. 프롬프팅과 도구를 결합한 기본 모델로 충분한 시점은 언제이며, Apple의 .contentTagging 사용 사례가 자기 자리를 정당화하는 시점은 언제인가? 커스텀 어댑터 경로는 별도의 글로 다룹니다. 개발자가 관리하는 라이프사이클은 표면적이 너무 넓어서 의사결정 기준과 함께 다루기 어렵기 때문입니다.

TL;DR

• SystemLanguageModel.UseCase는 .general과 .contentTagging 두 개의 정적 프로퍼티를 가진 구조체입니다.³ 다른 사용 사례는 문서화되어 있지 않습니다.
• .general이 기본값입니다. 먼저 이것부터 사용하세요. 프롬프팅, 인스트럭션, 가이디드 생성, 도구 호출은 모두 .general 위에서 동작합니다. 특수화는 마지막에 당기는 레버입니다.
• .contentTagging은 Apple의 콘텐츠 태깅 가이드에 속합니다. 입력 텍스트에서 주제, 동작, 객체, 감정을 식별하며, Apple이 명시한 경계에 맞지 않을 경우 .general로 되돌아갑니다.⁵
• 세 번째 레일(커스텀 어댑터, Adapter 타입, 엔타이틀먼트, 툴킷)은 운영상 복잡도가 큽니다. 이는 다른 글에서 다룹니다.

SystemLanguageModel의 실체

Apple은 SystemLanguageModel을 텍스트 생성 작업을 위한 온디바이스 언어 모델로 설명하며, default를 기본 모델로 둡니다. 가용성은 런타임 상태입니다. 디바이스 자격 요건, Apple Intelligence 설정, 모델 준비 상태가 모두 모델 기반 UI를 보여주기 전에 중요합니다.¹

Apple 문서는 모델이 지원하는 플랫폼(iOS, iPadOS, Mac Catalyst, macOS, visionOS, 모두 26.0+)과 현재 두 가지 모델 버전(OS 릴리스 26.0–26.3용과 26.4용)을 명시합니다. Apple은 일상적인 OS 업데이트를 통해 온디바이스 모델을 갱신합니다.¹

가용성은 런타임에 확인합니다. SystemLanguageModel.availability는 Apple 샘플 코드에 문서화된 다음 케이스를 포함하는 Availability 열거형입니다.¹

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은 시스템이 완전히 준비되었을 때만 true를 반환하는 편의 게터입니다.¹ 호출 전에 항상 확인하세요.

첫 번째 레일: 일반 모델 프롬프팅

Apple의 일반 가이드는 온디바이스 모델이 다음 작업에 대한 텍스트 생성과 이해를 지원한다고 명시하며, 여기에는 텍스트로부터 태그 생성도 포함됩니다.⁴

Apple의 회피 목록은 별도입니다. 기초 수학, 코드 작성, 논리적 추론입니다.⁴

“텍스트로부터 태그 생성”이 일반 모델의 잘하는 작업 표에 등장한다는 점에 주목하세요. 이는 아래 특수화 결정에서 중요한 맥락입니다.

일반 레일은 Apple이 프롬프트, 인스트럭션, 가이디드 생성, 도구 호출, 생성 옵션을 문서화하는 곳입니다.⁴

시스템 모델의 컨텍스트 윈도우는 4,096 토큰입니다.⁴ Apple은 영어, 스페인어, 독일어 같은 언어에서는 토큰 하나가 3~4개 문자에 해당하고, 일본어, 중국어, 한국어 같은 언어에서는 한 문자당 한 토큰이라고 설명합니다. 인스트럭션, 프롬프트, 출력 모두 한도에 포함됩니다. 세션이 한도를 초과하면 프레임워크는 LanguageModelSession.GenerationError.exceededContextWindowSize(_:)를 던집니다.⁴

두 번째 레일: .contentTagging

SystemLanguageModel.UseCase는 두 개의 정적 프로퍼티를 가진 struct(열거형이 아님)로 문서화됩니다.³

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

다른 문서화된 케이스는 없습니다. 어떤 글이 세 번째 사용 사례를 거론한다면, 그 글이 지어낸 것입니다.

.contentTagging은 .general과는 다른 형태입니다. Apple 가이드는 contentTagging 모델을 “입력 텍스트에서 주제, 동작, 객체, 감정을 식별”하며 태그를 “한 단어에서 몇 개 단어의 소문자”로 생성하는 모델로 설명합니다.⁵ 이 모델은 대화형으로 응답하기보다 입력을 평가하도록 만들어졌습니다. “사람의 질의에 응답하는 일반적인 언어 모델이 아닙니다. 대신 제공한 입력을 평가하고 그룹화합니다.”⁵

.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.
        """
)

문서화된 편의 이니셜라이저는 init(useCase:guardrails:)입니다.¹ Apple 샘플 코드는 guardrails 인자 없이 이를 호출하는데, 이는 guardrails가 호출 지점에서 기본값을 가진다는 점을 시사합니다.

contentTagging 모델은 Generable과 통합되므로, 원하는 태그의 형태를 포착하는 Swift 타입을 정의할 수 있습니다.

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

Apple의 동작 관련 노트: “매우 짧은 입력 질의의 경우, 주제 및 감정 태깅 인스트럭션이 가장 좋은 결과를 제공합니다. 동작 또는 객체 목록은 너무 구체적이며, 질의에 사용된 단어를 반복할 수 있습니다.”⁵ contentTagging 모델은 또한 “인스트럭션이 없더라도 원하는 출력 형식을 존중”하므로, Generable 형태가 장황한 시스템 프롬프트보다 더 큰 비중을 가집니다.

의사결정 트리(Apple의 표현 그대로)

Apple은 결정 규칙을 직접 제시합니다. 동작, 객체, 감정, 주제 외 태그의 경우, 해시태그의 경우, 도구 호출 태그 흐름의 경우, 그리고 maximumCount 이상의 제약 조건에 대해 .general을 사용하세요.⁵

Apple contentTagging 가이드의 정확한 네 문장:⁵

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은 작업이 Apple의 문서화된 네 카테고리로 텍스트를 태깅하고 출력 제약이 maximumCount에 들어맞을 때만 선택하세요. .general이나 .contentTagging 둘 다 맞지 않는다면, 커스텀 어댑터 결정은 어댑터 라이프사이클 글에 맡기세요.⁵

Apple이 공개하지 않은 것

Apple은 .contentTagging을 적응된 콘텐츠 태깅 모델로 문서화하지만, 적응 메커니즘, 벤치마크 차이, 추가 UseCase 정적 프로퍼티는 공개하지 않습니다. general과 contentTagging 외의 모든 것은 developer.apple.com이 문서화하기 전까지 검증되지 않은 것으로 간주하세요.³⁵

버전 관리에 대한 Apple 자체 입장: “Apple은 온디바이스 모델의 능력과 성능을 개선하기 위해 일상적인 OS 업데이트를 통해 SystemLanguageModel을 주기적으로 갱신할 것입니다.”¹ 이 표면을 버전이 있는 것으로 취급하세요.

핵심 정리

1. 두 개의 문서화된 사용 사례. Apple의 UseCase 페이지는 general과 contentTagging을 문서화합니다. 세 번째 값을 가정하지 마세요.³
2. .general을 기본값으로. 프롬프팅 + 도구 + 가이디드 생성으로 온디바이스 모델이 설계된 대부분의 사용 사례를 처리할 수 있습니다. 특수화는 첫 번째가 아니라 마지막 레버입니다.
3. Apple이 문서화한 형태에 맞을 때만 .contentTagging을 선택하세요. 주제, 동작, 객체, 감정. 한 단어에서 몇 단어의 소문자 태그. maximumCount 수준의 제약. 그 이상은 되돌아가세요.
4. Apple의 “use general instead” 규칙을 읽으세요. contentTagging 가이드에 네 개의 구체적인 문장이 있습니다.⁵ 각각이 실제 경계입니다.
5. 커스텀 어댑터 경로는 별도의 결정입니다. 다른 표면적, 다른 라이프사이클, 다른 글입니다.

전체 Apple Ecosystem 클러스터: 프레임워크의 기본 요소를 다루는 온디바이스 LLM과 Tool 프로토콜, 인앱과 개발자 도구 LLM을 가르는 에이전틱 워크플로 분리, 세 가지 모두를 아우르는 라우팅 질문에 대한 App Intents vs MCP. 허브는 Apple Ecosystem Series에 있습니다. AI 에이전트와 함께하는 더 넓은 iOS 맥락은 iOS Agent Development guide를 참고하세요.

FAQ

SystemLanguageModel.UseCase 값은 몇 개입니까?

현재 문서화된 두 개의 정적 프로퍼티: .general과 .contentTagging입니다.³ 튜토리얼이나 LLM이 생성한 답변에서 세 번째 값을 보게 된다면, 채택하기 전에 developer.apple.com에서 검증하세요.

.general을 단순히 프롬프팅하는 대신 .contentTagging은 언제 사용해야 합니까?

작업이 입력 텍스트에서 주제, 동작, 객체, 감정을 식별하고 짧은 소문자 태그를 반환하는 것일 때 .contentTagging을 사용하세요. Apple 가이드는 대신 .general이 정답인 네 가지 시나리오를 명시합니다. 네 카테고리에 맞지 않는 태깅, 해시태그 생성, 도구 호출을 거치는 태그 파이프라인, maximumCount보다 풍부한 태깅 제약입니다.⁵

contentTagging 모델은 일반 모델처럼 임의의 인스트럭션을 받습니까?

인스트럭션을 받기는 하지만, 이 모델의 설계는 사용자 스타일의 질의에 응답하기보다 입력을 평가하는 것입니다. Apple 가이드는 contentTagging 모델이 “인스트럭션이 없더라도 원하는 출력 형식을 존중”한다고 명시하므로, 긴 프롬프트가 아니라 @Guide 어노테이션이 붙은 @Generable 형태가 제약을 담당합니다.⁵

온디바이스 모델의 컨텍스트 윈도우는 어떻게 됩니까?

시스템 모델은 4,096 토큰입니다.⁴ 토큰 대 문자 비율은 영어/스페인어/독일어에서 대략 한 토큰당 3~4개 문자, 일본어/중국어/한국어에서는 한 문자당 한 토큰입니다.⁴ 세션이 한도를 초과하면 프레임워크는 LanguageModelSession.GenerationError.exceededContextWindowSize(_:)를 던집니다.⁴

Apple 샘플 코드는 왜 guardrails: 없이 SystemLanguageModel(useCase:)를 호출합니까?

Apple은 init(useCase:guardrails:)를 문서화하고, SystemLanguageModel(useCase: .contentTagging)을 호출하는 콘텐츠 태깅 샘플 코드를 공개합니다. iOS 26 SDK에 대해 컴파일하여 기본값이 적용된 guardrails 파라미터를 검증하지는 않았습니다.¹⁵

References