JSON이 맞아도 AI는 틀릴 수 있다: 구조화된 출력과 에이전트 검증의 함정

 

구조화된 출력은 AI 응답을 미리 정한 JSON 스키마에 맞춰 프로그램이 처리하기 쉽게 만드는 기능이다. 필수 필드가 빠지거나 예상하지 못한 형식이 나오는 문제를 줄이는 데 유용하다. 그러나 JSON이 올바르다는 사실과 그 안의 날짜·금액·고객 번호가 사실이라는 것은 별개다.

 

환불 금액이 정수이고 고객 번호가 문자열이어도 다른 사람의 거래를 골랐거나 원문에 없는 금액을 만들어 냈다면 업무는 틀린다. 이 결과를 파싱에 성공했다는 이유만으로 바로 실행하면 오류가 데이터베이스와 외부 시스템까지 전달될 수 있다.

 

이 글은 Structured Outputs, JSON mode, JSON Schema, 함수 호출의 차이부터 Pydantic과 Zod, 불확실성 표현, 값과 근거 검증, 에이전트 실행 경계까지 정리한다. OpenAI·Google 공식 문서와 국내 구현 블로그 2건을 비교해 “구조화 성공”과 “업무 성공”을 구분하는 설계 기준을 살펴보자.

 

먼저 알아둘 핵심 요약

 

• 파싱 가능한 JSON, 스키마에 맞는 JSON, 사실이 맞는 데이터, 실행해도 되는 행동은 각각 다른 조건이다.

 

• 프롬프트로 형식을 요청하는 방법과 API의 스키마 제약 기능은 구분해야 한다.

 

• 모르는 값을 억지로 채우지 않도록 누락·불확실·상충 상태를 설계해야 한다.

 

• 모델의 거절, 응답 중단, 지원하지 않는 스키마 오류를 같은 파싱 실패로 처리하면 안 된다.

 

• 구조화된 도구 인자도 서버의 권한·현재 상태·중복 실행 검사를 통과해야 한다.

 

읽을 순서

 

① JSON과 구조화된 출력의 차이

② 국내 구현 사례와 공식 문서의 보장 범위

③ 스키마·누락값·근거·업무 규칙 설계

④ 도구 실행과 스트리밍·재시도·평가

⑤ 도입 체크리스트와 FAQ

 

 

1. “JSON으로 답해”와 Structured Outputs는 다르다

 

프롬프트에 “설명 없이 JSON으로만 답하라”고 쓰는 것은 모델에게 형식을 요청하는 방법이다. 예시를 주고 불필요한 문장을 금지하면 개선될 수 있지만 해당 요청만으로 API 수준의 스키마 제약이 생기는 것은 아니다. 출력 뒤에 설명이 붙거나 필드 이름이 달라지는 문제가 남을 수 있다.

 

JSON mode는 유효한 JSON 형식을 생성하도록 하는 기능이지만 특정 스키마의 모든 조건을 따르게 하는 기능과는 구분된다. JSON 객체로 파싱할 수 있어도 필요한 필드가 없거나 분류 값이 애플리케이션에서 기대한 목록과 다를 수 있다.

 

Structured Outputs는 지원하는 JSON Schema를 제공해 출력 구조를 제약하는 기능이다. OpenAI 공식 문서는 JSON mode와 달리 스키마 준수를 다루며 지원 가능한 스키마의 범위가 따로 있다고 설명한다.[1] 이름이 비슷해도 어떤 모드를 요청했는지 확인해야 한다.

 

라이브러리에서 객체로 변환해 주는 편의 함수도 실제로는 프롬프트에 형식 지시를 붙이는 방식일 수 있다. 함수 이름과 반환 타입만 보고 제공자 기능이 켜졌다고 가정하지 말고, 사용하는 버전의 요청 설정과 실제 전송 내용을 확인하는 편이 좋다.

 

2. 네 가지 검사를 통과해야 업무 데이터가 된다

 

첫 번째는 문법 검사다. 중괄호와 따옴표 등이 맞아 JSON으로 파싱할 수 있는지 확인한다. 두 번째는 구조 검사다. 필수 필드, 데이터 유형, 허용된 분류 값과 같은 스키마 조건을 따르는지 확인한다. 이 두 단계가 자동화의 입력을 안정시키는 기본이다.

 

 

세 번째는 의미와 사실 검사다. 추출한 날짜가 원문에 있는지, 금액의 단위와 통화가 맞는지, 선택한 고객 번호가 실제로 존재하는지 확인한다. 스키마에서 금액을 양의 정수로 제한해도 그 정수가 원문의 청구액인지까지 자동으로 증명하지는 못한다.

 

네 번째는 실행 허용 검사다. 그 고객의 거래를 현재 사용자가 바꿔도 되는지, 해당 주문이 취소 가능한 상태인지, 같은 환불을 이미 실행하지 않았는지 확인한다. 형식과 사실이 맞더라도 권한과 업무 상태가 맞지 않으면 실행하면 안 된다.

 

이 네 단계를 하나의 ‘유효성 검사’라는 말로 뭉치면 책임이 흐려진다. 어디까지 모델 제공자가 제약하고 어디부터 애플리케이션이 확인하는지 나눠야 한다. 한 단계의 통과가 다음 단계의 통과를 대신하지 않는다는 점이 중요하다.

 

3. 국내 기술 블로그에서 확인한 구현상의 교훈

 

뚜벅뚜벅코딩의 2026년 글은 OpenAI와 Gemini의 구조화된 응답 설정, JSON Schema, UI 위젯 데이터 반환 흐름을 소개한다.[2] 자연어 결과를 화면 구성과 연결하려면 정해진 데이터 구조가 필요하다는 문제의식을 이해하는 데 유용하다.

 

mingdodev의 2025년 Spring AI 글은 출력 형식이 흔들려 UI에 문제가 드러난 경험과 구조화된 출력 도입 과정을 설명한다. 특히 객체 변환 편의 기능과 제공자에게 스키마를 직접 전달하는 설정을 구분해 확인한 부분은 프레임워크를 사용할 때 참고할 만하다.[3]

 

다만 이들은 각 작성 시점의 모델과 라이브러리, 프로젝트에 관한 기록이다. 당시 예제의 API 필드와 모델 이름, Java SDK의 상태를 현재 모든 환경의 규칙으로 소개하면 안 된다. 오늘 사용하는 버전의 공식 문서와 실제 요청을 대조해야 한다.

 

 

또한 엄격한 형식 제약을 켰다고 잘못된 값과 환각이 모두 없어지는 것은 아니다. 안전상 거절을 모든 형식 오류의 결과로 설명해서도 안 된다. 구현 글에서 얻은 경험과 공식 문서의 보장 범위를 나눠 읽으면 과장 없이 적용할 수 있다.

 

4. 공식 문서도 값의 오류가 남는다고 설명한다

 

OpenAI 문서는 Structured Outputs에도 실수가 들어갈 수 있다고 명시한다. 입력이 스키마가 요구하는 작업과 전혀 관련 없는데도 모델이 구조를 채우려 하면 환각이 생길 수 있으므로, 처리 불가능한 입력에 어떻게 응답할지 지시하라고 안내한다.[1]

 

Google의 구조화된 출력 문서도 구문상 올바른 JSON이라도 애플리케이션에서 값을 검증해야 하며 의미적으로 잘못된 출력에 대한 오류 처리가 필요하다고 설명한다.[4] 형식을 안정화하는 기능과 내용 검증을 함께 설계해야 한다는 점에서 같은 방향이다.

 

스키마의 설명 필드는 모델이 값을 이해하는 데 도움이 될 수 있다. 하지만 “정확한 금액을 넣는다”는 설명을 썼다고 금액이 원문과 일치한다는 검증이 수행된 것은 아니다. 설명은 생성 방향을 안내하고 검증은 실제 조건을 확인한다.

 

같은 이유로 모델이 confidence를 0.99라고 적었다고 오류 확률이 1%라고 해석할 수 없다. 그 값이 실제 정답률과 어떻게 연결되는지 평가하지 않았다면 자기 보고 점수일 뿐이다. 실행 여부를 결정할 때는 검증 가능한 근거와 규칙이 필요하다.

 

5. 스키마는 후속 작업이 이해할 수 있게 작게 설계한다

 

처음부터 거대한 범용 객체 하나로 모든 업무를 표현하려 하면 필드 의미가 모호해지고 검증이 복잡해진다. 한 응답이 무엇을 전달하는지 먼저 정하자. 문서에서 정보를 추출하는 결과와 실제로 주문을 바꾸는 명령은 다른 계약을 가질 수 있다.

 

 

금액에는 통화와 단위를, 시각에는 기준 날짜와 시간대를 명확히 한다. 정수 100이 원인지 달러의 최소 단위인지, 문자열 “금요일”이 어떤 주의 금요일인지 결정되지 않으면 구조가 맞아도 후속 처리에서 해석이 갈릴 수 있다.

 

분류에는 정의된 값 목록을 사용할 수 있다. 다만 분류가 애매하거나 입력이 범위 밖일 때 어떤 값을 반환할지도 정해야 한다. 무조건 정상 분류 중 하나를 선택하게 하면 애매한 자료를 확신 있는 결과처럼 보이게 만들 수 있다.

 

필드 이름과 설명, 예시는 같은 의미를 전달해야 한다. total_amount라는 이름인데 설명에는 세금 제외 금액이라고 적혀 있으면 혼란이 생긴다. 스키마는 모델을 위한 힌트이자 후속 프로그램을 위한 데이터 계약이므로 사람이 읽어도 의미가 명확해야 한다.

 

6. 모르는 값을 표현할 자리가 없으면 빈칸이 거짓말이 된다

 

원문에 결제일이 없는데 스키마가 날짜 문자열을 반드시 요구하면 무엇을 넣어야 할까. 애플리케이션이 허용한 표현이 없으면 모델이 그럴듯한 값을 채울 유인이 생긴다. 필요한 키가 존재해야 한다는 조건과 실제 값이 확인됐다는 조건을 분리하는 것이 좋다.

 

지원 범위 안에서 null을 허용하고, 값이 없는 이유를 함께 표현하는 방법을 검토할 수 있다. 찾지 못함, 자료 간 상충, 현재 작업의 적용 대상 아님은 서로 다르다. 이 상태들을 모두 빈 문자열 하나로 표현하면 나중에 복구와 검토가 어려워진다.

 

OpenAI의 엄격한 스키마 규칙에서는 필드를 필수로 지정하면서 null과의 유니언으로 선택적인 값을 표현하는 방식이 설명돼 있다.[1] 다른 제공자가 동일한 규칙을 갖는다고 일반화해서는 안 된다. 필수 키와 null 허용의 의미를 현재 API 지원 범위에 맞춰 설계해야 한다.

 

 

누락값을 0으로 대체하는 방식도 조심하자. 금액을 찾지 못했다는 사실과 실제 금액이 0이라는 사실은 다르다. 후속 코드가 둘을 구분할 수 있도록 해야 잘못된 정산이나 통계 집계를 막을 수 있다.

 

7. 근거 필드는 추적을 돕지만 사실 보증서는 아니다

 

추출한 값에 원문 위치와 문서 식별자를 연결하면 검토가 쉬워진다. 예를 들어 총액을 추출한 경우 문서의 관련 구간과 해당 구간의 텍스트를 함께 남길 수 있다. 값만 저장한 결과보다 사람이 왜 그렇게 추출됐는지 살펴보기 좋다.

 

그러나 모델이 근거 문장 자체를 만들어 낼 수도 있다. 근거 필드를 추가했다는 사실만으로 검증이 끝나지 않는다. 인용 구간이 실제 원문에 존재하는지, 그 구간이 해당 값을 뒷받침하는지 애플리케이션이나 별도의 평가 과정에서 확인해야 한다.

 

페이지 번호나 문자 위치를 쓴다면 원문 버전과 추출 방식도 연결해야 한다. OCR 결과와 PDF 페이지의 표시가 다르거나 문서를 정규화하면서 위치가 바뀔 수 있다. 검토자가 같은 자료를 다시 찾을 수 있는 기준이 필요하다.

 

근거가 없는 항목은 검토 대상으로 남기는 편이 낫다. 모든 필드를 채우는 완전성 지표만 높이면 근거 없는 값을 감출 수 있다. 구조화된 추출의 품질은 채운 비율뿐 아니라 틀린 값과 적절하게 비워 둔 값을 함께 봐야 한다.

 

8. 업무 규칙은 필드 하나가 아니라 관계를 검사한다

 

스키마가 각 필드의 유형과 범위를 확인하더라도 업무 규칙은 여러 필드 사이의 관계를 다룬다. 시작일이 종료일보다 늦지 않은지, 품목별 금액과 총액이 정해진 계산 규칙에 맞는지, 통화가 서로 일치하는지 같은 조건이다.

 

 

이런 관계를 일부 스키마 기능으로 표현할 수 있는 경우도 있지만 제공자마다 지원하는 하위 집합과 제한이 다르다. 모든 검사를 생성 제약에 넣으려 하기보다 서버의 결정적인 코드로 확인할 조건을 분리하면 책임이 명확해진다.

 

가상의 영수증 추출 예시를 보자. 상품 금액과 세금, 할인, 최종 결제액이 각각 숫자로 출력돼도 이들이 합계 규칙과 맞는지 확인해야 한다. 반올림과 통화의 최소 단위도 정해야 한다. 단순한 숫자 일치가 어려운 경우에는 허용 오차의 근거가 필요하다.

 

업무 규칙 위반이 발견되면 바로 값을 고쳐 저장하지 말고 원문과 처리 정책을 확인한다. 총액을 맞추려고 할인 값을 임의로 바꾸면 검증 과정이 새로운 환각을 만들 수 있다. 수정한 값과 원래 추출값, 수정 근거를 구분할 필요가 있다.

 

9. Pydantic과 Zod는 타입 계약을 돕는 도구다

 

Pydantic과 Zod 같은 도구는 프로그램의 타입 정의와 JSON 스키마를 연결하고 파싱 결과를 다루는 데 유용하다. OpenAI와 Google의 공식 문서도 이러한 정의 방식을 소개한다.[1][4] 필드 이름과 타입을 여러 곳에 따로 적다가 어긋나는 문제를 줄일 수 있다.

 

다만 도구가 어떤 검사를 실제로 수행하는지 알아야 한다. 문자열을 숫자로 자동 변환하는지, 정의하지 않은 필드를 무시하는지, 사용자 정의 검증기가 실행되는지 설정에 따라 차이가 날 수 있다. 타입 객체를 얻었다는 사실만으로 원문과의 사실 대조가 이루어진 것은 아니다.

 

타입 정의에서 생성한 JSON Schema가 해당 API의 지원 범위 안에 있는지도 확인해야 한다. 일반적인 스키마에서 유효한 구조가 특정 모델의 제약 기능에서는 허용되지 않을 수 있다. SDK와 제공자 버전이 바뀌면 생성 결과를 확인하는 테스트가 유용하다.

 

 

가능하다면 스키마와 애플리케이션 타입의 기준을 하나로 관리하고 변경 시 호환성을 점검한다. OpenAI 문서도 둘이 서로 달라지지 않도록 SDK 도우미나 자동 생성, CI 검사를 권고한다.[1] 자동화가 계약의 의미를 대신 정의해 주지는 않지만 중복 정의에 따른 실수를 줄일 수 있다.

 

10. 거절·중단·스키마 오류는 서로 다른 상태다

 

모델이 안전상의 이유로 요청을 거절하면 정상적인 데이터 객체와 다른 응답 경로가 사용될 수 있다. OpenAI 문서는 refusal을 프로그램에서 감지할 수 있다고 설명한다.[1] 이 상태를 추출값이 비어 있는 정상 성공으로 처리하면 안 된다.

 

출력 길이 한계나 통신 중단으로 결과를 끝까지 받지 못한 경우도 있다. 그럴 때는 완성된 결과인지 먼저 확인하고, 현재 API와 SDK가 제공하는 종료 상태를 살펴봐야 한다. 일부 문자열을 파싱할 수 있다는 이유만으로 전체 요청이 성공했다고 판단하지 않는다.

 

지원하지 않는 스키마를 전달해 생기는 요청 오류는 또 다른 문제다. 이를 모델이 형식을 못 맞춘 것과 동일하게 처리하면 같은 잘못된 요청을 반복할 수 있다. 스키마 설정을 수정해야 하는지, 출력 예산을 조정해야 하는지, 실행을 중단해야 하는지를 구분한다.

 

예외 상태의 이름과 필드 위치는 API 종류와 버전에 따라 다를 수 있다. 과거 Chat Completions 예제를 현재 Responses API에 그대로 붙이기보다 사용하는 경로의 문서를 확인하자. 제품에는 내부 예외 전체보다 사용자에게 필요한 상태와 복구 방법을 명확히 보여주는 것이 좋다.

 

11. 스트리밍된 필드를 보고 즉시 결제하면 안 되는 이유

 

 

구조화된 출력을 스트리밍하면 생성 중인 내용을 화면에 단계적으로 보여줄 수 있다. Google 문서는 여러 청크를 연결해 최종 JSON 객체를 형성하는 방식을 설명하고, OpenAI도 SDK를 이용한 스트리밍 처리를 안내한다.[1][4]

 

그러나 화면에 일부 값을 보여주는 일과 외부 효과를 실행하는 일은 다르다. 중간에 수신자와 금액이 나타났더라도 최종 응답이 정상 완료됐는지, 필요한 필드가 모두 있는지, 업무 관계가 맞는지는 아직 확인되지 않았을 수 있다.

 

실행이 필요한 작업은 정해진 완료 상태를 확인하고 전체 검증을 거친 뒤 처리해야 한다. 중간 결과로 임시 UI를 표시한다면 아직 확정되지 않았다는 상태를 표현할 수 있다. 표시 속도를 높이는 최적화가 검증 단계를 건너뛰는 이유가 되어서는 안 된다.

 

가상의 배송 요청에서 주소 일부만 나온 시점에 발송 도구를 호출하면 나머지 주소가 빠질 수 있다. 어떤 필드를 언제 확정할 수 있는지는 업무 계약으로 정해야 한다. 스트리밍 파서가 작동한다는 사실과 업무가 실행 가능한 상태라는 사실을 분리한다.

 

12. 함수 호출 인자가 맞아도 실행 권한은 생기지 않는다

 

구조화된 최종 응답과 함수 호출은 사용 목적이 다르다. 전자는 UI나 후속 처리에 사용할 응답 형식을 정하는 데, 후자는 모델이 애플리케이션의 기능과 연결되도록 도구 이름과 인자를 제안하는 데 쓰인다. OpenAI와 Google 모두 이 구분을 설명한다.[1][4]

 

도구 인자를 엄격하게 제한하면 없는 필드를 보내거나 허용되지 않은 분류 값을 만드는 문제를 줄일 수 있다. 하지만 customer_id가 문자열이라는 조건을 통과해도 그 고객이 현재 사용자의 고객인지 확인해야 한다. 모델이 고른 식별자가 존재하는지도 별도의 조회 대상이다.

 

 

금액과 수신자가 형식상 올바르더라도 실행 계층은 현재 권한과 업무 상태를 검증해야 한다. 모델이 반환한 approved라는 값은 신뢰할 수 있는 승인 기록을 대신하지 못한다. 승인 상태는 애플리케이션이 관리하는 근거에서 읽어야 한다.

 

또한 같은 유효한 도구 호출을 두 번 실행하면 중복 효과가 생길 수 있다. 구조화된 출력은 멱등성 기능이 아니다. 업무 식별자와 처리 상태, 외부 결과 확인은 실행 계층에서 관리해야 한다. 형식 안정화와 행동 안전성은 서로 보완하는 설계다.

 

13. 실패한 출력을 다시 만들 때도 범위가 필요하다

 

검증에 실패한 결과를 다시 생성하도록 요청하는 방법은 유용할 수 있다. 누락한 필드나 위반한 규칙, 관련 원문을 함께 제공하면 수정의 방향이 분명해진다. 하지만 재시도할수록 항상 정답에 가까워진다는 보장은 없다.

 

원문에 정보가 없는 문제는 다시 생성한다고 해결되지 않는다. 모델이 같은 빈칸을 다른 추측으로 채울 수 있다. 이런 경우에는 불확실 상태를 반환하거나 추가 자료를 요청하는 것이 적절하다. 구조 문제와 정보 부족 문제를 구분해야 한다.

 

재시도 횟수와 전체 시간, 비용의 상한도 둔다. 오류 유형별로 복구할 수 있는 범위와 사람에게 넘길 기준을 정하면 무한 수정 루프를 줄일 수 있다. 외부 작업을 이미 실행했다면 출력 재생성과 같은 작업의 재실행을 연결하지 않도록 주의해야 한다.

 

형식이 틀린 JSON을 임의로 고치는 복구 로직도 의미를 바꾸지 않는지 확인한다. 필드 이름이나 숫자를 추측해 보완하는 수리가 업무 데이터를 조작하는 결과가 될 수 있다. 복구한 결과도 같은 검증을 통과해야 하며 원래 응답과 수정 기록을 추적할 수 있어야 한다.

 

14. 가상의 청구서 추출 파이프라인으로 살펴보자

 

 

다음은 실제 기업의 사고나 실험이 아닌 설계 예시다. 청구서에서 공급자, 발행일, 통화, 품목, 합계 금액을 추출해 검토 화면을 만드는 작업을 가정하자. 최종 목적은 예쁜 JSON을 얻는 것이 아니라 사람이 확인할 수 있는 정확한 업무 후보 데이터를 만드는 것이다.

 

먼저 필요한 필드와 단위, 원문에 없는 값의 표현을 정한다. 모델에는 추출과 추측을 구분하고 확인하지 못한 값을 임의로 완성하지 않도록 지시한다. 스키마에는 항목별 값과 상태, 필요하다면 근거 위치를 담을 수 있다.

 

응답을 받은 뒤 정상 완료와 거절·중단을 구분하고 파싱·구조 검사를 수행한다. 다음으로 원문 근거, 날짜와 통화, 합계 규칙을 대조한다. 공급자 식별이 필요한 경우에는 내부 목록과 조회해 확인한다. 이 단계까지는 실제 지급과 분리한다.

 

검토 화면에는 확인된 값과 확인이 필요한 항목을 다르게 보여줄 수 있다. 사용자가 수정했다면 원래 추출값과 수정값을 구분해 저장한다. 실제 지급 기능이 있다면 다시 권한과 승인, 현재 상태를 확인한 뒤 실행한다. 추출 성공이 곧 지급 승인이라는 연결을 만들지 않는다.

 

이렇게 단계를 나누면 실패 위치를 알 수 있다. JSON 형식은 안정적이지만 합계가 자주 틀린다면 의미 검증이나 원문 해석을 개선해야 한다. 원문 근거는 맞는데 고객 매핑이 틀리면 식별과 데이터 연결 단계를 살펴봐야 한다.

 

15. 구조 준수율과 사실 정확도를 따로 측정한다

 

테스트에서는 정상적인 문서뿐 아니라 정보 누락, 모호한 날짜, 서로 다른 통화, 상충하는 값, 관련 없는 입력을 포함한다. 문서가 길거나 OCR이 틀리는 상황도 업무에 존재한다면 평가 범위에 넣는다. 쉬운 예제 몇 건만으로 운영 품질을 판단하기 어렵다.

 

 

지표를 나눠 보면 문제가 선명해진다. 파싱 성공률과 스키마 준수율은 형식을, 필드별 정확도와 근거 일치율은 내용을, 업무 규칙 통과율과 최종 완료율은 후속 처리를 보여준다. 거절과 중단, 검토 필요 상태도 분모에서 조용히 빼지 말고 별도로 기록한다.

 

누락값을 올바르게 비워 두는지 확인하는 평가도 필요하다. 모든 필드를 채우는 모델이 더 좋아 보일 수 있지만 추측한 값을 많이 넣는다면 실제 품질은 낮다. 정확한 추출과 적절한 보류를 함께 평가해야 한다.

 

검증기가 얼마나 잘못 차단하는지도 본다. 정상 문서를 지나치게 검토 대상으로 보내면 사람의 작업량이 늘어난다. 비용과 지연, 재시도, 사람의 수정 시간까지 합쳐 성공한 업무 한 건당 부담을 비교하면 도입 효과를 판단하기 쉽다.

 

모델과 프롬프트, 스키마, 검증 규칙이 바뀌면 같은 평가 세트를 다시 확인한다. 스키마 변경은 필드 이름만의 문제가 아니라 하위 시스템과 데이터의 계약 변경이다. 새 필드를 처리하지 못하는 소비자가 있는지, 이전 결과와 어떤 버전으로 구분할지 점검해야 한다.

 

16. 운영 전에 답해야 할 체크리스트

 

• 프롬프트 형식 유도와 제공자의 스키마 제약을 구분했는가?

• 사용 모델·API·SDK가 지원하는 스키마 범위를 확인했는가?

• 필수 키와 실제로 확인된 값의 차이를 표현할 수 있는가?

• 날짜·시간대·통화·단위의 의미가 명확한가?

• 원문 근거와 값의 관계를 확인할 수 있는가?

• 필드 간 관계와 업무 규칙을 코드에서 검사하는가?

• 거절·중단·잘못된 스키마·정보 부족을 구분하는가?

• 스트리밍 중간 결과와 확정 실행을 분리했는가?

• 권한·승인·중복 효과 검사를 실행 계층이 담당하는가?

• 구조 준수율과 사실 정확도, 사람의 수정 시간을 따로 보는가?

 

 

구조화된 출력은 자연어 AI를 프로그램과 연결할 때 유용한 기반이다. 형식 문제에 쓰던 방어 코드를 줄이고 데이터 계약을 명확하게 만들 수 있다. 그렇지만 이후의 검증 책임이 없어지는 것은 아니다.

 

JSON이라는 그릇이 안정적이면 그 안의 값을 더 정교하게 검사할 수 있다. 그릇을 잘 만드는 일과 내용이 맞는지 확인하는 일을 함께 설계할 때 AI 자동화를 업무에 연결할 근거가 생긴다.

 

자주 묻는 질문

 

Q1. JSON mode와 Structured Outputs는 같은 기능인가요?

 

아니다. JSON mode는 유효한 JSON을 만드는 기능이고 구조화된 출력은 지원되는 스키마의 준수까지 다룬다. 사용하는 API와 모델이 어떤 기능을 지원하는지 확인해야 한다.

 

Q2. strict 설정을 켜면 환각도 없어지나요?

 

그렇지 않다. 구조와 허용 값을 제약해도 원문에 없는 사실을 넣거나 잘못된 항목을 선택할 수 있다. 근거와 업무 규칙을 별도로 검증해야 한다.

 

Q3. 모든 필드를 필수로 만들면 더 정확해지나요?

 

필드 누락을 줄일 수는 있지만 정보가 없는데도 값을 채우게 만들 수 있다. 키의 존재와 값의 확인 여부를 나누고, 지원 범위 안에서 null과 불확실 상태를 설계하는 편이 좋다.

 

Q4. Pydantic 검증을 통과하면 바로 저장해도 되나요?

 

수행한 검증의 범위에 달려 있다. 타입과 형식만 확인했다면 원문과의 일치나 업무 규칙 검사가 남는다. 저장이 외부 실행으로 이어지는 경우 권한과 현재 상태도 확인해야 한다.

 

Q5. 함수 호출 인자가 스키마에 맞으면 실행해도 되나요?

 

형식 통과만으로 실행 권한이 생기지는 않는다. 현재 사용자의 권한, 대상의 존재와 상태, 승인과 중복 실행 여부를 서버에서 검사해야 한다.

 

Q6. 가장 먼저 만들 평가 데이터는 무엇인가요?

 

 

대표 정상 입력과 함께 누락·상충·무관한 입력을 준비하는 것이 좋다. 필드별 정답과 보류해야 할 조건을 정하고, 형식 성공률과 내용 정확도를 따로 기록하면 개선 지점을 찾기 쉽다.

 

참고 자료와 확인 범위

 

[1] OpenAI API Documentation, Structured model outputs.

https://developers.openai.com/api/docs/guides/structured-outputs

Structured model outputs | OpenAI API

JSON mode와 스키마 준수의 차이, 거절과 오류 처리, 값의 실수 가능성, 스키마 지원 범위와 타입 정의 관리에 관한 설명을 확인했다.

 

[2] 뚜벅뚜벅코딩, [AI] 구조화된 출력(Structured Outputs)과 Gemini API를 통한 JSON Schema 데이터 반환, 2026.03.20.

https://tiptapcoding.tistory.com/entry/AI-Structured-Outputs구조화된-출력와-Gemini-API를-통한-구조화-데이터-반환

[AI] 구조화된 출력(Structured Outputs)과 Gemini API를 통한 JSON Schema 데이터 반환

UI 위젯과 API 응답을 연결하는 국내 구현 사례의 문제의식을 참고했다. 당시 예제의 모델·SDK·설정과 모든 공급자의 현재 보장을 동일시하지 않았다.

 

[3] mingdodev, [Spring AI] OpenAI ChatClient로 구조화된 출력(Structured Outputs) 사용하기, 2025.03.22.

https://mingdodev.github.io/blog/dev/2025-03-22-OpenAI-structred-outputs-with-Spring-AI/

[Spring AI] OpenAI ChatClient로 구조화된 출력(Structured Outputs) 사용하기

프롬프트 기반 형식 유도와 제공자 설정을 구분하는 구현상의 교훈을 참고했다. 당시 라이브러리의 지원 상태와 오류 해석은 현재 공식 문서로 다시 확인했다.

 

 

[4] Google AI for Developers, 구조화된 출력.

https://ai.google.dev/gemini-api/docs/structured-output

구조화된 출력  |  Gemini API  |  Google AI for Developers

스키마 하위 집합과 값 검증, 의미적 오류 처리, 스트리밍과 함수 호출의 구분을 확인했다. 열람 페이지의 최종 업데이트 표기는 2026.10.13이었다.

 

자료 확인일: 2026년 10월 18일. 청구서 처리 흐름과 체크리스트는 공개 자료를 바탕으로 구성한 가상 설계 예시이며 직접 수행한 벤치마크나 특정 기업의 실제 사고를 뜻하지 않는다.