생성형 AI를 실제 웹 서비스의 데이터베이스나 백엔드 로직에 연동하려면 텍스트 답변 대신 검증 가능한 규격화된 **JSON 데이터(Structured Output)**로 받아야 합니다.
1. Structured Output 용어 사전 (Glossary)
- JSON (JavaScript Object Notation): 키-값(Key-Value) 구조로 데이터를 표현하는 국제 경량 표준 데이터 교환 포맷입니다.
- Pydantic: 파이썬에서 데이터 구조와 타입을 클래스 형태로 선언하고, 런타임에 자동으로 데이터 유효성을 검증(Validation)해주는 대표적 라이브러리입니다.
- Structured Outputs: OpenAI가 도입한 기능으로, 제공된 JSON Schema를 모델이 100% 완벽하게 준수하도록 이진 문법 제약을 거는 기술입니다.
2. Pydantic 라이브러리 기반 정밀 JSON 데이터 추출
from pydantic import BaseModel, Field
from typing import List, Optional
# 1. Pydantic을 이용한 원하는 출력 스키마 정의
class MovieReviewAnalysis(BaseModel):
movie_title: str = Field(description="영화 제목")
rating: float = Field(description="1.0 ~ 5.0 사이의 별점")
sentiment: str = Field(description="긍정, 부정, 중립 중 하나")
keywords: List[str] = Field(description="리뷰에서 추출한 핵심 키워드 3개")
summary: str = Field(description="한 줄 요약")
# 2. OpenAI Structured Output API 호출
completion = client.beta.chat.completions.parse(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "너는 영화 리뷰 데이터 분석 시스템이야."},
{"role": "user", "content": "인터스텔라 봤는데 우주 연출이 대박이고 음악이 지렸다. 인생작 5점 줌!"}
],
response_format=MovieReviewAnalysis,
)
# 3. 파싱된 객체 바로 사용
result: MovieReviewAnalysis = completion.choices[0].message.parsed
print(f"영화제목: {result.movie_title}")
print(f"평점: {result.rating} / 감정: {result.sentiment}")
print(f"키워드: {result.keywords}")
3. 자주 묻는 질문 (Q&A)
Q. response_format={"type": "json_object"}와 Structured Outputs의 차이는?
A. 기존 json_object 방식은 JSON 형태로 출력하려 노력하지만 키 이름이 빠지거나 문법이 깨질 확률이 미세하게 존재했습니다. 반면 Structured Outputs(Pydantic 스키마 연동)는 스키마 일치율 100%를 보장합니다.