쉽게 이해하기

모델이 자유롭게 문장을 쓰게 두면, 같은 요청에도 어떤 때는 설명 문장, 어떤 때는 JSON, 어떤 때는 빠진 필드가 섞여 나옵니다. 사람이 읽는 답변이라면 괜찮지만, 애플리케이션이 바로 파싱해야 하는 API 응답에서는 작은 형식 흔들림도 장애가 됩니다.

Structured Outputs는 이 문제를 “모델에게 신청서 양식을 채우게 하는 방식”으로 줄입니다. 개발자가 JSON Schema 같은 스키마로 name은 문자열, price는 숫자, category는 정해진 enum 중 하나처럼 계약을 정하면, 모델은 그 계약에 맞는 구조로 답하도록 제약됩니다. 중요한 점은 단순히 “JSON처럼 써줘”라고 프롬프트에 부탁하는 것이 아니라, API 요청 파라미터나 tool/function schema에 구조를 넘겨 모델 출력 경로 자체를 제한한다는 점입니다.

실무에서는 추출, 분류, UI 카드 생성, 워크플로 입력값 생성처럼 “다음 코드가 바로 읽어야 하는 답”에 특히 유용합니다. 다만 스키마가 너무 깊거나 제공자가 지원하지 않는 키워드를 쓰면 실패할 수 있으므로, 서버 측 검증과 폴백도 함께 설계해야 합니다.

비유와 예시

• 계약서 추출: 갱신 유형, 통지 기간, 관할 법을 정해진 필드로 뽑아 검토 UI에 바로 넣는다.
• 운영 로그 정리: host_id, severity, incidents[], timestamp 같은 필드로 사고 요약을 만든다.
• 대시보드 카드 생성: 카드 제목, 지표값, 추세 enum, 설명 문장을 배열 구조로 받아 프론트엔드에 바인딩한다.
• 고객 문의 분류: 문의를 billing, technical, refund 같은 enum으로 제한해 라우팅 오류를 줄인다.

한눈에 비교

방식	보장하는 것	보장하지 않는 것	적합한 상황
JSON mode	유효한 JSON 문법	필드/타입/enum 준수	가벼운 구조화
Structured Outputs	스키마 기반 필드와 타입	모든 제공자에서 모든 JSON Schema 키워드	파싱 안정성이 중요한 앱
Function/Tool Calling	도구 인자 스키마	사용자에게 보여줄 일반 답변 형식	실제 도구 실행
프롬프트만으로 JSON 요청	없음에 가까움	일관된 파싱 안정성	프로토타입

어디서 왜 중요한가

• 파서 실패와 재시도 비용을 줄여 백엔드 코드가 모델 답변을 더 안정적으로 소비할 수 있습니다.
• enum, required, additionalProperties 같은 계약을 쓰면 잘못된 라벨이나 불필요한 필드를 줄일 수 있습니다.
• 안전 정책상 응답을 거부해야 하는 경우에는 거부 흐름을 별도 처리해야 하므로, 앱의 오류 처리 설계가 더 명확해집니다.
• 여러 벤더를 함께 쓰는 경우 지원 키워드가 다르므로, 공통 스키마와 사후 검증 계층이 필요합니다.

자주 하는 오해

• ❌ 오해: JSON mode면 스키마까지 지킨다 → ✅ 실제: JSON mode는 주로 JSON 문법을 보장하고, 필드 계약은 별도 스키마 기능이 필요합니다.
• ❌ 오해: 스키마를 쓰면 검증 코드가 필요 없다 → ✅ 실제: 제공자별 한계, safety refusal, 네트워크 오류를 처리하려면 서버 검증과 폴백이 필요합니다.
• ❌ 오해: 스키마는 복잡할수록 좋다 → ✅ 실제: 깊은 중첩, 긴 enum, 많은 optional 필드는 실패율과 지연을 높일 수 있습니다.

대화에서는 이렇게

• "이 경로는 자유 텍스트 말고 json_schema로 고정합시다. 프론트가 바로 파싱해야 해요."
• "JSON mode가 아니라 strict schema가 필요합니다. enum 값이 흔들리면 라우팅이 깨집니다."
• "스키마가 너무 커서 400이 납니다. 필드명을 줄이고 중첩을 한 단계 낮추죠."
• "refusal이 오면 빈 JSON으로 처리하지 말고 사용자 안내 플로우로 분기합시다."

함께 읽으면 좋은 용어

• 기초
  JSON Schema — 필드, 타입, required, enum 같은 구조 계약의 기반입니다.
• 유사
  JSON mode — 유효 JSON에는 도움 되지만 스키마 준수와는 다릅니다.
• 유사
  Function Calling — 도구 실행 인자를 스키마로 제한하는 인접 기능입니다.
• 심화
  Constrained Decoding — 허용 가능한 토큰 집합을 줄여 구조를 강제하는 생성 방식입니다.
• 심화
  Pydantic/Zod — 코드의 타입 정의와 JSON Schema를 연결해 드리프트를 줄이는 도구입니다.