Foundation Models 裝置端LLM：Tool 協定

Apple 在 WWDC 2025 發表的裝置端LLM契約引出一個立即的路由問題：何時該選擇 LanguageModelSession、何時該選 AppIntent、何時該用 MCP、又何時三者皆非。

iOS 26 在每部支援 Apple Intelligence 的裝置上配置了 30 億參數的語言模型。¹ Apple 將此框架命名為 Foundation Models。框架是本機運作的。推論已針對 Apple silicon 進行最佳化並在裝置上執行；網路不在呼叫路徑中。模型存放於 SystemLanguageModel.default，您的應用程式取得 LanguageModelSession,而讓該 session 執行實用工作的型別化介面便是 Tool 協定。

Tool 協定是應用程式開發者最關注的部分。少了它,裝置端LLM就只是一個與您應用程式資料、使用者資料以及系統其他部分毫無連結的聊天完成端點。有了它,模型便能呼叫具型別的 Swift 函式、取回具型別的結果,並在下一輪推理中對答案進行思考。具備工具增強的裝置端生成才是此框架真正的能力。聊天介面只是示範。

TL;DR

• Foundation Models 為每部符合 Apple Intelligence 條件的裝置在 SystemLanguageModel.default 提供 30 億參數的LLM。模型是本機的;推論針對 Apple silicon 最佳化並在裝置上執行;網路不在呼叫路徑中。
• Tool 協定是模型與您應用程式之間的契約。工具會宣告具型別的 Arguments、回傳具型別的 Output,並在建構時繫結至某個 LanguageModelSession。
• Generable 與 Guide 註解讓模型直接產生具型別的 Swift 值,而非僅是字串。解碼器是框架的一部分,而非您的程式碼。
• Foundation Models、App Intents 與 MCP 之間的路由規則在於由誰執行模型、在何處執行。Foundation Models = 您的應用程式在裝置端執行模型。App Intents = Apple Intelligence 在裝置端執行模型並路由至您的應用程式。MCP = 由外部主機在其選擇的位置執行模型,並透過工具伺服器接入您的應用程式。

框架實際提供的內容

三項基本元素構成此框架:模型、session 與工具。²

SystemLanguageModel。 對裝置端基礎模型的參考。預設實例繫結至使用者的裝置,在符合 Apple Intelligence 條件的硬體上可用,並提供應用程式於執行時讀取的能力檢查,以判定模型是否可用。框架支援透過 SystemLanguageModel(useCase:guardrails:)、自訂介面卡與 GenerationOptions 進行設定,但您並不能像對 OpenAI 或 Anthropic 那樣自由挑選任意的雲端模型 ID;Apple 會隨每次 OS 發行版本提供並更新裝置端模型,框架交給您的就是當前已安裝的版本。

LanguageModelSession。 一個有狀態的物件,跨呼叫保留對話狀態。Session 在建構時接收系統提示、隨時間累積使用者/助理輪次,並暴露用於生成回應的 async 方法。Session 建立成本低且可拋棄;您應為每個任務建立一個 session,而非整個應用程式共用一個。冥想計時器為「總結我過去 7 天的練習」建立一個 session;食譜應用程式則為「將此食譜改為兩人份而非四人份」建立另一個不同的 session。

Tool(協定)。 一個 Swift 協定,宣告 name、description、Arguments 型別、Output 型別,以及 async call(arguments:) 函式。工具於建構時繫結至 session(LanguageModelSession(tools: [...], instructions: ...))。當模型判定需要工具時,會發出結構化呼叫;框架解碼引數、執行工具、編碼結果,並回饋給 session 用於下一輪。模型看不到 Swift;由框架負責封送處理。

該協定的完整需求:name: String、description: String、一個符合 ConvertibleFromGeneratedContent 的關聯 Arguments 型別、一個符合 PromptRepresentable 的關聯 Output 型別,以及一個 async call(arguments:) 方法。在 Arguments 結構上使用 @Generable 巨集會免費產生 ConvertibleFromGeneratedContent 的符合性;對於 Output,String 與 GeneratedContent 已自動符合。Apple 文件中的範例會回傳 String 或 [String]。

簡化後的 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 -> String {
        let entries = try store.entries(
            from: ISO8601DateFormatter().date(from: arguments.startDate) ?? .now,
            to: ISO8601DateFormatter().date(from: arguments.endDate) ?? .now
        )
        let totalMl = entries.reduce(0) { $0 + $1.amountMl }
        return "Found \(entries.count) entries totalling \(totalMl)ml."
    }
}

模型看到的是工具描述和產生模式的引數樣貌。Swift 程式碼看到的是具型別的輸入與具型別的輸出。解碼/編碼邊界由 Apple 負責。工具輸出可以是 String 或 GeneratedContent 物件;上方範例回傳 String,因為消費者是模型下一輪的推理。

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
)

該呼叫回傳 Response<PracticeSummary>,其 content 是具型別的 PracticeSummary。您的程式碼裡沒有 JSON 解析、沒有對「headline:」做字串比對、沒有當模型回傳格式錯誤物件時的退路處理。框架透過約束取樣讓模型逐 token 的輸出在結構上對齊 schema,因此結構性無效的輸出不會跨過此邊界。上方 session 不接收任何工具,因為具型別輸出與工具呼叫是彼此獨立的能力;一個 session 可以單用 @Generable 來決定回應形狀、單用工具進行接地、兩者並用,或皆不用。

Swift 具型別介面正是該框架與雲端LLM SDK 的差異所在。雲端 SDK(OpenAI Structured Outputs、Anthropic tool use 等)同樣支援約束取樣,但開發者收到的具型別值是一個依據 schema 驗證過的 JSON 物件,然後再以另一個步驟解碼成 Codable 的 Swift 型別。Foundation Models 將這些步驟合併:@Generable 巨集與框架的解碼器將具型別的 Swift 值作為直接回傳值產出,而每個欄位上的 @Guide 註解則把意圖帶入生成約束。輸出之所以具型別,是因為生成過程是針對 Swift schema 進行型別約束,而不是針對開發者在 Swift 中重建的 JSON 規格。

@Guide 註解是讓您不必把意圖寫進提示中、便能向模型傳達各欄位意圖的方式。產生的描述會成為生成約束的一部分。欄位層級的 guide 讓提示保持簡潔,並讓 schema 緊貼資料。

路由問題的三種樣貌

Apple 現在提供應用程式三種協定介面,可將自身領域暴露給語言模型。它們會路由至不同的執行者。

Foundation Models(LanguageModelSession)。 您的應用程式載入裝置端模型並執行推論。session 可呼叫的工具,正是您應用程式自身程式碼定義的工具。模型永遠不離開裝置。使用者並非透過 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 分鐘的 session」能力則使用 App Intents,讓 Siri 能呼叫它。同一應用程式中「給我看最近的冥想紀錄」這項由 Claude Code session 使用的能力則使用 MCP。三個不同執行者、三組不同義務,底層共享同一個領域層。

推論預算:框架對您的要求

在裝置端執行LLM並非免費。Apple silicon 處理推論,但模型仍受限於上下文視窗、token 預算,以及隨裝置而異的實際延遲。三項約束會形塑您運用此框架的設計方式:⁶

可用性因裝置而異。 並非每部 iOS 26 裝置都支援 Apple Intelligence。較舊的 iPhone、受限裝置,以及使用者已停用 Apple Intelligence 的裝置,SystemLanguageModel.default.availability 會回傳「不可用」狀態。未檢查可用性即呼叫 LanguageModelSession 的程式碼會在執行時拋出生成錯誤;正確做法是事先依可用性狀態分支 UI,並在不可用時提供無LLM的替代路徑。把模型視為功能旗標,而非保證。

延遲不可忽視。 在我們對 Return 的測試中,iPhone 16 Pro 硬體的首 token 延遲足以應付應用內互動;較長的生成與工具呼叫鏈則並非即時。雲端LLM串流適用的 UI 模式在這裡同樣適用;不要阻塞主執行緒、要呈現漸進式輸出、並為使用者在生成中途離開的情況做設計。

上下文視窗比雲端更小。 裝置端模型的上下文視窗比 GPT-4 等級的雲端模型更小。長文件需要摘要或分塊;長對話歷史需要修剪;傳回大型結構化負載的工具輸出應只回傳一個參考(ID 或 key)讓下一輪在需要時重新擷取,而不要把整個負載內嵌傳回。

整套約束類似於針對低階邊緣執行環境設計,而非前沿雲端模型。框架的便利性讓開發過程更愉快;但底層物理限制並未改變。

何時應選擇 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 session 接入您應用程式領域屬於 MCP 的範疇。應用程式不執行LLM;由主機執行;模型存在於主機放置之處。Foundation Models 無法服務外部代理。

對大型文件的繁重推理。 裝置端模型很小。200 頁的合約、長段程式碼上下文,或對眾多照片進行多影像推理,都應交給雲端推論(您自己的或廠商的),讓上下文視窗與參數量符合工作負載。超出框架包覆範圍的任務會產生具體錯誤:超出上下文視窗、違反防護欄、不支援的語系。請刻意把這些錯誤呈現出來,而不要設計依賴模型處理超出包覆範圍工作的流程。

跨裝置與跨使用者的工作流。 裝置端模型只能取得應用程式傳入 session 的內容。跨裝置同步(從 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 領域函式可被三個介面共同呼叫。

三篇姊妹文進一步深入 Foundation Models 框架:Foundation Models use cases 探討工作負載適配的決策、custom adapters 說明如何以應用程式資料微調裝置端模型,而 the agentic workflow 則處理應用內與工具化LLM的職責切分。

完整的 Apple Ecosystem 系列:為 Apple Intelligence 而設的具型別 App Intents;為跨LLM代理而設的 MCP 伺服器;兩者之間的 routing question;用於 Lock Screen 狀態機的 Live Activities;視覺層的 Liquid Glass patterns;多平台出貨範圍可達跨裝置觸及的 multi-platform shipping。專欄總覽位於 Apple Ecosystem Series。如需更廣泛的 iOS 結合 AI 代理脈絡,請參閱 iOS Agent Development guide。

FAQ

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 註解)、async call(arguments:) 方法,以及供模型決定何時呼叫的 name 與 description。工具於建構時繫結至 LanguageModelSession。當模型判定需要工具時,框架會解碼引數、執行呼叫,並把具型別的輸出回饋給 session。

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更小;請挑選符合此包覆範圍的工作負載。

參考資料