---

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

FoundationModels：设备端 LLM（iOS 26）

将 Apple 设备端语言模型集成到应用中的模式，使用 FoundationModels 框架。涵盖文本生成、使用 @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("Device not eligible for Apple Intelligence")
        case .unavailable(.appleIntelligenceNotEnabled):
            Text("Please enable Apple Intelligence in Settings")
        case .unavailable(.modelNotReady):
            Text("Model is downloading or not ready")
        case .unavailable(let other):
            Text("Model unavailable: \(other)")
        }
    }
}

核心模式 — 基础会话

// 单轮对话：每次创建新会话
let session = LanguageModelSession()
let response = try await session.respond(to: "What's a good month to visit Paris?")
print(response.content)

// 多轮对话：复用会话以保持上下文
let session = LanguageModelSession(instructions: """
    You are a cooking assistant.
    Provide recipe suggestions based on ingredients.
    Keep suggestions brief and practical.
    """)

let first = try await session.respond(to: "I have chicken and rice")
let followUp = try await session.respond(to: "What about a vegetarian option?")

指令要点：

• 定义模型角色（"You are a mentor"）
• 指定要做什么（"Help extract calendar events"）
• 设置风格偏好（"Respond as briefly as possible"）
• 添加安全措施（"Respond with 'I can't help with that' for dangerous requests"）

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

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

1. 定义 Generable 类型

@Generable(description: "Basic profile information about a cat")
struct CatProfile {
    var name: String

    @Guide(description: "The age of the cat", .range(0...20))
    var age: Int

    @Guide(description: "A one sentence profile about the cat's personality")
    var profile: String
}

2. 请求结构化输出

let response = try await session.respond(
    to: "Generate a cute rescue cat",
    generating: CatProfile.self
)

// 直接访问结构化字段
print("Name: \(response.content.name)")
print("Age: \(response.content.age)")
print("Profile: \(response.content.profile)")

支持的 @Guide 约束

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

核心模式 — 工具调用

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

1. 定义工具

struct RecipeSearchTool: Tool {
    let name = "recipe_search"
    let description = "Search for recipes matching a given term and return a list of results."

    @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: "Find me some pasta recipes")

3. 处理工具错误

do {
    let answer = try await session.respond(to: "Find a recipe for tomato soup.")
} catch let error as LanguageModelSession.ToolCallError {
    print(error.tool.name)
    if case .databaseIsEmpty = error.underlyingError as? RecipeSearchToolError {
        // 处理特定工具错误
    }
}

核心模式 — 快照流式传输

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

@Generable
struct TripIdeas {
    @Guide(description: "Ideas for upcoming trips")
    var ideas: [String]
}

let stream = session.streamResponse(
    to: "Suggest 3 weekend trip ideas",
    generating: TripIdeas.self
)

for try await partial in stream {
    // partial.content 是 TripIdeas.PartiallyGenerated
    // 字段在生成时逐步填充
    print(partial.content.ideas ?? [])
}