Claude 上车苹果生态

大家好，我是 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 框架

写 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，让每次请求都用固定的推理强度：

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

本地模型上下文有限

复杂推理

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 应用，这个包值得现在就开始关注