Macros @Generable @Guide FoundationModels Swift

Macros @Generable y @Guide en FoundationModels: Automatizando la Generación de Modelos

Las macros @Generable y @Guide en el framework FoundationModels permiten generar instancias de estructuras Swift a partir de las respuestas de modelos de lenguaje. El compilador sintetiza protocolos y métodos para manejar respuestas en streaming desde LanguageModelSession. Esto reduce código repetitivo y garantiza seguridad de tipos al trabajar con datos estructurados provenientes de LLMs.

Aplicar @Generable a una estructura la hace compatible con mecanismos de generación. La estructura debe conformar Identifiable para una correcta identificación de objetos.

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

El parámetro opcional description aclara el contexto de generación, guiando al LLM hacia resultados relevantes.

@Generable(description: "Generar elementos para una lista de compras")
struct ShoppingItem: Identifiable {
    let id: String
    let value: String
}

Detallando Propiedades con @Guide

La macro @Guide se aplica a propiedades individuales para proporcionar instrucciones al LLM. Esto ofrece un control preciso sobre el contenido de los campos sin alterar la lógica de generación del modelo.

@Generable(description: "Generar elementos para una lista de compras")
struct ShoppingItem: Identifiable {
    let id: String

    @Guide(description: "El nombre del producto a comprar")
    let value: String
}

Las anotaciones @Guide se pasan a la sesión del modelo de lenguaje como directivas, influyendo en el análisis y validación de las salidas. Esto es útil para estructuras complejas con tipos anidados o formatos de datos específicos.

Integración con LanguageModelSession

Los modelos generados se integran en tareas asíncronas mediante streamResponse. El método acepta un tipo de resultado y un prompt, devolviendo un flujo de fragmentos.

private func generateShoppingList() {
    let prompt = "Crea 15 elementos para una lista de compras"
    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
        }
    }
}

El procesamiento de fragmentos incluye filtrar valores nulos y actualizar el estado de la interfaz. Esto garantiza la capacidad de respuesta de la interfaz durante la generación.

• Procesamiento en Streaming: Los fragmentos llegan de forma asíncrona, minimizando retrasos.
• Seguridad de Tipos: El compilador verifica la conformidad de protocolos de la estructura.
• Validación: Las expresiones guard filtran objetos incompletos.
• Manejo de Errores: Try-catch captura fallos de la sesión.

Integración con SwiftUI para Generación en Streaming

En vistas SwiftUI, los modelos se vinculan a @State. Un botón activa la generación, deshabilitándose durante la ejecución.

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(
                    "Generar Lista de Compras",
                    systemImage: "cart.fill.badge.plus"
                ) {
                    generateShoppingList()
                }
                .disabled(isGenerating)
            }
        }
    }

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

La interfaz se actualiza de forma reactiva a medida que llegan los datos. Esto demuestra una aplicación real para contenido dinámico en aplicaciones.

Conclusiones Clave

• @Generable sintetiza protocolos para la generación en streaming desde LLMs hacia estructuras Swift.
• @Guide proporciona instrucciones a nivel de propiedad para un análisis preciso de las salidas.
• La integración con LanguageModelSession soporta streaming asíncrono con seguridad de tipos.
• Es adecuado para generar listas, formularios y datos dinámicos en aplicaciones SwiftUI.
• Reduce código repetitivo manteniendo el control sobre la estructura de los objetos generados.

— Editorial Team