Apple Foundation Models

Claude for Foundation Models 是一個 Swift 套件，讓 Claude 可以作為伺服器端語言模型在 Apple 的 Foundation Models 框架中使用。此套件讓 Claude 符合該框架的 LanguageModel 協定，因此您可以使用與 Apple 裝置端模型相同的 LanguageModelSession API 來驅動它：respond(to:)、串流（streaming）、引導式生成和工具呼叫的運作方式完全相同。

請求會直接從您的應用程式傳送到 Claude API；Apple 不在請求路徑中，也不會看到提示或回應。使用量會以標準 API 定價計費到您的 Anthropic 帳戶。您的應用程式決定何時使用 Claude、何時使用 Apple 的裝置端模型：只需將您想要的模型傳遞給每個工作階段即可。



需求

• iOS 27、macOS 27、visionOS 27 或 watchOS 27（皆為 beta 版）：這些 OS 版本的 Foundation Models 框架支援伺服器端語言模型
• Xcode 27（beta 版）
• 從 Claude Console 取得的 Claude API 金鑰（API key），供開發使用。生產環境選項請參閱驗證。



安裝套件

將套件加入您的 Package.swift：

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

或在 Xcode 中：File > Add Package Dependencies… 並輸入儲存庫 URL。

然後將 ClaudeForFoundationModels 加入您目標的相依項目，並與 FoundationModels 一起匯入：

import FoundationModels
import ClaudeForFoundationModels



快速開始

ClaudeLanguageModel 是進入點。將它傳遞給 LanguageModelSession，然後像使用任何 Foundation Models 提供者一樣使用該工作階段：

import FoundationModels
import ClaudeForFoundationModels

let model = ClaudeLanguageModel(
  name: .sonnet5,
  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)

初始化器也接受 baseURL（預設為 https://api.anthropic.com）、timeout 和 serverTools（請參閱伺服器端工具）。

如需完整可運作的程式，儲存庫包含 Examples/ClaudeExample，這是一個可執行的命令列目標，會將一輪對話串流到終端機，並提供 --search 旗標以為該輪對話啟用伺服器端網路搜尋。執行它需要 macOS 27 主機。



選擇模型

模型識別碼是 ClaudeModel 的值。使用編譯內建的常數，或為尚未編譯內建的 ID 建構一個具有明確能力的模型（請參閱能力）：

ClaudeLanguageModel(name: .opus5, auth: auth)

常數對應 API 模型 ID（.opus5 即 claude-opus-5），並帶有每個模型的能力。新模型會在套件發布時以新常數的形式提供；請在 Xcode 中查看 ClaudeModel 以取得目前的清單，並參閱模型總覽來比較模型。



能力

每個 ClaudeModel 都宣告它接受的內容：取樣參數、effort 等級、自適應思考、結構化輸出和圖片輸入。套件使用這些資訊來決定要傳送哪些請求欄位，因為傳送模型拒絕的欄位會是硬性錯誤。常數帶有正確的能力。對於未編譯內建的 ID，請宣告該模型接受的內容（刻意不提供會猜測的簡寫方式）：

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



Effort

使用 fixedEffort: 為每個請求固定 Claude 的 effort 等級。它的優先順序高於框架的每次請求推理提示。框架的具名推理等級最高只到 high；若要改為針對單一請求要求更高的 effort，請傳遞一個指定 Claude effort 的自訂推理等級（.custom("xhigh") 或 .custom("max")），它會直接對應。當未傳送 effort 時，API 預設為 high：

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

該等級必須是模型接受的等級。每個 ClaudeModel 都宣告其模型接受五個等級（low、medium、high、xhigh、max）中的哪些（如果有的話）：有些模型完全不接受 effort。



何時使用 Claude 而非裝置端模型

Apple 的裝置端模型快速、私密且可離線使用，但其規模適合輕量級任務。當您需要更大的上下文、前沿推理能力，或網路搜尋和程式碼執行等伺服器端工具時，請升級到 Claude。由於兩者使用相同的 LanguageModelSession API，您只需替換 model: 引數即可切換。



驗證

使用 auth: 參數設定憑證。



API 金鑰（開發）

開發時直接傳遞 API 金鑰：

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



代理伺服器（生產環境）

在生產環境中，使用 .proxied 將請求路由到您自己的後端。位於 baseURL 的中繼伺服器會在伺服器端加入 Claude API 憑證，因此應用程式不會附帶金鑰。您提供的 headers 會隨每個請求傳送，讓您的代理伺服器可以授權呼叫者。如果不需要任何標頭，請傳遞 [:]：

ClaudeLanguageModel(
  name: .sonnet5,
  auth: .proxied(headers: ["X-App-Token": "..."]),
  baseURL: URL(string: "https://api.yourapp.com/claude")!
)

您的代理伺服器會收到標準的 Messages API 請求，附加 x-api-key 標頭，然後轉發到 https://api.anthropic.com。



串流

streamResponse(to:) 會以增量方式回傳回應。每個元素都是到目前為止回應的累積快照，而非差異（delta）：

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



結構化輸出

使用 @Generable 標註型別，並以 generating: 請求它。模型會透過結構化輸出回傳該型別的值：

@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)

結構化輸出需要能力包含此功能的模型（所有編譯內建的常數都包含）。如果所選模型不支援，套件會拋出 LanguageModelError.unsupportedGenerationGuide，而不是默默降級。



工具使用



用戶端工具

框架的 tools: 陣列可以原封不動地使用。讓您的型別符合 Tool，將它們傳遞給 LanguageModelSession，當 Claude 呼叫它們時，框架會在裝置上調用它們。請參閱使用 Claude 進行工具使用。

let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()])



伺服器端工具

伺服器工具（網路搜尋、網頁擷取和程式碼執行）在 Anthropic 的基礎設施上於單次往返內執行，框架不需要在裝置上調用任何東西。使用 serverTools: 為每個模型設定它們：

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

.webSearch 和 .webFetch 接受選用的 allowedDomains、blockedDomains 和 maxUses。伺服器工具活動會以 ClaudeServerToolSegment 自訂區段的形式出現在文字記錄（transcript）中。



圖片

能力包含圖片輸入的模型會宣告框架的視覺能力。透過框架的標準工作階段 API 傳遞圖片內容；套件會將其轉換為 Claude API 的圖片格式。圖片需求請參閱視覺。



錯誤處理

套件會將 Claude API 錯誤對應到合適的 Apple LanguageModelError 案例：上下文視窗（context window）溢位會顯示為 .contextSizeExceeded，HTTP 429 為 .rateLimited，超過設定逾時的請求為 .timeout。沒有框架對應項的提供者錯誤會顯示為 ClaudeError。使用模式比對來驅動產品流程：

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // 提示輸入 API 金鑰。
} catch let error as LanguageModelError {
  // 框架層級的錯誤（速率限制、防護機制、上下文長度、解碼）。
} catch {
  // 傳輸錯誤。
}

一個常見的模式是捕捉 .rateLimited，然後在該輪對話改用 SystemLanguageModel、將請求排入佇列，或顯示重試選項。



功能支援

套件提供 Foundation Models 提供者協定能夠表達的 Messages API 能力。在 Apple 協定中沒有對應表示的功能無法透過它使用，包括：

• 提示快取（prompt caching）控制（套件會自動套用提示快取；快取 TTL 和中斷點位置無法設定）
• 停止序列
• 批次處理
• Files API
• 權杖計數
• Beta 標頭



其他資源

此套件以 Apache 2.0 授權。歡迎透過 GitHub issues 回報錯誤。在 beta 期間不接受外部 pull request。