매크로 @Generable @Guide FoundationModels Swift

FoundationModels의 @Generable 및 @Guide 매크로: 모델 생성 자동화

FoundationModels 프레임워크의 @Generable 및 @Guide 매크로는 언어 모델 출력을 기반으로 Swift 구조체 인스턴스를 생성할 수 있게 해줍니다. 컴파일러는 LanguageModelSession에서 스트리밍 응답을 위한 프로토콜과 메서드를 합성합니다. 이를 통해 LLM에서 구조화된 데이터를 다룰 때 보일러플레이트 코드를 줄이고 타입 안전성을 보장합니다.

@Generable을 구조체에 적용하면 생성 메커니즘과 호환됩니다. 구조체는 적절한 객체 식별을 위해 Identifiable을 준수해야 합니다.

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

선택적 description 매개변수는 생성 컨텍스트를 명확히 하여 LLM이 관련 결과를 생성하도록 유도합니다.

@Generable(description: "쇼핑 목록 항목 생성")
struct ShoppingItem: Identifiable {
    let id: String
    let value: String
}

@Guide로 속성 상세화

@Guide 매크로는 개별 속성에 적용하여 LLM에 지시사항을 제공합니다. 이는 모델 생성 로직을 변경하지 않고 필드 내용을 정밀하게 제어할 수 있게 해줍니다.

@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
        }
    }
}

청크 처리에는 nil 값 필터링과 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은 LLM에서 Swift 구조체로의 스트리밍 생성을 위한 프로토콜을 합성합니다.
• @Guide는 출력의 정밀한 파싱을 위한 속성 수준 지시사항을 제공합니다.
• LanguageModelSession과의 통합은 타입 안전성을 가진 비동기 스트리밍을 지원합니다.
• SwiftUI 애플리케이션에서 목록, 양식, 동적 데이터 생성에 적합합니다.
• 생성된 객체 구조에 대한 제어를 유지하면서 보일러플레이트 코드를 줄입니다.

— Editorial Team