Claude for Apple Foundation Models Integration Guide

Unified LLM Integration for Apple Platforms

Anthropic 推出了 ClaudeForFoundationModels Swift package，將 Claude 作為伺服器端語言模型整合進 Apple 的 Foundation Models 框架中。此整合讓開發者可以使用相同的 LanguageModelSession API，同時調用 Apple 的裝置端模型與 Claude 的前沿模型，從而根據任務的複雜度在本地與雲端 AI 之間進行無縫切換。

Core Architecture and Data Privacy

透過 ClaudeForFoundationModels package 進行的請求會直接從應用程式傳送到 Claude API。Apple 並不在請求路徑中，這意味著 Apple 無法看到提示詞（prompts）或回應內容。計費將直接透過開發者的 Anthropic 帳戶，按標準 API 定價進行處理。

Technical Requirements

若要使用此整合功能，開發者必須使用以下軟體的 beta 版本：

  • OS Versions: iOS 27, macOS 27, visionOS 27, 或 watchOS 27（皆為 beta 版）。
  • IDE: Xcode 27 (beta)。
  • Authentication: 從 Claude Console 取得一個 Claude API key 用於開發。

Implementation Details

Model Selection and Capabilities

開發者使用 ClaudeLanguageModel 作作為進入點。模型識別碼透過 ClaudeModel enum 管理，其中包含與 API 模型 ID 對應的常數（例如，.opus4_8 對應 claude-opus-4-8）。

由於傳送一個模型不支援的欄位會導致硬錯誤（hard error），因此該 package 使用能力系統（capabilities system）來決定要傳送哪些請求欄位。對於尚未編譯進 package 的模型，開發者可以手動宣告能力，包括採樣參數（sampling parameters）、努力程度（effort levels）以及結構化輸出（structured output）支援。

Effort Levels and Reasoning

該 package 允許使用 fixedEffort: 參數來固定 Claude 的努力程度（low, medium, high, xhigh, max）。此設定會優先於框架的每請求推理提示（reasoning hints）。值得注意的是，.xhigh 與 .max 僅能透過此參數取得，因為標準 Apple 框架的推理層級僅到 high 為止。

Structured Output and Streaming

  • Structured Output: 透過使用 @Generable 標註一個類型，開發者可以使用 generating: 參數來請求特定的資料類型。若模型不支援結構化輸出，package 會拋出 LanguageModelError.unsupportedGenerationGuide。
  • Streaming: streamResponse(to:) 方法提供增量回應。每個回傳的元素都是回應內容的累積快照（cumulative snapshot），而非增量（delta）。

Tool Use and Vision

Client-Side vs. Server-Side Tools

此整合支援兩種不同的工具執行方式：

  1. Client-Side Tools: 這些工具使用標準的 Apple 框架 tools: 陣列。框架會在 Claude 要求時，於裝置端執行這些工具。
  2. Server-Side Tools: 這些工具在 Anthropic 的基礎設施上執行（例如：web search, web fetch, 以及 code execution），並透過 ClaudeLanguageModel 進行配置。這些工具會在單次往返（round trip）內完成，不需要裝置端執行。

Vision Capabilities

對於支援影像輸入的模型，package 會自動將透過標準 session API 傳遞的影像內容轉換為 Claude API 所要求的格式。

Production Deployment and Security

Authentication Strategies

Anthropic 提供兩種身份驗證模式，以防止 API key 洩露：

  • Development: .apiKey 允許直接傳遞 key，但這對於發布二進位檔（binaries）並不安全，因為 key 可能會被提取。
  • Production: .proxied 會將請求路由至開發者自己的後端。代理伺服器會在伺服器端加入 x-api-key 標頭，並將請求轉發給 Anthropic，確保應用程式發布時不包含任何敏感憑證。

Error Handling

Claude API 的錯誤會映射到 Apple 的 LanguageModelError 案例，以維持一致性。例如，HTTP 429 錯誤會映射到 .rateLimited，而 context-window 溢出則映射到 .contextSizeExceeded。這讓開發者可以實作 fallback 邏輯，例如當雲端模型因速率限制而被限制時，切換至 SystemLanguageModel（裝置端模型）。

Community Perspectives and Analysis

Hacker News 上的產業觀察家與開發者討論了此發布的幾項戰略意義：

  • Abstraction as Strategy: 有人建議，透過提供統一的 API，Apple 正在將 LLM 商品化，並鼓勵開發者針對抽象層進行開發。這使得開發者在 Apple 自己的模型變得更強大時，能更容易地切換到 Apple 模型，進而可能降低開發者成本並提升使用者體驗（UX）。
  • UX Concerns: 關於 API key 管理的摩擦力有相當大的討論。批評者認為要求使用者提供自己的 key，是一種糟糕的使用者體驗，而依賴開發者代理伺服器可能會引入關於代理層級資料可見性的隱私問題。
  • UX and Control: 有些開發者對模型名稱被硬編碼為 enum 而非使用基於字串的探索方式感到驚訝，因為後者可以讓模型在不需要 App Store 更新的情況下進行更新。

"Apple, despite not really leading in AI themselves, are right on the hot path of where developers are going to yolo slop into the ecosystem. Make a tonne of sense to define a nice clean API that places like Anthropic can build on top of and expose to developers."

Feature Limitations

由於缺乏在 Apple 協議中的表示，某些 Messages API 的功能目前無法使用，包括：

  • Prompt caching controls (雖然 caching 是自動套用的)。
  • Stop sequences.
  • Batch processing.
  • The Files API.
  • Token counting.

Sources