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 的裝置端模型：將您想要的模型傳入各個 session 即可。

需求

• iOS 27、macOS 27、visionOS 27 或 watchOS 27（皆為 beta 版）：這些是 Foundation Models 框架支援伺服器端語言模型的作業系統版本
• Xcode 27（beta 版）
• 開發時需要一組來自 Claude Console 的 Claude「API key」（API 金鑰）。正式環境的選項請參閱驗證。

安裝套件

將套件加入您的 Package.swift：

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

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

接著將 ClaudeForFoundationModels 加入您 target 的相依項目，並與 FoundationModels 一同匯入：

import FoundationModels
import ClaudeForFoundationModels

快速開始

ClaudeLanguageModel 是進入點。將它傳入 LanguageModelSession，然後像使用任何 Foundation Models 提供者一樣使用該 session：

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，這是一個可執行的命令列 target，會將一輪對話以串流方式輸出至終端機，並提供 --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 的裝置端模型快速、私密且可離線使用，但其規模是為輕量任務設計的。當您需要更大的「context window」（上下文視窗）、前沿推理能力，或網頁搜尋與程式碼執行等伺服器端工具時，請升級使用 Claude。由於兩者使用相同的 LanguageModelSession API，您只需替換 model: 引數即可切換。

驗證

使用 auth: 參數設定憑證。使用 .appAttest 可在沒有後端的情況下發布，使用 .proxied 可將請求經由您自己的後端轉送，或使用 .apiKey 在開發期間快速迭代。

App Attest

您應用程式的每個安裝實例都會使用 Apple 的 App Attest 服務，來證明它是您所註冊之應用程式的正版、未經修改的建置版本。接著，Anthropic 會向該裝置核發一個短效期的「access token」（存取權杖），並將使用量計費至您的工作區。應用程式中不會內含任何 API 金鑰，您也無需自行營運任何代理伺服器。

App Attest 驗證僅在您的應用程式直接呼叫 Claude API 時可用。透過 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 則無法使用此功能。

若要在不執行後端的情況下發布，請使用 .appAttest：

ClaudeLanguageModel(
  name: .sonnet5,
  auth: .appAttest(clientID: "clid_...")
)

若要設定 App Attest，您需要您的 Apple Developer Team ID，以及在您組織中的管理員、擁有者或主要擁有者角色。請設定您的 Xcode 專案，並在 Claude Console 中註冊您的應用程式：

1. 在 Xcode 中，於 Signing & Capabilities 下為您的應用程式目標新增 App Attest 功能。
2. 在 Claude Console 中您工作區的設定裡，開啟 App integrations。
3. 點擊 Create app integration，並輸入名稱、您的 Apple Developer Team ID，以及一個或多個 bundle ID（最多 32 個）。
4. 從該整合的 Overview 分頁複製 client ID（clid_...），並將其傳入您應用程式的 Claude 設定中。

您的應用程式首次在某部裝置上使用 Claude 時，應用程式會向 Anthropic 請求一個 challenge（挑戰值），使用 Apple 的 DCAppAttestService 對裝置進行證明，然後以經過驗證的證明交換一個 access token（存取權杖）。Claude for Foundation Models 套件會自動執行此流程，並在權杖過期時請求新的權杖；您無需撰寫任何證明相關的程式碼。

權杖的範圍限定於您的工作區，一小時後過期，且僅授權 Messages API 呼叫。它們不帶有任何終端使用者身分：App Attest 識別的是您的應用程式，而非使用它的人，因此請在您的應用程式中處理任何與個別使用者相關的邏輯。

若要停止已遭入侵或已淘汰的應用程式，請撤銷其整合：在 Claude Console 中您工作區的設定裡，開啟 App integrations，選取該整合，然後點擊 Revoke，再進行確認。撤銷整合會撤銷其尚未失效的權杖，且其已註冊的裝置將無法再請求新的權杖。撤銷是永久性的，因此若要恢復存取權限，請建立新的應用程式整合。

代理伺服器（正式環境）

在正式環境中，請使用 .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。

API 金鑰（開發用）

開發期間可直接傳入 API 金鑰：

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

串流

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

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 中。

圖像

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

錯誤處理

套件會在有對應項目時，將 Claude API 錯誤對應至 Apple 的 LanguageModelError 案例：上下文視窗溢位會呈現為 .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
• Token 計數
• Beta 標頭

其他資源

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