foundation-models-on-device

Apple FoundationModels 框架，用于设备端大语言模型（LLM）—— iOS 26+ 中的文本生成、配合 @Generable 的引导式生成、工具调用以及快照流式传输。

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

FoundationModels：设备端大语言模型 (iOS 26)

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

何时激活

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

核心模式 —— 可用性检查

在创建会话（Session）之前，请务必检查模型的可用性：

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: "那素食选择呢？")

提示词指令（Instructions）的关键点：

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

核心模式 —— 使用 @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. 定义一个工具（Tool）

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 来引导模型行为 —— 它们的优先级高于提示词（Prompts）
在发送新请求前检查 isResponding —— 会话每次处理一个请求
访问 response.content 获取结果 —— 而非 .output
将大型输入分成块 —— 4,096 Token 限制适用于指令 + 提示词 + 输出的总和
使用 @Generable 进行结构化输出 —— 比解析原始字符串具有更强的保证
使用 GenerationOptions(temperature:) 来调整创意程度（越高越有创意）
使用 Instruments 进行监控 —— 使用 Xcode Instruments 分析请求性能

应避免的反模式

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

何时使用

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

Repository: xu-xiang/everything-claude-code-zh
Path: skills/foundation-models-on-device/SKILL.md
Commit: dfbf946

Last updated: about 1 hour ago
First committed: 5 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.