Apple Foundation Models

Claude for Foundation Models 是一个 Swift 软件包，可将 Claude 作为服务器端语言模型接入 Apple 的 Foundation Models 框架。该软件包使 Claude 符合框架的 LanguageModel 协议，因此您可以使用与 Apple 设备端模型相同的 LanguageModelSession API 来驱动它：respond(to:)、流式传输、引导式生成和工具调用的工作方式完全相同。

请求直接从您的应用发送到 Claude API；Apple 不在请求路径中，也不会看到提示或响应。使用量按标准 API 定价计入您的 Anthropic 账户。您的应用自行决定何时使用 Claude、何时使用 Apple 的设备端模型：只需将所需的模型传递给每个会话即可。

要求

• iOS 27、macOS 27、visionOS 27 或 watchOS 27（均为 beta 版）：这些操作系统版本的 Foundation Models 框架支持服务器端语言模型
• Xcode 27（beta 版）
• 用于开发的 Claude 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 添加到目标的依赖项中，并与 FoundationModels 一起导入：

import FoundationModels
import ClaudeForFoundationModels

快速入门

ClaudeLanguageModel 是入口点。将其传递给 LanguageModelSession，然后像使用任何 Foundation Models 提供方一样使用该会话：

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)

初始化器还接受 baseURL（默认为 https://api.anthropic.com）、timeout 和 serverTools（参见服务器端工具）。

如需完整的可运行程序，仓库中包含 Examples/ClaudeExample，这是一个可运行的命令行目标，会将一轮对话以流式方式输出到终端，并提供 --search 标志以在该轮对话中启用服务器端网络搜索。运行它需要 macOS 27 主机。

选择模型

模型标识符是 ClaudeModel 的值。您可以使用内置常量，或者为尚未内置的 ID 显式声明能力来构造一个（参见能力）：

ClaudeLanguageModel(name: .opus4_8, auth: auth)

常量与 API 模型 ID 一一对应（.opus4_8 即 claude-opus-4-8），并携带每个模型的能力信息。新模型会作为新常量随软件包版本发布；请在 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 级别。它优先于框架的每请求推理提示，并且是请求 .xhigh 或 .max 的唯一方式，因为框架的推理级别最高只到 high。当未发送 effort 时，API 默认为 high：

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

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

何时使用 Claude 而非设备端模型

Apple 的设备端模型速度快、注重隐私且可离线工作，但其规模仅适用于轻量级任务。当您需要更大的上下文、前沿推理能力或服务器端工具（如网络搜索和代码执行）时，请升级使用 Claude。由于两者使用相同的 LanguageModelSession API，您只需更换 model: 参数即可切换。

身份验证

使用 auth: 参数设置凭据。

API 密钥（开发环境）

开发时直接传递 API 密钥：

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

代理（生产环境）

对于生产环境，请使用 .proxied 通过您自己的后端路由请求。位于 baseURL 的中继服务会在服务器端添加 Claude API 凭据，因此应用中不包含任何密钥。您提供的 headers 会随每个请求发送，以便您的代理对调用方进行授权。如果代理不需要任何标头，请传递 [:]：

ClaudeLanguageModel(
  name: .sonnet4_6,
  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:) 以增量方式返回响应。每个元素都是截至当前的响应的累积快照，而非增量差异：

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: .sonnet4_6,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

.webSearch 和 .webFetch 接受可选的 allowedDomains、blockedDomains 和 maxUses。服务器工具活动会以 ClaudeServerToolSegment 自定义片段的形式出现在对话记录中。

图像

能力包含图像输入的模型会声明框架的视觉能力。通过框架的标准会话 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 协议中没有对应表示的功能无法通过它使用，包括：

• 提示缓存控制（软件包会自动应用提示缓存；缓存 TTL 和断点位置不可配置）
• 停止序列
• 批处理
• Files API
• 令牌计数
• Beta 标头

其他资源

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