大家好，我是 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 框架
打开网易新闻 查看精彩图片
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：精细控制推理深度

这是个很实用的功能——你可以钉死一个 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 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 应用，这个包值得现在就开始关注