• 목록

LLM의 답변을 JSON으로 받으면 프로그램이 읽기 쉬워지지만, 그 안의 값이 사실이거나 업무 규칙에 맞는다는 뜻은 아닙니다. 구조화 출력은 형식을 맞추는 문제와 값의 의미를 검증하는 문제를 구분해서 이해해야 합니다.

괄호가 맞는 JSON, 스키마에 맞는 객체, 원문과 일치하는 정보는 서로 다른 확인 단계입니다. 이 차이를 알면 출력이 정상인데 서비스 결과는 잘못되는 상황을 더 구체적으로 설명할 수 있습니다.

AI 생성 삽화 · 개념 이해를 위한 AI 연출 이미지이며 실제 시스템 구성도나 측정 결과가 아닙니다.

핵심 정리
파싱 성공, 스키마 통과, 의미 검증을 분리합니다. 구조화 출력의 지원 범위를 확인하고 원문 근거와 업무 조건은 애플리케이션에서 별도로 점검합니다.

1. JSON으로 읽힌다는 것부터 하나의 단계입니다

문자열을 JSON으로 파싱할 수 있다는 것은 문법에 맞게 해석할 수 있다는 뜻입니다. 원하는 필드가 들어 있는지나 값의 의미가 옳은지는 별도 질문입니다.

가상의 문서 분류 결과에 category와 summary라는 키가 필요하다고 해도, 빈 객체가 JSON 문법에 맞는다는 이유로 업무 결과를 완성한 것은 아닙니다. 학습용 흐름에서는 받은 원문 응답, 파싱한 객체, 다음 검증 결과를 각각 남겨 볼 수 있습니다.

이 구분 없이 성공 여부 하나만 기록하면 어떤 단계에서 문제가 생겼는지 알기 어렵습니다. 예시는 개념 설명용이며 실제 모델 응답이나 특정 SDK의 실행 결과로 제시하는 것이 아닙니다.

2. 스키마는 기대하는 구조를 표현합니다

JSON Schema의 공식 object 안내는 속성과 필수 속성, 추가 속성에 관한 규칙을 설명합니다. 타입 안내는 값의 종류를 구별하는 기반을 제공합니다.

이를 이용하면 특정 키가 있어야 한다거나 어떤 필드는 문자열이어야 한다는 기대를 표현할 수 있습니다. 다만 스키마에 어떤 규칙을 작성했는지가 중요합니다.

원하는 제약을 적지 않았는데 검증기가 알아서 업무 요구를 추론한다고 생각하지 않습니다. 가상의 분류 객체에서 category를 문자열로만 정했다면 문자열이라는 조건과 허용된 분류 중 하나라는 조건은 다릅니다.

개발자는 무엇을 필수로 확인할지 먼저 정하고 그 요구를 지원되는 스키마 기능으로 옮겨야 합니다.

3. 누락과 null, 빈 문자열은 같은 상태가 아닙니다

가상의 추출 작업에서 날짜를 찾지 못한 상황을 어떻게 표현할지 정해야 합니다. 필드가 없는 객체, 값이 null인 객체, 빈 문자열이 들어 있는 객체는 서로 다른 상태입니다.

JSON Schema의 객체와 타입 규칙도 이런 차이를 명시하는 데 사용됩니다. 어떤 표현을 사용할지는 서비스 계약과 소비 코드의 기대에 맞춰 정합니다.

모델에게 아무 설명 없이 맡기면 처리 코드가 여러 상태를 혼동할 수 있습니다. 값이 없을 때의 표현을 정했다고 실제 원문에 날짜가 없었다는 사실이 보장되는 것도 아닙니다.

원문에서 놓친 경우와 실제로 정보가 없는 경우를 어떻게 확인할지는 별도 검토가 필요합니다. 예외 상태의 의미를 문서에 함께 남기는 편이 좋습니다.

4. 스키마를 통과한 값도 틀릴 수 있습니다

Gemini의 구조화 출력 공식 안내는 형식이 맞더라도 애플리케이션에서 값을 검증하고 의미가 잘못된 출력의 오류 처리를 마련하도록 안내합니다. 가상의 문서에서 사람 이름을 문자열로 추출했다고 해도 다른 사람의 이름을 넣었다면 타입 검사는 이를 해결하지 못합니다.

이름이 실제 원문에 있는지, 해당 역할의 사람인지 같은 질문이 남습니다. 따라서 구조 검증을 사실 확인의 대체물로 사용하지 않습니다.

본문에 없는 정보를 추정했는지 확인할 근거를 함께 보관할 수 있도록 출력과 원문 위치의 관계를 설계하는 것이 좋습니다. 이 관계를 어떻게 검증할지는 데이터와 업무 목적에 따라 정하며 모든 서비스에 같은 절차를 강요할 수는 없습니다.

5. 업무 규칙은 필드 사이 관계를 포함합니다

가상의 일정 추출에서 시작일과 종료일이 각각 올바른 날짜 형태여도 종료가 시작보다 앞설 수 있습니다. 상품 분류에서 허용된 문자열을 반환했더라도 실제 내용과 맞지 않을 수 있습니다.

이처럼 개별 값의 형식과 여러 값 사이의 업무 관계는 다른 확인 대상입니다. 어떤 규칙을 스키마에서 표현할 수 있는지와 어떤 규칙을 애플리케이션 로직에서 확인할지는 사용하는 기능의 지원 범위를 봐야 합니다.

구조화 출력 기능이 JSON Schema 전체를 동일하게 지원한다고 가정하지 않습니다. 공식 제공자의 안내에서 지원하는 하위 집합과 제한을 확인하고 작성한 스키마가 실제 요청에서 받아들여지는지 검증합니다.

이 글에는 특정 API 버전에 맞춘 실행 코드를 제시하지 않습니다.

6. 실패 종류에 따라 다음 처리를 나눕니다

파싱 실패, 필수 속성 누락, 허용되지 않은 값, 원문 불일치는 서로 다른 실패입니다. 가상의 운영 기록에서 모두 모델 오류라고만 남기면 어떤 개선이 필요한지 찾기 어렵습니다.

입력 문제인지, 스키마 설계 문제인지, 추출의 의미 오류인지 조사할 수 있게 단계를 표시합니다. 다시 요청할지, 사용자가 확인할지, 결과를 보류할지는 업무 위험과 운영 조건에 맞게 정합니다.

같은 요청을 반복한다고 의미 오류가 항상 해결된다고 보장할 수는 없습니다. 자동 처리로 넘어가기 전에 어떤 조건을 통과해야 하는지 정의하고 실패한 결과를 성공 데이터에 섞지 않도록 설계합니다.

오류를 숨기고 기본값을 채우는 방식이 실제 요구에 맞는지도 별도로 확인해야 합니다.

7. 예제 데이터에는 정답과 애매한 사례를 함께 둡니다

가상의 테스트 묶음에는 정보가 명확한 문서뿐 아니라 날짜가 없는 문서, 여러 사람 이름이 있는 문서, 표기가 엇갈리는 문서도 포함할 수 있습니다. 각 사례에서 기대하는 출력과 보류 조건을 먼저 적습니다.

실제 응답을 받았다면 구조 검사 결과와 의미 검사 결과를 다른 열에 기록합니다. 이 글의 사례는 테스트 설계 예시이며 실행 성능이나 정확도를 측정한 결과가 아닙니다.

평가 자료를 정답처럼 쓰려면 그 자료의 기대값도 확인해야 합니다. 사람이 만든 예시라고 자동으로 오류가 없는 것은 아닙니다.

서비스에서 중요한 실패 유형이 빠져 있지 않은지 검토하고 단순히 JSON 생성 성공률만으로 전체 품질을 설명하지 않는 편이 좋습니다.

8. 구조화 출력과 도구 실행을 연결할 때 경계를 둡니다

답변이 정해진 구조를 가진다는 사실과 외부 작업을 수행할 권한이 있다는 사실은 다릅니다. 가상의 객체에 action이라는 필드가 있어도 그 문자열을 곧바로 실제 작업으로 실행해서는 안 됩니다.

허용된 작업인지, 필요한 조건이 충족되는지, 현재 요청자가 해당 작업을 요청할 수 있는지 애플리케이션이 확인할 항목이 있습니다. 이는 모든 응답을 위험하다고 보는 것이 아니라 데이터와 실행의 역할을 구분하는 설계입니다.

구조화 출력은 후속 프로그램이 읽기 쉬운 형태를 만드는 데 도움이 되지만 실행 결과까지 대신 보장하지 않습니다. 제공자의 문서에서도 응답 형식을 맞추는 기능과 도구 호출의 용도를 구별하므로 자신의 흐름에서 어느 단계에 쓰는지 설명하는 것이 좋습니다.

9. 자주 묻는 질문

Q1. JSON으로 받으면 환각이 없어지나요?

형식이 맞는 출력도 원문과 다른 값을 담을 수 있습니다. 구조 검증과 의미 검증을 분리하고 필요한 근거와 업무 조건을 별도로 확인해야 합니다.

Q2. 필수 필드면 값이 반드시 유효한가요?

필드의 존재와 값의 유효성은 다른 조건입니다. 타입과 허용 범위, 원문과의 일치 등 실제로 필요한 검사를 무엇으로 수행할지 정해야 합니다.

Q3. 모든 JSON Schema 기능을 그대로 사용할 수 있나요?

구조화 출력 제공자가 지원하는 범위를 확인해야 합니다. 지원 하위 집합이나 복잡도 제한이 있을 수 있으므로 공식 문서와 실제 요청 검증을 기준으로 구현합니다.

Q4. 스키마 검사 후 바로 외부 작업을 실행해도 되나요?

스키마 통과만으로 실행 권한이나 업무 조건이 확인되지는 않습니다. 데이터 해석과 실제 작업 실행을 나누고 애플리케이션의 허용 조건을 별도로 점검합니다.

참고 자료

• Gemini API — 구조화 출력과 검증 안내
• JSON Schema — 객체와 필수 속성
• JSON Schema — 타입별 키워드