foundation-models-on-device

FoundationModels：设备端 LLM（iOS 26）

使用 FoundationModels 框架将 Apple 设备端语言模型集成到应用中的模式。涵盖文本生成、使用 @Generable 的结构化输出、自定义工具调用和快照流式传输——全部在设备端运行，以保护隐私并支持离线使用。

何时激活

• 使用 Apple Intelligence 在设备端构建 AI 功能
• 无需依赖云端即可生成或总结文本
• 从自然语言输入中提取结构化数据
• 为特定领域的 AI 操作实现自定义工具调用
• 流式传输结构化响应以实现实时 UI 更新
• 需要保护隐私的 AI（数据不离开设备）

核心模式 — 可用性检查

在创建会话之前始终检查模型可用性：

struct GenerativeView: View {
    private var model = SystemLanguageModel.default

    var body: some View {
        switch model.availability {
        case .available:
            ContentView()
        case .unavailable(.deviceNotEligible):
            Text("设备不符合 Apple Intelligence 条件")
        case .unavailable(.appleIntelligenceNotEnabled):
            Text("请在设置中启用 Apple Intelligence")
        case .unavailable(.modelNotReady):
            Text("模型正在下载或未就绪")
        case .unavailable(let other):
            Text("模型不可用：\(other)")
        }
    }
}

核心模式 — 基本会话

// 单轮：每次创建新会话
let session = LanguageModelSession()
let response = try await session.respond(to: "去巴黎旅游哪个月份好？")
print(response.content)

// 多轮：重用会话以保持对话上下文
let session = LanguageModelSession(instructions: """
    你是一个烹饪助手。
    根据食材提供食谱建议。
    保持建议简洁实用。
    """)

let first = try await session.respond(to: "我有鸡肉和米饭")
let followUp = try await session.respond(to: "那素食选项呢？")

指令的关键点：

• 定义模型角色（"你是一个导师"）
• 指定要做什么（"帮助提取日历事件"）
• 设置风格偏好（"尽可能简短地回答"）
• 添加安全措施（"对于危险请求，回答'我无法帮助'"）

核心模式 — 使用 @Generable 的引导生成

生成结构化的 Swift 类型而非原始字符串：

1. 定义 Generable 类型

@Generable(description: "关于猫的基本信息")
struct CatProfile {
    var name: String

    @Guide(description: "猫的年龄", .range(0...20))
    var age: Int

    @Guide(description: "关于猫性格的一句话简介")
    var profile: String
}

2. 请求结构化输出

let response = try await session.respond(
    to: "生成一只可爱的救援猫",
    generating: CatProfile.self
)

// 直接访问结构化字段
print("名字：\(response.content.name)")
print("年龄：\(response.content.age)")
print("简介：\(response.content.profile)")

支持的 @Guide 约束

• .range(0...20) — 数值范围
• .count(3) — 数组元素数量
• description: — 生成的语义指导

核心模式 — 工具调用

让模型调用自定义代码以执行特定领域任务：

1. 定义工具

struct RecipeSearchTool: Tool {
    let name = "recipe_search"
    let description = "搜索与给定术语匹配的食谱并返回结果列表。"

    @Generable
    struct Arguments {
        var searchTerm: String
        var numberOfResults: Int
    }

    func call(arguments: Arguments) async throws -> ToolOutput {
        let recipes = await searchRecipes(
            term: arguments.searchTerm,
            limit: arguments.numberOfResults
        )
        return .string(recipes.map { "- \($0.name): \($0.description)" }.joined(separator: "\n"))
    }
}

2. 创建带工具的会话

let session = LanguageModelSession(tools: [RecipeSearchTool()])
let response = try await session.respond(to: "给我找一些意大利面食谱")

3. 处理工具错误

do {
    let answer = try await session.respond(to: "找一个番茄汤的食谱。")
} catch let error as LanguageModelSession.ToolCallError {
    print(error.tool.name)
    if case .databaseIsEmpty = error.underlyingError as? RecipeSearchToolError {
        // 处理特定工具错误
    }
}

核心模式 — 快照流式传输

使用 PartiallyGenerated 类型流式传输结构化响应以实现实时 UI：

@Generable
struct TripIdeas {
    @Guide(description: "即将到来的旅行想法")
    var ideas: [String]
}

let stream = session.streamResponse(
    to: "有哪些令人兴奋的旅行想法？",
    generating: TripIdeas.self
)

for try await partial in stream {
    // partial: TripIdeas.PartiallyGenerated（所有属性均为 Optional）
    print(partial)
}

SwiftUI 集成

@State private var partialResult: TripIdeas.PartiallyGenerated?
@State private var errorMessage: String?

var body: some View {
    List {
        ForEach(partialResult?.ideas ?? [], id: \.self) { idea in
            Text(idea)
        }
    }
    .overlay {
        if let errorMessage { Text(errorMessage).foregroundStyle(.red) }
    }
    .task {
        do {
            let stream = session.streamResponse(to: prompt, generating: TripIdeas.self)
            for try await partial in stream {
                partialResult = partial
            }
        } catch {
            errorMessage = error.localizedDescription
        }
    }
}

关键设计决策

决策	理由
设备端执行	隐私 — 数据不离开设备；支持离线工作
4,096 token 限制	设备端模型约束；跨会话分块处理大数据
快照流式传输（非增量）	适合结构化输出；每个快照是完整的局部状态
@Generable 宏	编译时安全的结构化生成；自动生成 PartiallyGenerated 类型
每个会话单个请求	isResponding 防止并发请求；如需可创建多个会话
response.content（而非 .output）	正确的 API — 始终通过 .content 属性访问结果

最佳实践

• 始终检查 model.availability 在创建会话之前 — 处理所有不可用情况
• 使用 instructions 指导模型行为 — 它们优先于提示
• 检查 isResponding 在发送新请求之前 — 会话一次处理一个请求
• 访问 response.content 获取结果 — 而非 .output
• 将大输入分块 — 4,096 token 限制适用于指令 + 提示 + 输出的总和
• 使用 @Generable 进行结构化输出 — 比解析原始字符串有更强保证
• 使用 GenerationOptions(temperature:) 调整创造力（越高越有创意）
• 使用 Instruments 监控 — 使用 Xcode Instruments 分析请求性能

应避免的反模式

• 在未检查 model.availability 的情况下创建会话
• 发送超出 4,096 token 上下文窗口的输入
• 在单个会话上尝试并发请求
• 使用 .output 而非 .content 访问响应数据
• 在 @Generable 结构化输出可行时解析原始字符串响应
• 在单个提示中构建复杂的多步逻辑 — 拆分为多个聚焦提示
• 假设模型始终可用 — 设备资格和设置各不相同

何时使用

• 对隐私敏感的应用进行设备端文本生成
• 从用户输入中提取结构化数据（表单、自然语言命令）
• 必须离线工作的 AI 辅助功能
• 逐步显示生成内容的流式 UI
• 通过工具调用实现特定领域的 AI 操作（搜索、计算、查找）