基础模型用例：何时专门化，何时只需提示

Foundation Models 中的设备端模型并非单一事物。Apple 提供了一个用于通用提示的默认 SystemLanguageModel，以及一个由 Apple 管理的、专门用于内容标签的特化版本。¹ 该框架还允许开发者训练并加载自己的适配器。² 三条轨道，一棵决策树，以及一个明确命名两个 UseCase 值的文档页面。

之前关于 Tool 协议 的文章介绍了如何让默认模型完成有用的工作。本文要回答的是下一个问题：何时使用默认模型加上提示和工具就够了，何时 Apple 的 .contentTagging 用例值得占据一席之地？自定义适配器路径将另写一篇；开发者管理的生命周期涉及面太广，无法与决策准则共享一篇文章。

TL;DR

• SystemLanguageModel.UseCase 是一个具有两个静态属性的结构体：.general 和 .contentTagging。³ 没有其他文档化的用例。
• .general 是默认值。请优先使用它。提示、指令、引导生成和工具调用都构建在 .general 之上；专门化是最后才拉动的杠杆。
• .contentTagging 是为一项工作量身打造的：识别输入文本中的主题、动作、对象和情感，并返回一到几个单词的小写标签。⁴ Apple 自己的指南会告诉您何时应改用 .general。
• 第三条轨道（自定义适配器、Adapter 类型、entitlement、工具包）才是运维复杂性所在之处。另一篇文章再讨论。

SystemLanguageModel 究竟是什么

SystemLanguageModel 是 FoundationModels 框架中的一个 final class，可在 iOS 26.0+、iPadOS 26.0+、Mac Catalyst 26.0+、macOS 26.0+ 和 visionOS 26.0+ 上使用。¹ Apple 将其描述为”一个能够执行文本生成任务的设备端大语言模型”。

有两个事实塑造了它的使用方式。第一，SystemLanguageModel.default 返回模型的基础版本。¹ 这是所有未专门化场景的入口点。第二，Apple 会在操作系统更新中更新该模型：截至撰写本文时，Apple 的文档列出了两个模型版本，一个用于 iOS、iPadOS、macOS 和 visionOS 26.0–26.3，另一个用于 26.4。¹ 应用不会固定到特定版本；框架返回操作系统当前正在运行的任何模型。

可用性会在运行时检查。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 将默认模型定位为适用于广泛任务的合适工具。该框架的通用指南列举了 Apple 称设备端模型擅长处理的能力：⁴

Apple 也明确指出了设备端模型不适用的场景：⁴

请注意，”从文本生成标签”出现在通用模型的擅长表中。这是下文关于专门化决策的重要背景。

默认轨道拥有完整的工具集：指令、提示、通过 Generable 进行的引导生成、通过 Tool 协议进行的工具调用、温度等生成选项。大多数采用 Foundation Models 的应用都将运行在这条轨道上，从不触及用例指定符。

系统模型的上下文窗口为 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 自己的话）

用例 API 中有趣的部分在于,Apple 的文档明确指出了何时不应专门化。来自 contentTagging 指南：⁵

1. “如果您正在标记的内容不是动作、对象、情感或主题,请改用 general。”
2. “使用 general 模型生成像社交媒体帖子的话题标签这样的内容。”
3. “如果您采用了工具调用 API 并希望生成标签,请使用 general 并将 Tool 输出传递给 content tagging 模型。”
4. “如果您对标签有一组复杂的约束,这些约束比标签模型的最大数量支持更复杂,请改用 general。”

将这四点结合起来读。contentTagging 模型范围狭窄：主题、动作、对象、情感。其他一切（话题标签生成、涉及工具调用的标签流水线、约束比 maximumCount 更丰富的标签输出）都归通用模型管。

对于一款认为自己需要标签的应用,务实的决策准则是：

默认使用 .general。 它处理 Apple 表格描述的广泛生成任务,包括”从文本生成标签”。大多数应用就此止步。

仅在以下情况下选择 .contentTagging： 输入是文本形态,输出是一小组单词或几个单词的标签,清晰地落入 Apple 的四个类别（主题/动作/对象/情感）之一,并且约束符合 maximumCount。Apple 给出的示例就是典型模式：希望按帖子打标签以驱动主题面板的社交应用、希望自动打标签的电子邮件客户端、希望聚合趋势信号的内容商店。

仅在两条轨道都不合适,且用例足够高价值以吸纳训练和发布与特定系统模型版本绑定的适配器所带来的运维成本时,才退而采用自定义适配器。 自定义适配器路径有单独的文档；其生命周期复杂性（工具包版本、再训练周期、分发）值得专文论述。

Apple 尚未公布的内容

有几件事您会看到被人猜测,但并未出现在文档化的范围内：

• Apple 用以将模型专门化为 .contentTagging 的机制。Apple 的 contentTagging 指南将该框架描述为提供”一个适配的设备端系统语言模型,专门用于内容标签”。⁵ Apple 并未公布专门化机制,该句中的”适配”一词不应与开发者管理的 SystemLanguageModel.Adapter 类型混淆,后者是另一条独立的轨道。
• 其他用例值。截至当前文档,该结构体只有两个静态属性；任何第三种情形都需要在未来的操作系统更新中发布。
• 不能保证 .general 和 .contentTagging 永远共存。Apple 表示”Apple 将定期在常规操作系统更新中更新 SystemLanguageModel,以改进设备端模型的能力和性能”。¹ 请将该接口视为带版本的。
• .contentTagging 与 .general 在标签基准上的具体质量数据。Apple 将选择构架为”是否适合任务”,而非质量排行榜。

如果一篇文章（无论是这篇还是其他任何文章）对适配器机制做出了不在 developer.apple.com 上的定量声明,请默认将该声明视为错误。

这两条轨道实际上为您带来什么

第二条轨道并不是”模型变得更好”,而是”模型为一项工作而生,且 Apple 已记录了何时选用它”。这改变了经济性：

1. 针对标签任务的提示工程面更小。 contentTagging 模型”在没有指令的情况下也会遵循您想要的输出格式”。⁵ 您可以依靠 @Generable 和 maximumCount,而不是通用模型所需的多段提示。
2. 受约束的语义形态。 该模型在输入词项之间寻找相似性,并产出语义一致的标签（Apple 的示例：对于”hi”“hello”“yo”,”greet”作为主题标签浮现）。⁵ 这正是面向用户生成内容的聚合分析所需要的。
3. 一份文档化的决策准则。 Apple 告诉您他们的专门化何时合适,何时应当回退。该准则是用例 API 中最有价值的部分：它是对应用开发者本来要从第一性原理上反复争论的问题给出的鲜明态度的回答。

成本同样清晰：.contentTagging 绑定到一种任务形态。任何超出该形态的内容都要回到 .general,其成败取决于提示和 Generable 的设计。

要点

1. 今天有两条轨道,未来可能更多。 .general 和 .contentTagging 是 Apple 已记录的仅有的两个 UseCase 静态属性。不要写假设存在其他选项的代码。
2. 默认使用 .general。 提示 + 工具 + 引导生成可以处理设备端模型所设计的大多数用例。专门化是最后的杠杆,而不是首选。
3. 仅在 Apple 文档化的形态契合时,才选择 .contentTagging。 主题、动作、对象、情感。一到几个单词的小写标签。maximumCount 级别的约束。任何更多需求,请回退。
4. 请阅读 Apple 的”改用 general”规则。 它们是 contentTagging 指南中四个具体的句子。⁵ 每一条都是真实的边界。
5. 自定义适配器路径是另一项决策。 不同的接口面、不同的生命周期、另一篇文章。

完整的 Apple 生态系列：设备端 LLM 与 Tool 协议 介绍框架的原语；智能体工作流划分 区分应用内和开发者工具型 LLM；App Intents 与 MCP 对比 探讨三者间的路由问题。中枢页面位于 Apple 生态系列。如需更宽泛的 iOS 与 AI 智能体上下文,请参阅 iOS 智能体开发指南。

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:？

文档中的便捷初始化器是 init(useCase:guardrails:)。¹ Apple 的 contentTagging 指南在调用时未传入 guardrails 参数,这表明 guardrails 在调用处带有默认值。两参数形式是文档化的接口；单参数形式是 Apple 已发布示例代码所展示的形式。

参考资料