Apple Foundation Models 框架入门：Swift 原生 AI 开发实战指南

本文基于 Tanaschita 的 Foundation Models 入门文章 及相关 WWDC26 官方资料整理编写。

目录

1. 什么是 Foundation Models 框架
2. 快速上手：第一次调用
3. 结构化输出：告别 JSON 解析
4. 模型运行的三个层级
5. 多模态输入：图像 + 文本
6. 第三方模型接入
7. Dynamic Profiles 与多智能体工作流
8. 与 Core AI 框架的关系
9. 最佳实践与踩坑指南
10. 个人见解与总结
11. 参考资料

什么是 Foundation Models 框架

Foundation Models 是 Apple 在 WWDC 2025 首次引入、WWDC 2026 大幅增强的一套原生 Swift API，它让开发者可以直接在 App 中访问大型语言模型。这些模型与驱动 Apple Intelligence（苹果智能）的底层模型是同一套。

简单来说：以前你要在 iOS App 里接入 AI 能力，需要注册 OpenAI / Claude 账号、管理 API Key、按 token 付费、把所有用户请求发到云端。现在 Apple 把这个能力内置到了系统里——一个 API、设备端运行、隐私优先、甚至免费。

支持的功能一览

硬件要求

• iPhone 15 Pro 及更新机型
• M 系列芯片的 iPad
• Apple Silicon Mac

快速上手：第一次调用

使用 Foundation Models 框架非常简单，几行代码即可完成一次 AI 对话：

import FoundationModels

// 1. 获取系统默认的设备端语言模型
let model = SystemLanguageModel.default

// 2. 检查模型是否可用（硬件是否支持 Apple Intelligence）
guard case .available = model.availability else {
    print("当前设备不支持 Apple Intelligence")
    return
}

do {
    // 3. 创建会话 —— 会话会维护对话历史
    let session = LanguageModelSession()
    
    // 4. 发送提示词并等待回复
    let response = try await session.respond(
        to: "给我推荐一款适合徒步旅行的 App 名称。"
    )
    
    // 5. 获取模型输出的文本内容
    print(response.content)
    // 可能的输出: "可以考虑'山野足迹'、'徒步指南'或'自然探险家'等名称..."
    
} catch {
    print("调用失败: \(error.localizedDescription)")
}

关键概念：LanguageModelSession

LanguageModelSession 是框架的核心入口。它会自动维护对话历史，这意味着你可以在同一个 session 实例上进行多轮对话：

// 第一轮对话
let response1 = try await session.respond(to: "我叫小明，我喜欢爬山。")

// 第二轮对话 —— session 会记住上下文
let response2 = try await session.respond(to: "根据我的兴趣爱好推荐一个周末活动。")
// 模型会基于"我喜欢爬山"这个上下文来回答

结构化输出：告别 JSON 解析

这是 Foundation Models 框架最引人注目的特性之一。通过 @Generable 宏，你可以直接定义期望的 Swift 类型，模型会直接生成该类型的实例——完全不需要手写 JSON 解析代码。

import FoundationModels

// 1. 用 @Generable 宏标注你期望的输出结构
@Generable
struct AppNameSuggestion {
    let name: String        // App 名称
    let tagline: String     // 宣传语
    let category: String    // 分类
}

// 2. 创建会话
let session = LanguageModelSession()

// 3. 调用模型，指定结构化输出类型
let response = try await session.respond(
    to: "为一款记录登山路线的 App 提供命名建议。",
    generating: AppNameSuggestion.self
)

// 4. 直接访问结构体属性，无需任何解析！
print(response.content.name)      // 例如: "山径漫游"
print(response.content.tagline)   // 例如: "每一步，都是风景"
print(response.content.category)  // 例如: "户外运动"

更复杂的结构化输出示例

// 复杂嵌套结构也可以直接生成
@Generable
struct TravelPlan {
    let destination: String         // 目的地
    let duration: Int               // 建议天数
    let budget: String              // 预算范围
    let dailyItinerary: [DayPlan]   // 每日行程
    let tips: [String]              // 旅行贴士
}

@Generable
struct DayPlan {
    let day: Int                    // 第几天
    let activities: [String]        // 活动安排
    let meals: [String]             // 推荐美食
}

let plan = try await session.respond(
    to: "计划一次从北京出发的3天短途旅行，预算2000元以内。",
    generating: TravelPlan.self
)

print(plan.content.destination)     // "承德"
print(plan.content.duration)        // 3
print(plan.content.dailyItinerary.count) // 每天的详细安排

为什么结构化输出如此重要？

传统的 AI 应用开发中，"让 LLM 返回 JSON"是一个让人头疼的问题：

1. 格式不稳定：模型有时返回纯文本而非 JSON
2. 字段缺失：某些字段可能被遗漏
3. 类型错误：数字变成了字符串
4. 解析代码脆弱：需要大量的 guard-let 和 try-catch

@Generable 宏从根本上解决了这些问题——它确保模型的输出严格按照 Swift 类型系统生成，输出即为编译时安全的 Swift 对象。

模型运行的三个层级

Foundation Models 框架的核心设计哲学是 "一个 API，三种后端"。你可以根据功能需求，在不同层级的模型之间无缝切换：

                    ┌──────────────────────────┐
                    │   LanguageModelSession    │  ← 统一的 API 入口
                    └───────────┬──────────────┘
                                │
            ┌───────────────────┼───────────────────┐
            ▼                   ▼                   ▼
   ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
   │   设备端模型     │  │  Private Cloud  │  │  第三方云端模型   │
   │  (On-Device)   │  │    Compute     │  │  (Claude/Gemini) │
   └────────────────┘  └────────────────┘  └────────────────┘
     • 完全离线          • 更大上下文窗口      • 前沿推理能力
     • 零延迟            • 更强推理能力        • 最长上下文
     • 隐私最高          • 需要网络            • 需要网络 + API Key
     • 永远免费          • App Store 小企业     • 按量付费
                          计划免费（<200万下载）

层级 1：设备端模型（默认）

// 最简单的用法 —— 默认使用设备端模型
let session = LanguageModelSession()
let response = try await session.respond(to: "总结这段文字...")

• 优点：完全离线、零延迟、隐私最高、永久免费
• 局限：模型相对较小，不适合复杂推理或需要广泛世界知识的任务
• 适用场景：文本摘要、内容分类、标签提取、简单的结构化数据抽取、短文本生成

层级 2：Private Cloud Compute (PCC)

// iOS 27+ 可以使用 Apple 的服务器端模型
import FoundationModels

// 配置使用 PCC 模型（需要 App Store Small Business Program 资格）
let pccModel = try await SystemLanguageModel.server(
    model: .foundation
)
let session = LanguageModelSession(model: pccModel)
let response = try await session.respond(to: "复杂的问题...")

• 优点：更大的上下文窗口、更强的推理能力、依然保持 Apple 的隐私标准
• 条件：需要加入 App Store Small Business Program，App 总下载量低于 200 万次
• 限制：有每日使用量上限，需要网络连接
• 适用场景：需要更强推理但不想接入第三方 API 的场景

层级 3：第三方云端模型

// 通过 LanguageModel 协议接入 Claude 等第三方模型
import FoundationModels
import ClaudeForFoundationModels  // 假设的 Claude 适配包

let claudeModel = ClaudeLanguageModel(
    name: .sonnet4_6,
    auth: .apiKey("your-api-key")
)
let session = LanguageModelSession(model: claudeModel)
let response = try await session.respond(to: "需要前沿推理的复杂任务...")

• 优点：最前沿的推理能力、最长的上下文
• 代价：数据离开 Apple 隐私边界、需要第三方 API Key、按量付费
• 适用场景：真正需要 GPT-4/Claude 级别推理的少数场景

推荐的升级阶梯策略

/// 推荐的模型路由策略：先本地、再 PCC、最后第三方
func getIntelligentResponse(to prompt: String) async throws -> String {
    // 第一步：尝试设备端模型
    let localSession = LanguageModelSession()
    do {
        let response = try await localSession.respond(to: prompt)
        // 简单的成功则直接返回
        if isSatisfactory(response.content) {
            return response.content
        }
    } catch {
        // 设备端失败，继续尝试 PCC
    }
    
    // 第二步：升级到 Private Cloud Compute
    if let pccModel = try? await SystemLanguageModel.server(model: .foundation) {
        let pccSession = LanguageModelSession(model: pccModel)
        if let response = try? await pccSession.respond(to: prompt) {
            return response.content
        }
    }
    
    // 第三步：回退到第三方模型（作为最后的选择）
    let cloudModel = ClaudeLanguageModel(name: .sonnet4_6, auth: .apiKey(apiKey))
    let cloudSession = LanguageModelSession(model: cloudModel)
    return try await cloudSession.respond(to: prompt).content
}

多模态输入：图像 + 文本

WWDC 2026 的重大更新之一是多模态支持。你现在可以在提示词中同时传入图像和文本，让模型对视觉内容进行推理。

import FoundationModels
import UIKit

@Generable
struct ReceiptInfo {
    let merchant: String       // 商家名称
    let totalAmount: Double    // 总金额
    let date: String           // 日期
    let items: [String]        // 购买项目
    let category: String       // 消费分类
}

let session = LanguageModelSession()

// 读取收据图片
guard let receiptImage = UIImage(named: "receipt") else {
    return
}

// 在 Prompt 中同时传入文本和图像
let receipt = try await session.respond(
    to: Prompt {
        "识别这张收据的内容，并提取关键信息。"
        receiptImage   // 将图片直接传入 Prompt
    },
    generating: ReceiptInfo.self
)

print("商家: \(receipt.content.merchant)")
print("金额: \(receipt.content.totalAmount)")
print("分类: \(receipt.content.category)")

OCR 和条形码工具调用

更强大的是，模型可以主动调用 Vision 框架的 OCR 和条形码读取工具来获取精确数据，而不是靠"记忆"猜数字：

// 定义一个可供模型调用的工具
struct ImageAnalyzer: LanguageModelTool {
    // 工具描述 —— 告诉模型何时调用
    static var description: String {
        "从图像中精确提取文字内容，适用于收据、名片、文档等场景"
    }
    
    // 模型调用此工具时会传入的参数
    func callAsFunction(image: UIImage) async throws -> String {
        // 使用 Vision 框架进行 OCR
        // 返回精确的识别结果
        return recognizedText
    }
}

// 将工具注册到会话中
let session = LanguageModelSession(tools: [ImageAnalyzer()])

这种 "模型 + 确定性工具" 的组合是工程上最可靠的 AI 功能实现方式——把需要精确值的地方交给工具，把需要理解和推理的地方交给模型。

第三方模型接入

Foundation Models 的强大之处在于它通过 LanguageModel 协议来抽象所有模型提供商。任何遵循该协议的第三方包，都可以无缝接入。

// ========== 使用 Claude ==========
import FoundationModels
import ClaudeForFoundationModels  // Anthropic 提供的 Swift 包

let claudeSession = LanguageModelSession(
    model: ClaudeLanguageModel(
        name: .sonnet4_6,
        auth: .apiKey("sk-ant-xxx")
    )
)

// ========== 使用 Gemini ==========
import GeminiForFoundationModels  // Google 提供的 Swift 包

let geminiSession = LanguageModelSession(
    model: GeminiLanguageModel(
        name: .pro_2_5,
        auth: .apiKey("xxx")
    )
)

// ========== 调用方式完全一致 ==========
let claudeResponse = try await claudeSession.respond(
    to: "分析这段 Swift 代码的性能问题...",
    generating: CodeAnalysis.self
)

let geminiResponse = try await geminiSession.respond(
    to: "分析这段 Swift 代码的性能问题...",
    generating: CodeAnalysis.self
)

封装一个可切换的模型服务层

/// 抽象模型提供者，方便全局切换和测试
protocol AIModelProvider {
    func createSession() -> LanguageModelSession
}

// 设备端实现
struct OnDeviceProvider: AIModelProvider {
    func createSession() -> LanguageModelSession {
        LanguageModelSession()
    }
}

// Claude 实现
struct ClaudeProvider: AIModelProvider {
    let apiKey: String
    
    func createSession() -> LanguageModelSession {
        let model = ClaudeLanguageModel(
            name: .sonnet4_6,
            auth: .apiKey(apiKey)
        )
        return LanguageModelSession(model: model)
    }
}

// 使用示例
class AIService {
    private let provider: AIModelProvider
    
    init(provider: AIModelProvider) {
        self.provider = provider
    }
    
    func analyzeText(_ text: String) async throws -> AnalysisResult {
        let session = provider.createSession()
        return try await session.respond(
            to: text,
            generating: AnalysisResult.self
        ).content
    }
}

// 生产环境 vs 测试环境轻松切换
#if DEBUG
let aiService = AIService(provider: OnDeviceProvider())
#else
let aiService = AIService(provider: ClaudeProvider(apiKey: config.apiKey))
#endif

Dynamic Profiles 与多智能体工作流

这是 WWDC 2026 最让人兴奋的功能之一。Dynamic Profile 允许你在同一个会话中动态切换模型的"角色"和可用工具集，从而实现多智能体协作模式。

// 定义不同角色的 Profile
let planningProfile = Profile(
    instructions: "你是一个任务规划专家。将用户需求拆解为可执行的子任务。",
    tools: []
)

let executionProfile = Profile(
    instructions: "你是一个执行专家。按照计划逐步完成任务。",
    tools: [SearchTool(), CalculatorTool(), FileManagerTool()]
)

let reviewProfile = Profile(
    instructions: "你是一个审核专家。检查执行结果的质量和完整性。",
    tools: []
)

let session = LanguageModelSession()

// 第一阶段：规划
try await session.apply(planningProfile)
let plan = try await session.respond(
    to: "帮我分析过去一周的股票数据，找出最佳买入时机。",
    generating: TaskPlan.self
)

// 第二阶段：执行
try await session.apply(executionProfile)
let result = try await session.respond(
    to: "按照上述计划开始执行。",
    generating: ExecutionResult.self
)

// 第三阶段：审核
try await session.apply(reviewProfile)
let review = try await session.respond(
    to: "审核执行结果，提供改进建议。",
    generating: ReviewResult.self
)

设计建议

保持每个 Profile 职责窄而精。 一个拥有 3 个精准工具和紧凑指令的 Profile，远比一个装了 12 个工具和模糊指令的 Profile 表现更好。模型用来"决定做什么"的 token 越少，越不容易做出错误的工具调用。

与 Core AI 框架的关系

WWDC 2026 还发布了 Core AI 框架，它和 Foundation Models 的关系如下：

一句话总结：日常开发用 Foundation Models，需要跑自定义模型时才用 Core AI。

最佳实践与踩坑指南

✅ 应该做的 5 件事

1. 从结构化输出开始 —— 用 @Generable 是避免 AI 功能崩溃的最有效手段
2. 封装模型提供者 —— 在你自己代码里用一个 protocol 隔离模型选择，方便测试和切换
3. 工具优先于提示词 —— 日期、金额、库存、用户数据这些精确值应该来自工具调用，而非模型记忆
4. 做好硬件降级方案 —— 不是所有用户都有 Apple Intelligence 设备，规划好非 AI 的降级路径
5. 尽早用 Instruments 测量 —— Xcode 27 新增了 FoundationModels instrument，延迟和 token 用量影响很大

❌ 不要做的 3 件事

1. 不要默认用云端模型 —— 先从设备端开始，按需升级
2. 不要在提示词里塞"事实" —— 让工具调用返回事实，让模型负责推理
3. 不要忽略隐私边界 —— 一旦切换到第三方云端模型，数据就离开了 Apple 的隐私保护范围

硬件兼容性检查

/// 检查当前设备是否支持 Foundation Models
func checkFoundationModelsAvailability() -> AIMode {
    let model = SystemLanguageModel.default
    
    // 设备端模型可用
    if case .available = model.availability {
        return .onDevice
    }
    
    // 不支持本地模型，检查网络是否可用（降级到 PCC 或云端）
    return .cloudOnly
}

enum AIMode {
    case onDevice   // 可以使用设备端 AI
    case cloudOnly  // 只能使用云端 AI
    case unavailable
    
    var description: String {
        switch self {
        case .onDevice:
            return "完整的 AI 功能可用（设备端）"
        case .cloudOnly:
            return "部分 AI 功能可用（需要网络）"
        case .unavailable:
            return "当前设备不支持 AI 功能"
        }
    }
}

线上发布检查清单

□ 设备端模型降级路径已实现
□ @Generable 类型已定义，无手写 JSON 解析
□ AI 功能有对应的确定性 fallback
□ 第三方 API Key 不外泄（不在客户端硬编码）
□ Instruments profiling 已完成，延迟在可接受范围
□ 隐私声明已更新（如涉及云端模型）

个人见解与总结

这为什么重要？

作为一个做了多年 iOS 开发的工程师，我对 Foundation Models 框架的出现感到非常兴奋。过去几年，AI 能力一直是 App 开发中那个"别人家的孩子"——我们想用，但接入成本高、隐私风险大、还要被云服务商绑定。

Apple 的做法很"Apple"：先保证隐私，再谈能力。设备端推理意味着用户的敏感数据根本不会离开手机。小企业免费使用 PCC 意味着独立开发者也负担得起。统一 API 接入第三方模型意味着你不会被锁死在 Apple 生态里。

我看到的三个趋势

1. AI 将成为 iOS 开发的基础能力——就像现在你用 URLSession 做网络请求一样，以后 LanguageModelSession 会成为每个 App 的标配
2. "设备端优先"成为新范式——隐私法规越来越严，用户越来越在意数据安全，能在本地跑的 AI 才是可持续的方案
3. 智能体模式是下一个战场——Dynamic Profiles 让 App 内置多角色 AI 协作成为可能，类似"一位 AI 规划、一位 AI 执行、一位 AI 审核"的模式将大量出现

适合在什么场景使用？

一点担忧

设备端模型效果目前还比不上 Claude/GPT-4，对于需要大量世界知识和复杂推理的任务，可能还是要接云端模型。但随着 Apple 自研芯片的演进和设备端模型的迭代，这个差距会逐渐缩小。而且别忘了，不是所有 AI 功能都需要 GPT-4 级别的智能——很多场景下，一个快、私密、免费的本地模型反而更合适。

扩展场景：结合 App Intents 打造 Siri 智能体验

Foundation Models 和 App Intents 的结合使用是 WWDC 2026 的另一个亮点。你可以将 AI 能力暴露给 Siri，让用户通过自然语言操控你的 App：

import AppIntents
import FoundationModels

struct SummarizeNotesIntent: AppIntent {
    static var title: LocalizedStringResource = "总结笔记"
    
    @Parameter(title: "时间范围")
    var timeRange: String
    
    func perform() async throws -> some IntentResult {
        // 获取笔记数据
        let notes = await NoteManager.shared.fetchNotes(in: timeRange)
        
        // 使用 Foundation Models 生成摘要
        let session = LanguageModelSession()
        let response = try await session.respond(
            to: "请用简洁的语言总结以下笔记的要点：\n\(notes.joined(separator: "\n"))"
        )
        
        // 返回结果给 Siri
        return .result(dialog: "以下是您的笔记摘要：\(response.content)")
    }
}

用户只需对 Siri 说："帮我总结一下这周的笔记"，就能触发上述 App Intent，整个过程 AI 都在设备端完成。

参考资料

1. Getting started with Apple's Foundation Models framework - Tanaschita
2. Apple Developer - WWDC26 iOS 指南
3. Apple Foundation Models Framework: 2026 Swift Guide - Lushbinary
4. Whats new in the Foundation Models framework - WWDC 2026 Session
5. Building agentic app experiences with Foundation Models - WWDC 2026 Session
6. Apple Developer Forums: Machine Learning and AI

原文发布日期：2026年6月22日
中文博客编写日期：2026年7月3日
作者注：本文在原文基础上扩充了 WWDC26 官方资料、Luishbinary 技术指南的深入分析以及个人实践经验，力求为中文读者呈现 Foundation Models 框架的完整图景。