2026 OpenAI Structured Outputs: JSON Schema 안정 출력은 어떻게 할까?

JSON 형식만 반환하라는 지시로 파싱 오류가 반복된다면, OpenAI Structured Outputs와 엄격한 JSON Schema를 사용하고 애플리케이션 검증을 추가해야 합니다. 데이터베이스 입력이나 도구 실행처럼 실패 비용이 큰 경우에 특히 필요합니다.

이 글은 JSON mode를 교체하려는 개발자, 데이터 추출 파이프라인을 운영하는 팀, 도구 매개변수와 최종 응답 구조를 구분해야 하는 엔지니어를 위한 안내서입니다.

먼저 정해야 할 것: 모델이 아니라 소비자가 필요한 계약

구조화된 출력의 시작점은 프롬프트가 아닙니다. 결과를 받는 데이터베이스, 작업 큐, 도구 실행기가 실제로 요구하는 필드를 먼저 적어야 합니다. 예를 들어 고객 문의를 분류한다면 category, priority, summary를 분리하고, 설명 문장 전체를 하나의 문자열에 몰아넣지 않아야 합니다.

다음 항목을 문서로 고정하십시오.

• 반드시 있어야 하는 필드와 선택 필드
• 문자열, 숫자, 불리언 등 각 필드의 자료형
• 허용할 열거값과 대소문자 규칙
• 값이 없을 때 null을 허용할지, 빈 문자열을 허용할지
• 정의하지 않은 필드를 additionalProperties로 허용할지 여부
• 하위 시스템이 실제로 처리할 수 있는 최대 길이

여기서 중요한 구분이 있습니다. JSON mode는 JSON 문법에 초점을 두지만, OpenAI Structured Outputs는 선언한 JSON Schema 구조에 맞추는 데 초점을 둡니다. OpenAI의 공식 설명에서도 구조화된 결과를 위해 스키마와 엄격한 설정을 함께 사용하는 흐름을 설명합니다. Structured Outputs 공식 설명을 기준으로 현재 지원 범위를 다시 확인해야 합니다.

첫 단계: 작은 스키마로 시작하기

처음부터 중첩 객체, 여러 배열, 복잡한 조건부 구조를 모두 넣으면 어떤 부분에서 실패했는지 찾기 어렵습니다. 하위 시스템이 즉시 소비하는 핵심 필드만 먼저 만들고, 상세 정보는 다음 호출이나 별도 검증 단계로 분리하십시오.

장점은 명확합니다.

• 지원되지 않는 스키마 요소를 빠르게 찾을 수 있습니다.
• 응답을 저장하기 전에 실패 지점을 구분하기 쉽습니다.
• 스키마 변경이 데이터베이스와 작업 큐에 미치는 영향을 줄일 수 있습니다.

반대로 호출 횟수와 관리해야 할 계약이 늘어날 수 있습니다. 한 번의 응답으로 충분한 단순 추출까지 억지로 나눌 필요는 없습니다.

첫 호출에서 최종 응답과 도구 매개변수를 나누는 방법

Responses API를 사용할 때 최종 응답의 형식과 Function Calling 도구의 매개변수 스키마는 같은 위치에 넣지 않습니다. 최종 답변은 응답 형식 설정에서 정의하고, 도구 호출 인자는 함수 도구의 parameters에 정의합니다. 이 둘을 섞으면 모델이 반환할 결과와 도구에 전달할 인자의 계약이 불명확해집니다.

최종 응답의 최소 형태는 현재 공식 문서의 필드명을 확인한 뒤 다음과 같은 구조로 구성할 수 있습니다.

result = client.responses.create(
    model="현재 사용 가능한 모델",
    input="문의 내용을 분류합니다.",
    text={
        "format": {
            "type": "json_schema",
            "name": "ticket_result",
            "strict": True,
            "schema": ticket_schema
        }
    }
)

도구 호출은 별도 계약으로 둡니다.

tools = [{
    "type": "function",
    "name": "create_ticket",
    "description": "검증된 문의를 티켓으로 등록합니다.",
    "parameters": ticket_schema,
    "strict": True
}]

위 코드는 개념을 보여 주는 최소 예시입니다. 실제 배포 전에는 Responses API 빠른 시작 문서와 모델 인터페이스 문서에서 현재 모델과 요청 필드의 유효성을 확인하십시오. 오래된 대화형 API 예시를 Responses API 코드에 그대로 붙여 넣는 방식은 피해야 합니다.

응답을 받은 뒤에는 두 번 검증해야 합니다

스키마에 맞는 JSON을 받았다는 사실과 업무상 올바른 결과라는 사실은 다릅니다. 배포 코드에서는 다음 순서로 확인하십시오.

둘째 단계: 전송과 상태를 검사하기

먼저 API 호출 자체가 성공했는지 확인합니다. 응답에 거부가 있는지, 출력이 중단되었는지, 중단 원인이 길이 제한인지 확인해야 합니다. 스트리밍을 사용한다면 거부 델타와 종료 이벤트를 정상 텍스트처럼 합치지 마십시오. 관련 필드는 Responses API 거부 델타 참고 문서에 정리되어 있습니다.

처리 규칙은 다음처럼 나눌 수 있습니다.

• 정상 완료: JSON 파싱 후 업무 검증으로 이동합니다.
• 거부: 정상 데이터로 저장하지 않고 거부 상태로 기록합니다.
• 길이 중단: 부분 JSON을 복구하려 하지 말고 요청을 줄이거나 재처리합니다.
• 예상 밖 상태: 원문과 요청 식별자를 보존하고 재시도 정책을 적용합니다.

셋째 단계: 업무 의미를 검사하기

두 번째 검증에서는 JSON Schema 밖의 조건을 검사합니다.

• priority가 허용된 값인지 확인합니다.
• 시작일이 종료일보다 늦지 않은지 확인합니다.
• 식별자가 실제 데이터베이스에 존재하는지 확인합니다.
• 합계와 세부 항목의 계산 결과가 일치하는지 확인합니다.
• 도구 실행에 필요한 권한과 대상이 유효한지 확인합니다.

이 단계에서 실패하면 모델에게 무조건 재시도시키지 마십시오. 입력 오류, 모델의 판단 오류, 내부 자료 부족을 구분해야 합니다. 자동 재시도는 비용과 중복 실행 위험을 높일 수 있으므로, 읽기 전용 추출과 결제·삭제 같은 상태 변경 작업에 서로 다른 정책을 두는 편이 안전합니다.

실패 유형별로 복구 경로를 고정하기

Schema가 지원되지 않는다는 오류가 나오면 먼저 중첩 깊이와 복잡한 조건부 구조를 줄입니다. 필요하지 않은 선택 필드와 배열을 제거하고, 작은 계약으로 재현한 뒤 단계적으로 되돌리는 방식이 좋습니다.

컴파일 지연이 문제라면 요청마다 새로운 스키마를 만들지 말고, 동일한 스키마를 재사용하는 구조를 검토하십시오. 스키마의 이름과 버전도 요청 로그에 남겨야 합니다. 정확한 지연 특성과 지원 범위는 모델과 인터페이스 변경에 따라 달라질 수 있으므로, 고정된 수치를 전제로 운영하지 마십시오.

출력이 길이 제한에서 끝나면 입력을 줄이는 것만으로 해결되지 않을 수 있습니다. 출력 필드를 나누고, 불필요한 설명을 제거하며, 장문 원문은 별도 저장소에서 다루십시오. 잘린 JSON을 문자열 조작으로 이어 붙이는 방법은 데이터 손상을 숨깁니다.

거부는 파싱 실패와 다른 사건입니다. 거부 내용을 빈 객체로 바꾸면 운영 지표가 왜곡되고, 이후 Function Calling이 실행될 위험도 생깁니다. 안전한 재요청이 가능한지 판단한 뒤, 그렇지 않으면 사람의 검토 대기열로 보내십시오.

업무 검증 실패는 스키마를 더 엄격하게 만드는 것만으로 해결되지 않습니다. 외부 자료 조회, 규칙 엔진, 사람이 승인하는 단계를 추가해야 할 수 있습니다.

FAQ: JSON Schema와 엄격한 출력의 실제 적용

FAQ는 구현 중 자주 발생하는 혼동을 짧게 분리한 부분입니다. API 호출과 도구 호출을 함께 운영한다면 Function Calling 매개변수 검증 가이드와 연결되는 내부 안내도 함께 확인하는 편이 좋습니다.

넷째 단계: 회귀 샘플을 만든 뒤 배포하기

배포 전 테스트에는 정상 입력만 넣으면 안 됩니다. 다음 샘플을 고정하십시오.

• 일반적인 정상 입력
• 필수 정보가 빠진 입력
• 허용된 빈 값과 허용되지 않은 빈 값
• 매우 긴 원문
• 날짜와 숫자가 서로 충돌하는 입력
• 안전 정책에 따라 거부되어야 하는 입력

각 실행에는 모델 식별자, Responses API 사용 여부, Schema 버전, 애플리케이션 검증기 버전을 함께 기록하십시오. 그래야 모델이나 스키마가 바뀐 뒤 같은 실패를 재현할 수 있습니다. OpenAI의 엔드포인트별 데이터 제어 설명도 운영 전에 확인하여 입력과 출력의 보관 정책을 내부 기준과 맞추십시오.

회귀 검사는 결과가 JSON인지에만 점수를 주면 안 됩니다. 필수 필드 충족, 열거값 준수, 업무 규칙 통과, 거부 분류, 중단 분류를 각각 측정해야 합니다. 자동화 흐름에 연결된 경우에는 실제 도구를 실행하지 않는 모의 실행으로 먼저 검증하십시오.

다섯째 단계: Schema를 API 계약으로 버전 관리하기

Schema는 프롬프트에 붙이는 설정값이 아니라 하위 시스템과 공유하는 API 계약입니다. 필드를 삭제하거나 자료형을 바꾸는 변경은 새 버전으로 취급하고, 기존 소비자가 계속 읽을 수 있는지 확인해야 합니다.

운영 절차는 다음과 같이 구성할 수 있습니다.

• 스키마 파일과 검증기를 같은 저장소에서 관리합니다.
• 변경마다 정상·경계·거부 회귀 샘플을 다시 실행합니다.
• 새 버전은 일부 트래픽에서 먼저 확인합니다.
• 캐시된 스키마, 처리 지연, 데이터베이스 컬럼을 함께 점검합니다.
• 실패 응답을 이전 버전으로 조용히 변환하지 않습니다.

특히 도구 매개변수와 최종 응답 Schema를 같은 버전 번호로 관리하면 안 되는 경우가 많습니다. 도구는 실행기 계약이고, 최종 응답은 사용자나 저장 시스템의 계약이기 때문입니다.

어떤 출력 방식을 선택해야 하나요?

아래 표는 기능 이름보다 하위 시스템의 책임을 기준으로 선택하기 위한 도구입니다.

따라서 JSON mode를 단순히 교체하는 것이 목표라면, 먼저 현재 코드가 최종 응답을 받는지 도구 인자를 받는지 구분하십시오. 그다음 작은 Schema로 시작하고, 거부와 출력 중단을 정상 데이터와 다른 상태로 저장하십시오. 이 세 가지를 하지 않으면 strict: true를 켜도 운영 안정성이 생기지 않습니다.

로컬 개발 환경에서만 시험하면 긴 입력, 반복 호출, 스키마 버전 회귀를 충분히 돌리기 어려울 수 있습니다. 반대로 기존 Windows·Linux 환경이나 일반 클라우드 서버는 팀의 개발 도구와 원격 접속 방식에 따라 설정 차이가 생기고, 일시적인 테스트를 위해 고정 서버를 유지하면 사용하지 않는 시간의 비용과 권한 관리 부담이 남습니다. Mac 전용 개발 흐름을 검증하거나 여러 배치 테스트를 짧게 수행해야 한다면, kvmboot 맥 미니 렌탈 환경을 임시 테스트 노드로 비교해 볼 수 있습니다. 장기간의 지속적인 고부하 처리나 물리 인터페이스가 필요한 작업이라면 직접 장비를 보유하는 편이 더 적합합니다.

실제 도입 전에는 업무 데이터가 제거된 검수용 표본만으로 Schema, 거부, 중단, 의미 검증을 점검하십시오. 테스트 실행량이 갑자기 늘어나는 시기라면 고정 서버를 새로 사기보다 kvmboot 도움말 센터의 원격 접속 조건과 운영 절차를 확인한 뒤 임시 Mac 환경이 전체 비용과 관리 부담에 맞는지 판단하는 순서가 안전합니다.