Claude for Foundation Models 是一个 Swift 包，它使 Claude 能够作为服务器端语言模型在 Apple 的 Foundation Models 框架中使用。该包使 Claude 遵循框架的 LanguageModel 协议，因此您可以使用与 Apple 设备端模型相同的 LanguageModelSession API 来驱动它：respond(to:)、“streaming”（流式传输）、引导式生成和工具调用的工作方式完全相同。

请求直接从您的应用发送到 Claude API；Apple 不在请求路径中，也看不到提示或响应。用量按标准 API 定价计入您的 Anthropic 账户，因此您的组织需要有可用的额度余额或有效的付款方式。由您的应用决定何时使用 Claude、何时使用 Apple 的设备端模型：为每个会话传入您想要的模型即可。

注意

Beta。 此包面向 OS 27 beta 版中引入的 Foundation Models 服务器端语言模型 API。在 beta 期间，API 可能会发生变化。

说明

Claude for Foundation Models 不是通用的 Messages API 客户端。它的公开接口是 Foundation Models 提供者协议遵循，以及与之相关的配置类型（ClaudeLanguageModel、ClaudeModel、AuthMode、ClaudeServerTool）。如需在其他语言中直接访问 Messages API，请参阅客户端 SDK。

要求

  • iOS 27、macOS 27、visionOS 27 或 watchOS 27（均为 beta 版）：这些操作系统版本的 Foundation Models 框架支持服务器端语言模型
  • Xcode 27（beta 版）
  • 用于开发的 Claude “API key”（API 密钥），可从 Claude Console 获取。有关生产环境选项，请参阅身份验证。

安装包

将该包添加到您的 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 提供者一样使用该会话：

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_5, auth: auth)

常量与 API 模型 ID 一一对应（.opus5 即 claude-opus-5），并携带每个模型的能力信息。新模型会在包的新版本中以新常量的形式发布；请在 Xcode 中查看 ClaudeModel 以获取当前列表，并参阅模型概览来比较模型。

能力

每个 ClaudeModel 都声明了它所接受的内容：采样参数、努力级别、自适应思考、结构化输出和图像输入。该包据此决定发送哪些请求字段，因为发送模型拒绝的字段会导致硬错误。常量携带了正确的能力信息。对于未编译内置的 ID，请声明该模型接受的内容（有意不提供任何进行猜测的简写方式）：

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

努力级别

使用 fixedEffort: 为每个请求固定 Claude 的努力级别。它优先于框架的逐请求推理提示。框架的命名推理级别最高只到 high；如果要为单个请求请求更高的努力级别，请传入一个以 Claude 努力级别命名的自定义推理级别（.custom("xhigh") 或 .custom("max")），它会直接映射。未发送努力级别时，API 使用模型的默认级别，该级别因模型而异（请参阅 Effort 级别）：

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

该级别必须是模型所接受的级别。每个 ClaudeModel 都声明了其模型接受五个级别（low、medium、high、xhigh、max）中的哪些（如果有的话）：有些模型完全不接受努力级别。

何时使用 Claude，何时使用设备端模型

Apple 的设备端模型速度快、私密且可离线使用，但其规模适合轻量级任务。当您需要更大的上下文、前沿推理能力或服务器端工具（如网页搜索和代码执行）时，请升级到 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 需要物理设备。模拟器以及没有 Secure Enclave 的硬件无法执行 App Attest。在模拟器中迭代时使用 .apiKey，在设备上运行时使用 .appAttest。

要设置 App Attest，您需要拥有 Apple Developer Team ID，并在您的组织中具有管理员、所有者或主要所有者角色。请配置您的 Xcode 项目，并在 Claude Console 中注册您的应用：

  1. 在 Xcode 中，在 Signing & Capabilities 下为您的应用目标添加 App Attest 功能。
  2. 在 Claude Console 中，前往 App integrations 页面（platform.claude.com/settings/workspaces/default/app-integrations）。每个应用集成都属于一个工作区。在侧边栏的工作区选择器中选择您需要的工作区。
  3. 点击 Create app integration，然后输入名称、您的 Apple Developer Team ID 以及一个或多个 bundle ID（最多 32 个）。
  4. 从该集成的 Overview 选项卡中复制客户端 ID（clid_...），并将其传递给您应用的 Claude 配置。

当您的应用首次在某台设备上使用 Claude 时，应用会向 Anthropic 请求一个 challenge（质询），使用 Apple 的 DCAppAttestService 对设备进行证明，然后用经过验证的证明换取一个 access token（访问令牌）。Claude for Foundation Models 包会自动运行此流程，并在令牌过期时请求新令牌；您无需编写任何证明代码。

令牌的作用范围限定于您的工作区，1 小时后过期，并且仅授权 Messages API 调用。令牌不携带任何最终用户身份：App Attest 识别的是您的应用，而不是使用它的人，因此请在您的应用中处理任何针对单个用户的逻辑。

要停止已遭入侵或已停用的应用，请撤销其集成。在 Claude Console 中，前往 App integrations 页面（platform.claude.com/settings/workspaces/default/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 请求，以 Authorization: Bearer <key> 的形式附加您的 API 密钥，然后将其转发到 https://api.anthropic.com。

API 密钥（开发环境）

开发期间直接传递 API 密钥：

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

警告

打包到应用中的密钥可以从发布的二进制文件中提取出来，任何提取到它的人都可以发起计入您账户的请求。.apiKey 仅用于开发，发布前请切换到 App Attest 或代理。

流式传输

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 自定义片段的形式出现在对话记录中。

注意

serverTools 配置在 ClaudeLanguageModel 上而不是 LanguageModelSession 上，因为会话类型属于 Apple。若要为每个对话使用不同的服务器工具集，请构造多个 ClaudeLanguageModel 实例。

图像

能力中包含图像输入的模型会声明框架的视觉能力。通过框架的标准会话 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
  • 令牌计数
  • Beta 请求头

其他资源

参考资料 涵盖内容
Apple Foundation Models 文档 LanguageModelSession、@Generable、Transcript、Tool 以及框架的其余接口
GitHub 上的 ClaudeForFoundationModels 源代码、可运行示例和问题跟踪器
Claude API 参考 底层 Messages API

该包采用 Apache 2.0 许可证。欢迎通过 GitHub issues 提交错误报告。beta 期间不接受外部拉取请求。

可用性

Apple Foundation Models在所有模型上处于 beta 阶段。

API 支持

Messages API

  • 可用性：可用
状态 云平台
Beta Claude API