Foundation Models 使用场景：通用与内容标记

Apple 的 SystemLanguageModel 文档以基础模型开篇，接着是使用场景，最后是适配器。SystemLanguageModel.default 是基础模型；SystemLanguageModel.UseCase 记录了 general 和 contentTagging；自定义适配器则是开发者训练的路径，单独说明。¹²³

之前关于 Tool 协议 的文章介绍了如何让默认模型完成实用工作。本文回答的是接下来的问题：何时使用默认模型加上提示词和工具就足够了，何时 Apple 的 .contentTagging 使用场景才值得占据一席之地？自定义适配器路径是另一篇文章的主题；开发者管理的生命周期所涉及的内容过于广泛，无法与决策框架放在一起讨论。

TL;DR

• SystemLanguageModel.UseCase 是一个具有两个静态属性的结构体：.general 和 .contentTagging。³ 没有其他文档化的使用场景。
• .general 是默认选项。优先使用它。提示词、指令、引导式生成和工具调用全都构建在 .general 之上；专门化是最后才动用的杠杆。
• .contentTagging 属于 Apple 的内容标记指南：识别输入文本中的主题、动作、对象和情绪，当 Apple 所述的边界不适用时则回退到 .general。⁵
• 第三条路径（自定义适配器、Adapter 类型、entitlement、工具包）才是运维复杂度的所在。另一篇文章再讲。

SystemLanguageModel 究竟是什么

Apple 将 SystemLanguageModel 描述为用于文本生成任务的设备端语言模型，其中 default 是基础模型。可用性属于运行时状态：在应用展示模型支持的 UI 之前，设备资格、Apple Intelligence 设置以及模型就绪状态都至关重要。¹

Apple 的文档列出了模型支持的平台（iOS、iPadOS、Mac Catalyst、macOS、visionOS，均为 26.0+），以及当前的两个模型版本：一个用于 26.0–26.3 的系统版本，另一个用于 26.4。Apple 会在常规系统更新中迭代设备端模型。¹

可用性需在运行时检查。SystemLanguageModel.availability 是一个 Availability 枚举，根据 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 是一个便捷的 getter，仅当系统完全就绪时才返回 true。¹ 调用之前务必检查。

第一条路径：提示通用模型

Apple 的通用指南指出，设备端模型支持以下任务的文本生成与理解，其中包括 Generate tags from text。⁴

Apple 的回避清单则是另外列出的：基础数学、代码生成和逻辑推理。⁴

请注意，”generate tags from text” 出现在通用模型的擅长事项表格中。这对下文的专门化决策来说是重要的背景信息。

通用路径正是 Apple 用来记录提示词、指令、引导式生成、工具调用和生成选项的地方。⁴

系统模型的上下文窗口为 4,096 个 tokens。⁴ Apple 指出，在英语、西班牙语或德语等语言中，一个 token 大约对应三到四个字符；而在日语、汉语或韩语中，则是每个字符对应一个 token。指令、提示词和输出全都计入这一上限。当会话超出限制时，框架会抛出 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.”

仅当任务属于 Apple 文档化的四个类别中的文本标记，且输出约束符合 maximumCount 时，才选择 .contentTagging。如果 .general 和 .contentTagging 都不合适，自定义适配器的决策请留给适配器生命周期那篇文章。⁵

Apple 尚未公开的内容

Apple 将 .contentTagging 描述为一个适配过的内容标记模型，但并未公开适配机制、基准测试差异或更多的 UseCase 静态属性。在 developer.apple.com 给出文档之前，请将 general 和 contentTagging 之外的任何说法视为未经核实。³⁵

Apple 自己关于版本管理的表述：”Apple will periodically update SystemLanguageModel in routine OS updates to improve the on-device model’s abilities and performance.”¹ 请将这一接口视作受版本控制。

要点回顾

1. 两个文档化的使用场景。 Apple 的 UseCase 页面记录了 general 和 contentTagging；不要假设存在第三个值。³
2. 默认使用 .general。 提示词 + 工具 + 引导式生成能够应对设备端模型所设计的大多数使用场景。专门化是最后的杠杆，而不是首选。
3. 仅当符合 Apple 文档化形态时才选择 .contentTagging。 主题、动作、对象、情绪。一到几个单词的小写标签。maximumCount 级别的约束。超出范围则回退。
4. 阅读 Apple 的”改用 general”规则。 它们是 contentTagging 指南中的四句具体原话。⁵ 每一句都是真实的边界。
5. 自定义适配器路径是另一项独立决策。 不同的接口范围，不同的生命周期，单独的文章。

完整的 Apple 生态系统系列文章包括：介绍框架基本组件的设备端 LLM 与 Tool 协议；关于应用内与开发者工具 LLMs 之间的代理工作流划分；以及面向所有三者路由问题的 App Intents 与 MCP 对比。系列汇总页面是 Apple 生态系统系列。要了解更广泛的 iOS 与 AI 代理的背景，请参阅 iOS Agent 开发指南。

FAQ

SystemLanguageModel.UseCase 共有多少个值？

根据当前文档，有两个静态属性：.general 和 .contentTagging。³ 如果您在某篇教程或 LLM 生成的回答中看到提及第三个值，请先到 developer.apple.com 上核实，然后再采用。

我应何时使用 .contentTagging 而不是仅对 .general 进行提示？

当任务是识别输入文本中的主题、动作、对象或情绪并返回简短的小写标签时，使用 .contentTagging。Apple 的指南列出了四种应改用 .general 的场景：不属于这四个类别的标记、话题标签生成、通过工具调用路由的标签流水线，以及比 maximumCount 更复杂的标记约束。⁵

contentTagging 模型是否像通用模型那样接受任意指令？

它接受指令，但该模型的设计是评估输入而非回应用户式的查询。Apple 的指南指出，contentTagging 模型”即便没有指令也会遵循您所要求的输出格式”，因此承载约束的是带有 @Guide 标注的 @Generable 形态，而非冗长的提示词。⁵

设备端模型的上下文窗口是多少？

系统模型为 4,096 个 tokens。⁴ token 与字符的比率大致为：英语/西班牙语/德语中每个 token 三到四个字符，日语/汉语/韩语中每个字符一个 token。⁴ 当会话超出该限制时，框架会抛出 LanguageModelSession.GenerationError.exceededContextWindowSize(_:)。⁴

为什么 Apple 的示例代码调用 SystemLanguageModel(useCase:) 时没有 guardrails:？

Apple 文档化了 init(useCase:guardrails:)，并发布了调用 SystemLanguageModel(useCase: .contentTagging) 的内容标记示例代码。我未通过针对 iOS 26 SDK 进行编译来验证默认的 guardrails 参数。¹⁵

参考资料