구조화된 데이터 생성

구조화된 데이터 생성 (Generating Structured Data)

단순 텍스트 생성만으로는 부족하고 데이터 추출·분류·합성 데이터 생성 같은 작업에서는 구조화된 출력이 필요합니다. AI SDK는 generateText와 streamText의 output 속성으로 여러 모델 제공자에 걸쳐 구조화된 객체 생성을 표준화합니다. Zod·Valibot·JSON 스키마로 원하는 형태를 정의하면 모델이 그 구조를 따르는 데이터를 생성합니다.

출처: 공식문서

본문

텍스트 생성이 유용하긴 하지만, 실제 사용 사례는 구조화된 데이터 생성이 필요한 경우가 많습니다. 텍스트에서 정보를 추출하거나, 데이터를 분류하거나, 합성 데이터를 생성하는 것 같은 작업이 그 예입니다.

많은 LLM이 흔히 "JSON 모드"나 "도구"로 불리는 구조화된 데이터 생성에 대응합니다. 하지만 LLM이 잘못되거나 불완전한 구조화 데이터를 만들 수 있으므로 스키마를 직접 제공하고 생성 결과를 검증해야 합니다.

AI SDK는 generateText와 streamText의 output 속성을 통해 구조화된 객체 생성을 제공자별로 표준화합니다. Zod 스키마, Valibot, 또는 JSON 스키마로 원하는 데이터 형태를 지정하면 모델이 그 구조에 맞는 데이터를 생성합니다.

구조화된 출력 생성은 generateText/streamText 흐름의 일부이므로 같은 요청에서 도구 호출과 결합할 수 있습니다.

Output.object()와 generateText를 쓰면 프롬프트에서 구조화된 데이터를 생성할 수 있고, 스키마는 생성 데이터의 타입 안전성과 정확성을 보장하기 위해 검증에도 사용됩니다.

import { generateText, Output } from 'ai';
import { z } from 'zod';

const { output } = await generateText({
  model: "xai/grok-4.6",
  output: Output.object({
    schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(
          z.object({ name: z.string(), amount: z.string() }),
        ),
        steps: z.array(z.string()),
      }),
    }),
  }),
  prompt: 'Generate a lasagna recipe.',
});

구조화된 출력 생성은 AI SDK의 다단계 실행 모델(모델 호출 또는 도구 실행 1회 = 1단계)에서 한 단계로 계산됩니다. 도구와 결합할 때는 stopWhen 설정에 이를 반영하세요.

result.response.headers와 result.response.body로 제공자 원본 응답의 헤더와 본문에도 접근할 수 있습니다. 대화형 사용 사례에서 응답 시간이 우려된다면 streamText로 구조화된 출력을 스트리밍할 수도 있습니다.

더 알아보기