Pydantic Discriminated Unions를 통한 다형성 설정 모델의 타입 안전성 확보

Pydantic V2 Discriminated Unions in FastAPI: Modeling Polymorphic AI Feature Configs Without Schema Sprawl

Ugur Aslim2026년 6월 3일8분intermediate

AI 요약

Context

다양한 AI 기능별로 상이한 설정 구조를 가진 환경에서 generic dict와 if/elif 분기문을 활용한 런타임 검증 구조 채택. 이로 인한 Schema mismatch의 프로덕션 유입 및 API 호출 단계에서의 지연된 에러 발견이라는 기술적 부채 발생.

Technical Solution

Pydantic V2의 Discriminated Unions를 도입하여 HTTP 레이어에서 데이터 구조를 즉시 결정하는 폴리모피즘 구현
Literal 타입을 활용한 discriminator 필드 정의로 각 기능별 모델(Summarization, Classification, Generation)의 명확한 구분
Annotated와 Union을 결합하여 입력 데이터의 feature_type 값에 따라 자동으로 적절한 모델로 라우팅하는 검증 체계 구축
Type Narrowing 기법을 적용하여 isinstance 체크 후 별도의 캐스팅 없이 타입 안전한 필드 접근 가능 구조 설계
OpenAPI Schema 자동 반영을 통해 클라이언트 측의 Trial-and-error를 제거한 Self-documenting API 계약 체결

실천 포인트

- 다형성 데이터 모델링 시 Generic dict 대신 Discriminated Unions를 사용하여 Validation 지점을 최전방으로 이동 - 중첩된 Union 구조 설계 시 모든 레벨에서 discriminator 필드 이름을 통일하여 Pydantic 라우팅 오류 방지 - 스키마 진화(Schema Evolution)에 대비하여 모델 정의 단계부터 schema_version 필드 포함을 고려 - Discriminator 값은 Union 트리 전체에서 유일하게 유지하여 검증 모호성 제거

태그

#Pydantic #Discriminated Unions #Polymorphism #Type Safety #FastAPI

원문 읽기