OpenAI, Structured Outputs v2 정식 GA—스키마 복잡도 한계 대폭 완화
OpenAI가 Structured Outputs v2를 정식 출시하며 중첩 객체 깊이 제한을 기존 5단계에서 20단계로 확대하고, `anyOf` · `$ref` 등 JSON Schema 고급 키워드를 공식 지원하기 시작했다. 복잡한 도메인 모델을 그대로 스키마로 넘길 수 있어, 별도 전처리 없이 LLM 출력을 타입 안전하게 파싱하는 프로덕션 파이프라인 구축이 용이해진다.
무엇이 달라졌나
OpenAI Structured Outputs v2는 기존 버전 대비 다음 제약을 완화했다.
| 항목 | v1 | v2 |
|---|---|---|
| 중첩 객체 최대 깊이 | 5단계 | 20단계 |
| 프로퍼티 총 개수 상한 | 100개 | 500개 |
| anyOf 지원 | 미지원 | 정식 지원 |
| $ref / $defs | 미지원 | 정식 지원 |
gpt-4.1, gpt-4.1-mini, o3, o4-mini 등 현재 GA 상태인 모든 채팅 완성 모델에 즉시 적용되며, API 호출 시 "response_format": {"type": "json_schema", "json_schema": {...}} 구문은 동일하게 유지된다. 가격은 기존 토큰 요금과 동일하며 추가 비용은 없다(공식 페이지 참조).
한국 개발자·크리에이터에게 왜 중요한가
복잡한 비즈니스 로직을 LLM 출력과 연결하려면 지금까지 두 가지 우회책이 필요했다.
- 스키마 분할: 깊은 객체를 여러 번 나눠 호출한 뒤 앱 레이어에서 병합.
- 후처리 파서: JSON 출력을 받아 별도 검증·변환 레이어를 운영.
v2에서는 TypeScript zod 스키마나 Python pydantic 모델을 그대로 JSON Schema로 직렬화해 넘길 수 있어, 스키마 → 호출 → 파싱 3단계가 단일 흐름으로 압축된다. 특히 전자상거래 주문 객체, 의료 기록, 다단계 워크플로 상태 머신처럼 계층 구조가 깊은 도메인에서 효과가 즉각적이다.
# pydantic v2 모델을 바로 schema로 전달하는 예시
from pydantic import BaseModel
from openai import OpenAI
class LineItem(BaseModel):
sku: str
quantity: int
unit_price: float
class Order(BaseModel):
order_id: str
items: list[LineItem]
shipping_address: dict # 실제론 중첩 모델 가능
client = OpenAI()
completion = client.beta.chat.completions.parse(
model="gpt-4.1",
messages=[{"role": "user", "content": "주문 데이터 추출: ..."}],
response_format=Order,
)
order = completion.choices[0].message.parsed # Order 타입 보장
마이그레이션 체크리스트
- 기존 코드 호환: v1 스키마는 수정 없이 v2 엔드포인트에서 동작.
strict: true권장 유지:anyOf사용 시에도strict모드를 켜야 100% 준수 보장.- 토큰 비용 주의: 복잡한 스키마는 시스템 프롬프트 토큰을 늘릴 수 있으므로 첫 배포 전 토큰 수 측정 권장.
- SDK 버전 확인:
openai-python >= 1.78,openai-node >= 4.95이상에서parse()헬퍼가 v2 스키마를 자동 인식.