大家好，我是 Ai 學習的老章

WWDC26 剛結束，Anthropic 就放了個大招——Claude 正式接入 Apple Foundation Models 框架，iOS/macOS 開發者現在可以用同一套 API無縫切換設備端模型和 Claude 云端大腦了

以前你想在 App 里接 Claude，得自己封裝 HTTP 請求、處理流式響應、搞 JSON 解析，一堆臟活累活

現在 Anthropic 出了一個 Swift 包ClaudeForFoundationModels，直接讓 Claude 符合 Apple 的LanguageModel協議，用LanguageModelSession就能調用，跟調用本地模型一模一樣

這波操作，屬于是 Claude 主動上車蘋果生態

這個包是什么

ClaudeForFoundationModels是 Anthropic 官方出品的 Swift Package，核心作用就一個：讓 Claude 成為 Apple Foundation Models 框架里的一個"服務端語言模型提供者"

Apple Foundation Models 框架

寫 SwiftUI 應用時，原來怎么調 Apple 自帶的設備端模型，現在就怎么調 Claude。API 完全一致，開發者心智負擔為零

幾個關鍵事實：

• 請求直接從你的 App 發到 Claude API，Apple 不在請求鏈路上，不會看到你的 prompt 和響應

• 按 Anthropic 標準 API 計費，走的是你自己的 Anthropic 賬戶

• 你的 App 可以靈活決定什么時候用本地模型（快速、隱私、離線），什么時候升級到 Claude（大上下文、強推理、服務端工具）

• iOS 27 / macOS 27 / visionOS 27 / watchOS 27（全部 Beta 階段）

• Xcode 27 Beta

• Anthropic API Key（開發用）

注意，這些系統版本目前都在 Beta，正式版預計今年秋天隨新系統一起推出

安裝

兩種方式，都很簡單

方式一：Package.swift

dependencies: [
  .package(url: "https://github . com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0")
]

方式二：Xcode 圖形界面

File → Add Package Dependencies → 輸入倉庫 URL 搜索添加就行

然后在代碼里 import 兩個模塊：

import FoundationModels
import ClaudeForFoundationModels

來看最簡單的用法，5 行代碼搞定一次 Claude 調用：

import FoundationModels
import ClaudeForFoundationModels

 let model = ClaudeLanguageModel(
  name: .sonnet4_6,
  auth: .apiKey(ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"] ?? "")
)

 let session = LanguageModelSession(model: model)
let response = try await session.respond(to: "Plan a 4-day trip to Buenos Aires.")
print(response.content)

看到沒？LanguageModelSession是 Apple 框架的原生類型，你傳入ClaudeLanguageModel就用 Claude，傳入SystemLanguageModel就用本地模型。一行代碼切換，架構層面零改動

這個設計太優雅了，比自己封裝 URLSession 調 Messages API 不知道高到哪里去

模型選擇

通過ClaudeModel枚舉值來指定模型：

ClaudeLanguageModel(name: .opus4_8, auth: auth)   // Opus 4.8
ClaudeLanguageModel(name: .sonnet4_6, auth: auth)  // Sonnet 4.6

枚舉常量直接映射 API model ID，比如.opus4_8對應claude-opus-4-8。新模型會隨包更新加入

如果你想試驗還沒正式編譯進去的新模型，也能手動聲明能力：

let model = ClaudeModel(
  id: "claude-experimental-x",
  capabilities: .init(effortLevels: [.low, .high], structuredOutput: true)
)
ClaudeLanguageModel(name: model, auth: auth)

這是個很實用的功能——你可以釘死一個 effort level，讓每次請求都用固定的推理強度：

ClaudeLanguageModel(name: .opus4_8, auth: auth, fixedEffort: .xhigh)

五檔可選：low、medium、high、xhigh、max

Apple 框架自帶的 reasoning level 會自動映射：.light→ low，.moderate→ medium，.deep→ high。但如果你想上xhigh或max，就得用fixedEffort顯式指定，因為框架的級別最高只到 high

什么時候用 Claude，什么時候用本地模型

這其實是這個包最核心的設計哲學：

下面這張架構圖可以幫助理解整體設計思路：

Claude for Foundation Models 架構示意

場景

原因

快速響應、隱私敏感

本地模型

零延遲、數據不出設備

大上下文窗口

Claude

本地模型上下文有限

復雜推理

Claude

前沿推理能力

需要聯網搜索

Claude

服務端工具支持

離線場景

本地模型

無需網絡

因為兩者共享同一套LanguageModelSessionAPI，切換只需要換model:參數，甚至可以做運行時動態降級——Claude 限流了就自動回退到本地模型

認證方式

開發階段：直接用 API Key

ClaudeLanguageModel(name: .sonnet4_6, auth: .apiKey("YOUR_API_KEY"))

?? 注意：打包到 App 里的 Key 可以被人從二進制文件里提取出來，千萬別在正式發布的 App 里這么干

生產環境：走自建代理

ClaudeLanguageModel(
  name: .sonnet4_6,
  auth: .proxied(headers: ["X-App-Token": "..."]),
  baseURL: URL(string: "")!
)

你的后端代理接收標準 Messages API 請求，加上x-api-key頭后轉發給 Anthropic。這樣 App 端不存任何密鑰

Anthropic 還提到未來會推出一種不需要自建后端的生產模式，基于 App Attest 認證，計費走你的 Anthropic workspace。但目前還沒上線

流式響應

let stream = session.streamResponse(to: "Summarize today's top science stories.")
for try await partial in stream {
  print(partial.content)
}

注意這里每個partial是累積快照，不是增量 delta。這跟一些其他 SDK 的設計不同，用的時候注意

結構化輸出

這個功能我特別喜歡。用@Generable宏標注一個 struct，Claude 就會按照類型約束返回結構化數據：

@Generable
struct Trip {
  @Guide(description: "Destination city") var destination: String
  @Guide(description: "Length in days") var days: Int
}


 let response = try await session.respond(to: "Plan a trip to Tokyo.", generating: Trip.self)
print(response.content.destination)  // "Tokyo"

Swift 原生類型安全 + AI 結構化輸出，強類型 all the way。再也不用手動解 JSON 了

服務端工具

Claude 的服務端工具（Web Search、Web Fetch、Code Execution）可以直接配置，在一次 API 往返中在 Anthropic 的基礎設施上運行：

let model = ClaudeLanguageModel(
  name: .sonnet4_6,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

.webSearch和.webFetch還支持域名過濾（allowedDomains / blockedDomains）和調用次數限制

這些工具和 Apple 框架的tools:數組是分開的——tools:放的是客戶端工具（在設備上執行），serverTools:放的是服務端工具（在 Anthropic 服務器上執行）

錯誤處理

do {
let response = try await session.respond(to: prompt)
print(response.content)
} catchClaudeError.missingCredential {
// 提示用戶輸入 API Key
} catchlet error asLanguageModelError {
// 框架級錯誤：限流、上下文超長、內容審核等
} catch {
// 網絡/傳輸錯誤
}

Claude API 的錯誤會映射到 Apple 的LanguageModelError：上下文超長 →.contextSizeExceeded，429 限流 →.rateLimited，超時 →.timeout

一個常見模式：捕獲.rateLimited后自動回退到本地模型，或者排隊重試

當前限制

這個包目前不支持的東西：

• Prompt caching 控制（包會自動啟用緩存，但你無法控制 TTL 和斷點）

• Stop sequences

• 批量處理（Batch API）

• Files API

• Token counting

• Beta headers

本質上它只暴露了 Apple Foundation Models 協議能表達的那部分能力，超出協議邊界的特性暫時用不了

總結

ClaudeForFoundationModels是一個設計極其克制但恰到好處的 SDK。它沒有試圖做一個全功能的 Anthropic API 客戶端，而是精準地完成了一件事：讓 Claude 成為 Apple Foundation Models 框架里的一員

對于 iOS/macOS 開發者來說，這意味著：

• 零學習成本接入 Claude（用的是你已經會的 LanguageModelSession API）

• 架構層面可以靈活混用本地模型和 Claude

• 強類型、Swift 原生、async/await 全套

• 生產就緒的認證方案

目前還是 Beta 階段（畢竟 OS 27 都還沒正式發布），但整體 API 設計已經相當成熟。如果你在做 Apple 平臺的 AI 應用，這個包值得現在就開始關注