핵심 요약
OpenAI Structured Outputs는 JSON Schema에 맞는 출력을 생성하기 위해 설계되었으나, 실제 애플리케이션에서는 거절 응답, 생성 미완료 응답, 형식은 맞으나 내용이 틀린 결과를 별도로 처리해야 한다. 단순한 JSON 파싱 성공을 최종 처리 성공으로 오해하지 않도록 하는 것이 중요하며, 거절 상태는 별도의 처리와 저장 체계를 갖추어야 한다.
비교 및 절차 체크리스트
| 처리 단계 | 설명 | 권고사항 |
|---|---|---|
| 1. API 오류 및 완료 상태 확인 | API 호출 성공 여부와 finish_reason 등 전송 상태 점검 | 오류 및 미완료 상태는 후속 작업 수행 금지 |
| 2. 거절 응답 분기 | 응답 content 유형이 refusal인지 판별 | 거절 데이터는 정상 데이터와 분리 보관 |
| 3. JSON Schema 검증 | 응답이 스키마에 대한 형식 검증 통과 여부 확인 | 스키마 오류는 재시도보다 스키마 수정 우선 적용 |
| 4. 업무 내용 검증 | 날짜, 가격 등 필드값의 업무적 적합성 및 원자료와 대조 | 값의 진위 및 비즈니스 로직 조건 검증 수행 |
| 5. 최종 저장 및 후속 작업 | 검증된 정상 데이터만 저장 및 이메일 발송, 결제 등 외부 동작 실행 | 불완전 데이터 및 오류 데이터는 저장 및 후속 처리 금지 |
실무 유의점
- JSON 출력은 문법적 유효성과 스키마 준수가 별개임을 인지해야 한다.
- Responses API의 'text.format' 모드를 사용하는 경우 루트 객체 지정, 필수 필드 선언, additionalProperties 제한 등이 스키마 요구사항이다.
- 모델이 안전 검사로 거절한 응답은 단순 빈 데이터 처리 시 실제 결과 부재를 간과할 수 있다. 거절 메시지를 별도 상태로 관리해야 한다.
- 출력 토큰 한도 초과 등으로 인한 생성 중단은 불완전 응답을 초래하므로, API 완료 상태를 반드시 확인한 후에 데이터를 처리해야 한다.
- 내용 검증 과정에서는 단순 형식뿐 아니라 업무상 의미상 오류 여부를 확인해야 한다. 예를 들어 분류 작업에서 허용된 분류인지 검증한다.
- 스트리밍 응답 시 중단된 조각을 최종 결과로 처리하지 않고, 완료된 응답을 기준으로 후속 처리를 결정해야 한다.
- 자동 재시도 구현 시에는 오류, 거절, 불완전 응답 각각에 따른 적절한 재처리 경로를 설계하고, 중복 외부 동작이 발생하지 않도록 상태 구분이 필요하다.