宏 @Generable @Guide FoundationModels Swift

FoundationModels 中的 @Generable 与 @Guide 宏：自动化模型生成

FoundationModels 框架中的 @Generable 和 @Guide 宏支持基于语言模型输出生成 Swift 结构体实例。编译器会为 LanguageModelSession 的流式响应合成协议和方法，从而减少样板代码，并确保处理来自大语言模型的结构化数据时的类型安全。

将 @Generable 应用于结构体可使其兼容生成机制。该结构体必须遵循 Identifiable 协议以实现正确的对象识别。

@Generable
struct ShoppingItem: Identifiable {
    let id: String
    let value: String
}

可选的 description 参数用于阐明生成上下文，引导大语言模型生成相关结果。

@Generable(description: "生成购物清单中的项目")
struct ShoppingItem: Identifiable {
    let id: String
    let value: String
}

使用 @Guide 细化属性

@Guide 宏应用于单个属性，以向大语言模型提供指令。这可以在不改变模型生成逻辑的前提下，精确控制字段内容。

@Generable(description: "生成购物清单中的项目")
struct ShoppingItem: Identifiable {
    let id: String

    @Guide(description: "要购买的产品的名称")
    let value: String
}

@Guide 注解会作为指令传递给语言模型会话，影响输出的解析和验证。这对于具有嵌套类型或特定数据格式的复杂结构非常有用。

与 LanguageModelSession 集成

生成的模型通过 streamResponse 方法集成到异步任务中。该方法接受结果类型和提示，返回一个数据块流。

private func generateShoppingList() {
    let prompt = "创建 15 个购物清单项目"
    Task {
        do {
            let session = LanguageModelSession()

            let response = session.streamResponse(
                generating: [ShoppingItem].self
            ) {
                prompt
            }

            isGenerating = true

            for try await chunk in response {
                self.shoppingList = chunk.compactMap {
                    guard let id = $0.id, let task = $0.value else {
                        return nil
                    }

                    return ShoppingItem(id: id, value: task)
                }
            }

            isGenerating = false
        } catch {
            print(error.localizedDescription)
            isGenerating = false
        }
    }
}

数据块处理包括过滤空值并更新 UI 状态，确保生成过程中的界面响应性。

• 流式处理：数据块异步到达，最大限度减少延迟。
• 类型安全：编译器验证结构体的协议遵循情况。
• 验证：Guard 表达式过滤不完整的对象。
• 错误处理：Try-catch 捕获会话失败。

SwiftUI 集成实现流式生成

在 SwiftUI 视图中，模型绑定到 @State。按钮触发生成，并在执行期间禁用。

struct ContentView: View {
    @State private var shoppingList: [ShoppingItem] = []
    @State private var isGenerating: Bool = false

    var body: some View {
        List(shoppingList) { item in
            Text(item.value)
        }
        .toolbar {
            ToolbarItem(placement: .bottomBar) {
                Button(
                    "生成购物清单",
                    systemImage: "cart.fill.badge.plus"
                ) {
                    generateShoppingList()
                }
                .disabled(isGenerating)
            }
        }
    }

    private func generateShoppingList() {
        // ...
    }
}

UI 会随着数据到达而响应式更新，这展示了在应用中动态内容的实际应用。

关键要点

• @Generable 为从大语言模型到 Swift 结构体的流式生成合成协议。
• @Guide 提供属性级指令，用于精确解析输出。
• 与 LanguageModelSession 集成支持具有类型安全的异步流式处理。
• 适用于在 SwiftUI 应用中生成列表、表单和动态数据。
• 在保持对生成对象结构控制的同时，减少样板代码。

— Editorial Team