OpenAI, Structured Outputs v2 정식 출시—스키마 복잡도 제한 대폭 완화

무엇이 바뀌었나

OpenAI Structured Outputs v1은 JSON Schema의 $ref 재귀 참조와 anyOf 유니온 타입을 지원하지 않아, 실무에서 복잡한 도메인 모델을 다룰 때 스키마를 단순화하거나 응답 후 수동 파싱 단계를 추가해야 했다. v2는 다음 제약을 공식 해제했다.

• 재귀적 $ref: 트리 구조, 중첩 코멘트, AST 같은 자기 참조 스키마 직접 사용 가능
• anyOf / oneOf 유니온: 최대 5개 브랜치 허용, 각 브랜치에 독립 required 지정 가능
• 최대 뎁스: 기존 5단계 → 10단계로 확대
• 배열 내 객체 다형성: 동일 배열 내 서로 다른 타입 객체 혼재 허용

모델별 지원 현황 및 가격

| 모델 | Structured Outputs v2 | 비고 | |---|---|---| | gpt-4.1 | ✅ GA | 공식 페이지 참조 | | gpt-4.1-mini | ✅ GA | 공식 페이지 참조 | | gpt-4.1-nano | ✅ GA | 공식 페이지 참조 | | o3 | ✅ GA | 공식 페이지 참조 | | o4-mini | ✅ GA | 공식 페이지 참조 |

추가 토큰 비용은 없으며 기존 Chat Completions 요금 체계 그대로 적용된다. response_format 파라미터에 type: "json_schema"를 지정하는 방식은 동일하다.

한국 개발자 실전 적용 포인트

전자세금계산서·계약서 파싱 시나리오에서 효과가 크다. 예를 들어 공급자·수급자 정보가 중첩되고, 품목 배열 내 각 항목이 일반품목 | 할인품목 | 면세품목 유니온을 가지는 스키마를 v1에서는 플래트닝해야 했지만, v2에서는 도메인 모델 그대로 스키마를 작성할 수 있다.

# v2 유니온 스키마 예시 (간략)
schema = {
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "anyOf": [
          {"$ref": "#/$defs/StandardItem"},
          {"$ref": "#/$defs/DiscountItem"},
          {"$ref": "#/$defs/TaxExemptItem"}
        ]
      }
    }
  }
}

마이그레이션 주의사항: additionalProperties 는 여전히 false 고정이며, 스키마 총 토큰이 1,000 토큰을 초과하면 첫 요청 시 컴파일 지연이 발생할 수 있다. OpenAI 공식 문서의 Schema Caching 가이드를 참고해 동일 스키마를 재사용하면 지연을 회피할 수 있다.