Pydantic 출력 파서를 활용한 깔끔한 데이터 검증 및 변환

최신 파이썬 애플리케이션에서는 외부 API, LLM(대형 언어 모델) 등으로부터 받아온 JSON이나 텍스트를 안전하고 편리하게 다루는 일이 중요해졌습니다. 이때 Pydantic의 출력 파서(Output Parser) 기능을 활용하면, 수신한 데이터를 자동으로 검증하고 원하는 형태로 변환할 수 있어 코드의 안정성과 가독성을 크게 향상시킬 수 있습니다.

---

1. Pydantic란 무엇인가요?

Pydantic은 데이터 모델을 정의하고, 입력된 데이터를 타입 검증과 변환을 통해 안전하게 객체로 만드는 라이브러리입니다. FastAPI의 기본 검증 엔진으로 사용되며, 다음과 같은 장점이 있습니다.

• 자동 타입 변환: 문자열을 숫자로, 날짜/시간 문자열을 datetime 객체로 자동 변환합니다.
• 엄격한 검증: 필수 필드 누락, 잘못된 타입, 정해진 규격(format)에 어긋날 경우 예외를 발생시킵니다.
• 유연한 어노테이션: Field, validator를 활용해 추가 규칙을 정의할 수 있습니다.

---

2. 출력 파서(Output Parser)란?

출력 파서는 외부에서 가져온 미검증 데이터를 Pydantic 모델로 파싱(parse) 하는 과정을 의미합니다. 예를 들어, LLM이나 REST API 호출 결과를 원시 str 혹은 dict 형태로 받은 후, Pydantic 모델에 전달하여 안전하게 타입 검사와 구조 검증을 수행할 수 있습니다.

from pydantic import BaseModel, ValidationError

class UserModel(BaseModel):
    id: int
    name: str
    signup_date: datetime

# 외부에서 받은 JSON 문자열
raw_json = '{"id": "123", "name": "Alice", "signup_date": "2025-07-26T14:30:00"}'

try:
    user = UserModel.parse_raw(raw_json)
    print(user.id, type(user.id))           # 123 <class 'int'>
    print(user.signup_date, type(user.signup_date))  # 2025-07-26 14:30:00 <class 'datetime.datetime'>
except ValidationError as e:
    print(e.json())

위 예시에서 parse_raw는 JSON 문자열을 파싱, 타입 변환, 검증을 한 번에 수행합니다.

---

3. 어노테이션(Annotations) 활용하기

Pydantic의 핵심은 파이썬 타입 어노테이션입니다. 어노테이션을 통해 각 필드에 대한 타입과 추가 설정을 정의할 수 있습니다.

3-1. 기본 타입과 Field 설정

from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(..., description="상품 이름", min_length=1)
    price: float = Field(..., gt=0, description="상품 가격")
    tags: list[str] = []  # 기본값으로 빈 리스트 지정

• Field(..., ...)에서 ...은 필수 필드를 의미합니다.
• description, gt(greater than), min_length와 같은 키워드를 통해 세부 검증 규칙을 추가할 수 있습니다.

3-2. 커스텀 검증기(validator)

from pydantic import validator

class User(BaseModel):
    username: str
    email: str

    @validator('email')
    def valid_email(cls, v):
        if '@' not in v:
            raise ValueError('유효한 이메일 주소여야 합니다.')
        return v.lower()

• @validator('필드명') 데코레이터로 특정 필드에 대한 추가 검증 로직을 정의할 수 있습니다.
• 검증에 통과하면 반환값이 최종 필드 값으로 사용됩니다.

---

4. 실제 활용 예시: LLM 출력 파싱하기

LLM에서 JSON 형식의 응답을 기대하지만, 가끔 형식이 흐트러져 올 수 있습니다. 이때 Pydantic 모델로 한번 검증하고, 예외 처리로 안정적인 흐름을 유지할 수 있습니다.

from datetime import date
from typing import Literal
from pydantic import BaseModel, ValidationError

class Forecast(BaseModel):
    date: date
    condition: Literal['sunny', 'cloudy', 'rainy', 'snowy']
    temp_high: float
    temp_low: float

# 예시: LLM에서 반환된 텍스트 (JSON 유사)
llm_output = '''
{
    "date": "2025-07-27",
    "condition": "Sunny",
    "temp_high": "30.5",
    "temp_low": 22
}
'''

try:
    forecast = Forecast.parse_raw(llm_output)
    print(forecast)
except ValidationError as e:
    # 다양한 오류 메시지 출력
    print("파싱 오류:", e.errors())

• Literal을 이용해 허용된 문자열 목록을 제한합니다.
• 대소문자 차이나 타입 불일치 시 ValidationError를 통해 상세 원인을 확인할 수 있습니다.

---

5. 팁과 주의사항

1. 예외 처리를 반드시 추가하세요. 파싱 실패 시 앱 전체가 중단되지 않도록 try/except 블록을 활용합니다.
2. 모델 재활용: 다양한 입력 형태에 대응하려면, parse_raw, parse_obj, parse_file 등 여러 메서드를 활용해 보세요.
3. 커스텀 타입: constr, PositiveInt 등 Pydantic이 제공하는 복합 타입으로 보다 정밀한 검증이 가능합니다.

Pydantic 출력 파서를 활용하면, 외부 데이터와의 상호작용에서 발생할 수 있는 오류를 최소화하고, 안전한 데이터 파싱 흐름을 구축할 수 있습니다. 어노테이션을 적절히 활용하여 명확한 스키마를 정의하고, 신뢰성 높은 애플리케이션을 개발해 보시기 바랍니다.