设备端Foundation Models LLM：工具协议

类别： 前沿随笔。本文阐述了Apple在WWDC 2025上交付的设备端LLM契约,并探讨路由问题:何时应使用LanguageModelSession,何时应使用AppIntent,何时应使用MCP,何时三者皆非。

iOS 26在每台具备Apple Intelligence能力的设备上部署了一个30亿参数的语言模型。¹ Apple将该框架命名为Foundation Models。框架是本地的。推理针对Apple silicon进行优化并在设备端运行;网络不在调用路径上。模型位于SystemLanguageModel.default,您的应用获取一个LanguageModelSession,而让该会话执行有用工作的类型化接口便是Tool协议。

Tool协议是应用开发者真正需要关注的部分。没有它,设备端LLM不过是一个聊天补全端点,与您的应用数据、用户数据或系统的其他部分都没有连接。有了它,模型可以调用类型化的Swift函数、获得类型化的返回结果,并在下一轮中对答案进行推理。工具增强的设备端生成才是该框架真正的能力所在。聊天界面只是演示而已。

核心要点

• Foundation Models在SystemLanguageModel.default处为每台符合Apple Intelligence条件的设备提供了一个30亿参数的LLM。模型是本地的;推理针对Apple silicon进行优化并在设备端运行;网络不在调用路径上。
• Tool协议是模型与您的应用之间的契约。一个工具声明类型化的Arguments,返回类型化的Output,并在构造时绑定到LanguageModelSession。
• Generable和Guide注解让模型直接生成类型化的Swift值,而不仅仅是字符串。解码器是框架的一部分,而不是您的代码。
• Foundation Models、App Intents和MCP之间的路由规则是谁在运行模型以及在何处运行。Foundation Models = 您的应用在设备端运行模型。App Intents = Apple Intelligence在设备端运行模型并路由到您的应用。MCP = 外部宿主在任意位置运行模型,并通过工具服务器接入您的应用。

框架实际提供了什么

三个原语支撑起整个框架:模型、会话和工具。²

SystemLanguageModel。 对设备端基础模型的引用。默认实例绑定到用户的设备,在符合Apple Intelligence条件的硬件上可用,并暴露能力检查接口供应用在运行时读取以决定模型是否可用。框架支持通过SystemLanguageModel(useCase:guardrails:)、自定义适配器和GenerationOptions进行配置,但您不能像针对OpenAI或Anthropic那样任意挑选云端模型ID;Apple按操作系统版本发布并更新设备端模型,框架会向您交付当前安装的版本。

LanguageModelSession。 一个跨调用保持对话状态的有状态对象。会话在构造时接收系统提示,随时间累积用户/助手轮次,并暴露用于生成响应的异步方法。会话创建轻量且可丢弃;您应按任务创建一个会话,而不是每个应用一个。冥想计时器为”总结我过去7天的练习”创建一个会话;食谱应用为”将此食谱从四人份调整为两人份”创建另一个会话。

Tool(协议)。 一个声明Arguments类型、Output类型和异步call(arguments:)函数的Swift协议。工具在构造时绑定到会话(LanguageModelSession(tools: [...], instructions: ...))。当模型决定需要使用工具时,它会发出结构化调用;框架会解码参数、运行工具、编码结果,并将其反馈到会话中以供下一轮使用。模型看不到Swift;框架完成所有的封送处理。

Tool协议的精简形态:

import FoundationModels

struct WaterEntryLookup: Tool {
    let name = "lookup_water_entries"
    let description = "Look up water intake entries for a given date range."

    @Generable
    struct Arguments {
        @Guide(description: "Start date in ISO-8601 format")
        let startDate: String

        @Guide(description: "End date in ISO-8601 format")
        let endDate: String
    }

    func call(arguments: Arguments) async throws -> ToolOutput {
        let entries = try store.entries(
            from: ISO8601DateFormatter().date(from: arguments.startDate) ?? .now,
            to: ISO8601DateFormatter().date(from: arguments.endDate) ?? .now
        )
        return ToolOutput(GeneratedContent(properties: [
            "count": entries.count,
            "total_ml": entries.reduce(0) { $0 + $1.amountMl }
        ]))
    }
}

模型看到的是工具描述和JSON形态的参数模式。Swift代码看到的是类型化的输入与类型化的输出。解码/编码边界由Apple负责。

Generable与Guide:无需解析器的类型化输出

让工具参数实现类型化的同一套注解系统,也能让模型直接生成类型化的Swift值。³ 一个@Generable结构体声明其形态;框架则约束模型的输出与之匹配。

@Generable
struct PracticeSummary {
    @Guide(description: "Single-sentence headline summarizing the user's week")
    let headline: String

    @Guide(description: "Total practice duration this week in minutes")
    let totalMinutes: Int

    @Guide(description: "Three short observations as bullet points")
    let observations: [String]
}

let session = LanguageModelSession(instructions: "You are a meditation coach.")
let summary = try await session.respond(
    to: "Summarize this week of practice given the entries.",
    generating: PracticeSummary.self
)

模型返回一个PracticeSummary值。您的代码中无需进行JSON解析,无需对”headline:”做字符串匹配,也无需为模型返回格式错误对象时准备回退方案。框架使用受约束解码,使模型逐token的输出在结构上与模式保持一致,因此结构无效的输出不会越过边界。

类型化的Swift接口正是该框架与云LLM SDK的区别所在。云SDK(OpenAI Structured Outputs、Anthropic工具使用等)同样支持受约束解码,但开发者收到的类型化值是经模式校验后的JSON对象,再作为独立步骤被解码为Codable的Swift类型。Foundation Models将这些步骤合并:@Generable宏与框架的解码器直接生成类型化的Swift值作为返回值,字段级的@Guide注解将意图传递到生成约束中。输出之所以是类型化的,是因为生成本身就是依据Swift模式进行类型化的,而不是依据开发者在Swift中重建的JSON规范。

@Guide注解是您在不写入提示的情况下向模型传达字段级意图的方式。生成的描述会成为生成约束的一部分。字段级别的guide让提示保持简洁,并使模式贴近数据本身。

路由问题的三种思路

如今,Apple为应用提供了三种协议接口,可将其领域暴露给语言模型。它们路由到不同的运行方。

Foundation Models(LanguageModelSession)。 您的应用加载设备端模型并执行推理。会话可以调用的工具是您的应用代码所定义的工具。模型从不离开设备。用户不通过Siri调用此功能;调用方是您的应用代码。其使用场景在应用内部:冥想应用使用LLM总结一周练习,食谱应用调整食谱以减少份数,饮水追踪器将”我午餐时喝了一杯”转化为结构化条目。

App Intents。 Apple Intelligence代表用户运行LLM(Apple的第一方代理),并将能力调用路由到您应用的AppIntent类型。您的应用并不运行模型。您通过App Intents框架声明类型化的操作,Apple的系统栈则根据用户请求、Spotlight查询、Siri输入或Shortcuts编排来决定何时调用它们。详见App Intents Are Apple’s New API to Your App。⁴

MCP。 外部宿主(Claude Desktop、Claude Code、Cursor、ChatGPT)运行开发者所选择的任意模型。您的应用暴露一个服务器供宿主的模型调用。模型在宿主运行的任何位置运行;工具调用通过JSON-RPC传输跨越边界。详见Two Agent Ecosystems, One Shopping List以及App Intents vs MCP中的路由问题综述。⁵

路由决策可归结为代理是谁。

                  ┌──────────────────────────────────┐
                  │  Who is the language model?       │
                  └────┬─────────────┬─────────────┬──┘
                       │             │             │
              ┌────────┴────┐ ┌──────┴──────┐ ┌────┴──────┐
              │ Your app's  │ │   Apple     │ │  External │
              │ own use of  │ │ Intelligence│ │   host's  │
              │   LLM       │ │   agent     │ │   agent   │
              └──────┬──────┘ └──────┬──────┘ └────┬──────┘
                     │               │             │
                     ▼               ▼             ▼
              Foundation Models  App Intents     MCP
              + Tool protocol   + AppEntity    + tools/list
              (on-device, your  (system runs   (host runs
               app runs model)   the model)     the model)

总结用户一周练习的冥想应用使用Foundation Models,因为应用本身想要调用模型并在应用内呈现结果。同一应用的”记录5分钟会话”能力使用App Intents,以便Siri能够调用。同一应用通过Claude Code会话调用的”显示我最近的冥想日志条目”能力使用MCP。三种不同的运行方,三种不同的契约,底层共享同一个领域层。

推理预算:框架对您的要求

在设备端运行LLM并非毫无代价。Apple silicon负责推理,但模型仍有上下文窗口、token预算以及取决于设备的实际延迟。三个约束塑造了您的框架设计:⁶

可用性因设备而异。 并非每台iOS 26设备都具备Apple Intelligence。较旧的iPhone、受限设备以及用户已禁用Apple Intelligence的设备会从SystemLanguageModel.default.availability返回不可用状态。在未检查可用性的情况下调用LanguageModelSession的代码会在运行时抛出生成错误;正确的做法是提前根据可用性状态对UI进行分支处理,并在状态不可用时提供无LLM路径。把模型当作功能开关,而不是必然保证。

延迟并非可忽略。 iPhone 16 Pro上的首token延迟对应用内交互而言是可用的;较长的生成与工具调用链则并非即时。适用于云LLM流式输出的UI模式在此同样适用;不要阻塞主线程,要展示渐进式输出,并要为用户在生成过程中导航离开的情况做好设计。

上下文窗口比云端更小。 设备端模型的上下文窗口比GPT-4级别的云模型小。长文档需要进行总结或分块处理。长对话历史需要进行裁剪。返回大型结构化负载的工具输出应返回引用(ID或键)以便下一轮按需重新获取,而不是内联整个负载。

约束集类似于为低端边缘运行时进行设计,而非面向前沿云模型。框架的便利性使其更易于使用;底层的物理限制并不会改变。

何时应选用Foundation Models

该框架最契合的场景是设备端、低摩擦的生成本身就是产品的核心:

重新格式化与改写。 将用户的自由形式笔记转换为结构化条目,润色草稿消息,总结捕获的转录。延迟容忍度中等;数据敏感性高;云推理纯属过度。

对私有数据的本地综合。 健身应用将用户的训练历史汇总为”本周”摘要。理财应用解释用户的消费模式。日记应用从一个季度的条目中提炼主题。数据不应离开设备;答案应出现在应用内;提示是有边界的。

应用内自动化的轻量级工具调用。 用户可以说”显示周二的冥想日志”的应用,使用工具获取底层记录后再格式化答案。代理是应用本身,工具是应用自己的数据层,模型是本地的。

符合类型的生成。 但凡应用原本需要手写JSON解析器或字符串模板的地方,@Generable加上@Guide都是更耐久的方案。

何时不应选用Foundation Models

在以下几种常见场景中,该框架并非合适的答案:

用户可能向Siri询问的任何事情。 “记录250毫升饮水”、“开始5分钟冥想”、“将香蕉添加到我的清单”属于App Intents。Apple Intelligence是运行方;您的应用是目的地。Foundation Models用于应用内部生成,而非Siri路由的操作。如果您把同一能力构建两次(App Intent + 带工具的LanguageModelSession),App Intent会胜出,因为用户调用的是Siri,而不是您的应用内界面。

任何应由外部LLM代理驱动的事情。 Claude Code会话接入您应用领域应通过MCP实现。应用并不运行LLM;由宿主运行;模型位于宿主放置的任何位置。Foundation Models无法服务于外部代理。

针对大型文档的繁重推理。 设备端模型很小。一份200页的合同、长代码库上下文,或对许多照片进行多图推理,这些都属于云推理(您自有的或供应商的)的范畴,以使上下文窗口和参数量与工作负载匹配。超出框架处理范围的任务会产生明确的错误:超出上下文窗口、护栏违规、不支持的区域设置。请明确地处理这些错误,而不是设计依赖模型处理超范围工作的流程。

跨设备与跨用户的工作流。 设备端模型只能访问应用传入会话的内容。跨设备同步(Watch到iPhone的计时器状态)、跨用户协作(共享清单、共享文档),以及任何受益于服务端协调的流程,都需要服务器。模型并非网络原语。

我会以何种方式重新构建我的技术栈

该框架奖励一种特定的架构选择,而这种选择在第一次实践中很容易出错。用户通过应用UI调用的能力以及LLM应当作为工具消费的能力,不应作为重复的散文路径来处理。

冥想应用可能会添加一个由LLM总结的”周回顾”面板。简单的实现是单一提示:”以下是用户本周的条目,请写一段话。”更好的实现是定义一个WeeklyEntries工具,模型在需要了解本周内容时可以调用它,并通过@Generable产出结构化的WeeklySummary输出。第一种实现脆弱(模型每次调用都必须摄入冗长的条目列表)、token开销大,且产出的是非结构化的散文。第二种实现耐久(“发生了什么”与”如何叙述”由工具调用分离开)、低成本(模型只获取所需内容)且结构化(结果是类型化的Swift值)。

该模式可与App Intents和MCP清晰地组合。同一个WeeklyEntries查询同时也是AppIntent参数解析器和MCP工具处理程序的主体。一个Swift函数;三种接口。模型调用的是与用户调用的同一个函数。

另一个架构决策:工具描述是提示的一部分。模型读取Tool.description以决定是否以及何时调用。把描述视为您真正期望未来贡献者会阅读的docstring;模型就是那位未来的贡献者。

该模式对iOS 26+ Apple技术栈意味着什么

三点要义。

1. 设备端LLM是一项运行时特性,而非后端服务。 把它当作具有上下文窗口和设备端推理预算的系统框架来对待,而不是远程服务。架构决策是可用性、延迟、上下文窗口纪律以及结构化输出。

2. Tool协议就是接口。 没有工具,模型不过是一个与您的领域毫无连接的聊天补全端点。有了工具,模型就成了对应用数据的结构化查询层。

3. Foundation Models、App Intents和MCP之间的路由规则是”谁在运行模型”。 应用内部生成走Foundation Models。Apple Intelligence路由的能力走App Intents。外部代理能力走MCP。同一个Swift领域函数可被三种接口共同调用。

完整的Apple生态系列:面向Apple Intelligence的类型化App Intents;面向跨LLM代理的MCP服务器;两者之间的路由问题;用于锁屏状态机的Live Activities;视觉层的Liquid Glass模式;实现跨设备覆盖的多平台发布。集合中心位于Apple Ecosystem Series。如需更广泛的iOS与AI代理上下文,请参阅iOS Agent Development guide。

常见问题

iOS 26中的Foundation Models框架是什么?

Foundation Models是Apple用于访问iOS 26(以及iPadOS 26、macOS 26、visionOS 26)中符合Apple Intelligence条件的设备所搭载的设备端语言模型的框架。该框架暴露SystemLanguageModel、LanguageModelSession和Tool协议,使应用能够在无需网络访问的情况下进行类型化的设备端LLM调用。

Tool协议是如何工作的?

Tool是一个Swift类型,声明一个Arguments结构体(由@Generable和@Guide注解)、一个异步call(arguments:)方法,以及供模型决定何时调用的名称和描述。工具在构造时绑定到LanguageModelSession。当模型决定需要使用工具时,框架会解码参数、运行调用,并将类型化的输出反馈到会话中。

Foundation Models、App Intents和MCP之间有什么区别?

Foundation Models供您的应用在设备端运行LLM以进行应用内生成。App Intents供Apple Intelligence(系统代理)调用您应用的类型化能力。MCP供外部LLM宿主(Claude、ChatGPT等)通过JSON-RPC传输调用您应用的类型化工具。这三种协议的差异在于谁运行模型。同一个Swift领域函数可服务于三者。

Foundation Models可以调用MCP工具吗?

不可以。LanguageModelSession.tools仅接受符合Apple Tool协议的实现,不接受MCP工具服务器。要在两者之间架桥,您可以编写一个Foundation Models Tool,在其call方法中调用MCP客户端。Apple尚未发布内置适配器;桥接需由应用端代码自行实现。

设备端模型对生产环境而言足够好吗?

对于该框架所设计的使用场景(重新格式化、总结、对本地数据的结构化生成、轻量级工具调用)而言,是足够的。对于在长上下文上的前沿推理、规模化的多模态理解或跨文档推理而言,则不够。设备端模型是一个30亿参数的模型,上下文窗口比云端LLM更小;请挑选契合该范围的工作负载。

参考资料