foundation-models-on-device

name	foundation-models-on-device
description	Apple FoundationModels 框架用于设备端 LLM——文本生成、使用 @Generable 的引导生成、工具调用和快照流式传输，适用于 iOS 26+。

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 操作（搜索、计算、查找）