Structured Outputs와 JSON 응답 설계

자연어 응답은 사람이 읽기 좋다

AI 응답을 화면에 바로 보여 줄 때는 자연어가 편합니다. 사용자가 "이 글을 요약해 줘"라고 요청하면 모델은 문단 형태로 답하면 됩니다.

하지만 서비스 로직은 문장을 그대로 다루기 어렵습니다. 예를 들어 AI가 추천한 제목 5개를 저장하고, 태그를 검색 필터에 연결하고, 점수를 기준으로 정렬하려면 응답이 일정한 구조여야 합니다.

자연어 응답은 매번 조금씩 달라집니다. 어떤 날은 "제목:"이라고 쓰고, 어떤 날은 번호 목록으로 답합니다. 사람은 이해할 수 있지만 코드는 불안정해집니다.

그래서 AI 결과를 후속 로직에 연결하려면 "좋은 답변"보다 "예측 가능한 데이터"가 필요합니다.

AI 생성 이미지

JSON mode와 Structured Outputs의 차이

JSON mode는 모델이 유효한 JSON을 만들도록 돕습니다. 깨진 중괄호나 불필요한 설명 문장을 줄이는 데 유용합니다. 그러나 JSON mode는 "반드시 이 필드를 포함하라", "이 값은 배열이어야 한다", "각 배열 항목은 이런 구조여야 한다"까지 강하게 보장하지는 않습니다.

반면 Structured Outputs는 요청에 JSON Schema를 함께 전달해 모델의 출력 형식을 제한합니다. JSON Schema는 JSON 데이터의 설계도입니다. 필드명, 타입, 필수 여부, 배열 항목 구조를 미리 정의합니다. Microsoft 문서도 Structured Outputs를 JSON Schema를 따르는 응답이 필요할 때, 특히 구조화 데이터 추출·함수 호출·여러 단계 워크플로에 적합하다고 설명합니다.¹

간단히 구분하면 이렇습니다.

• 자연어 응답: 사람이 읽기 좋다.

• JSON mode: 유효한 JSON을 받는 데 도움이 된다.

• Structured Outputs: 정해진 스키마를 따르는 JSON을 받는 데 적합하다.

서비스 코드가 AI 응답을 바로 저장하거나 다음 API 호출의 입력으로 사용한다면 Structured Outputs를 우선 고려해야 합니다.

스키마는 계약서다

예를 들어 책 목차를 생성하는 기능을 만든다고 합시다. 화면에는 책 제목, 한 줄 소개, 챕터 목록이 필요합니다. 각 챕터에는 제목, 목표, 핵심 포인트 배열이 있어야 합니다.

이때 스키마는 다음 조건을 담아야 합니다.

• bookTitle: 문자열

• description: 문자열

• chapters: 배열

• 각 chapter: title, goal, keyPoints 포함

• keyPoints: 문자열 배열

• 불필요한 필드는 허용하지 않음

실무에서는 객체마다 additionalProperties: false를 두어 예상하지 않은 필드가 섞이지 않게 합니다. Structured Outputs에서는 모든 필드를 required에 포함하는 방식이 권장됩니다. 선택값이 필요하면 필드를 빼는 대신 string 또는 null처럼 null을 허용하는 타입으로 설계합니다.¹

스키마는 단순한 형식 지시가 아닙니다. 프론트엔드, 백엔드, 데이터베이스가 함께 따르는 계약서입니다.

서버 검증은 여전히 필요하다

Structured Outputs를 사용해도 모델 응답을 그대로 믿으면 안 됩니다. 서버는 한 번 더 확인해야 합니다.

검증할 항목은 명확합니다.

• 필수 필드가 모두 있는가

• 타입이 맞는가

• 배열이 비어 있지 않은가

• 점수나 등급이 허용 범위 안에 있는가

• 저장해도 되는 내용인가

검증에 성공하면 DB에 저장하고 화면에 렌더링합니다. 실패하면 재요청하거나, 사용자에게 "결과 생성에 실패했습니다. 다시 시도해 주세요."처럼 안전한 메시지를 보여 줍니다. 개발자 로그에는 검증 실패 이유를 남기되, API Key나 개인정보는 기록하지 않습니다.

중요한 원칙은 하나입니다. AI 응답은 입력값입니다. 사용자의 입력처럼 검증해야 합니다.

구조화 응답이 빛나는 순간

Structured Outputs는 다음 상황에서 특히 유용합니다.

문서에서 회사명, 날짜, 금액을 추출할 때. 사용자의 요청을 함수 호출 인자로 바꿀 때. 첫 번째 모델이 만든 결과를 두 번째 모델의 입력으로 넘길 때. 제목, 요약, 태그, 점수처럼 DB에 저장할 객체를 만들 때.

이런 기능에서는 "그럴듯한 문장"보다 "코드가 안정적으로 읽을 수 있는 값"이 중요합니다. AI가 만든 JSON은 화면 출력물이 아니라 서비스 데이터가 됩니다.

DB에는 결과만 저장하지 않는다

AI 결과를 저장할 때 최종 JSON만 남기면 나중에 문제를 추적하기 어렵습니다. 최소한 다음 정보를 함께 저장하는 것이 좋습니다.

• 원본 입력

• 검증된 JSON 결과

• 사용 모델

• 생성 시각

• 프롬프트 버전

• 스키마 버전

• 검증 상태

• 오류 메시지

스키마가 바뀌면 예전 결과와 새 결과의 구조가 달라질 수 있습니다. 그래서 스키마 버전은 중요합니다. 재처리, 디버깅, 품질 비교를 가능하게 하기 때문입니다.

실습 흐름: 책 목차 JSON 만들기

책 목차 생성 기능은 구조화 응답을 연습하기 좋습니다.

흐름은 이렇게 잡습니다.

1. 사용자가 책 주제와 대상 독자를 입력한다.

2. 서버가 입력 길이와 금지 내용을 검증한다.

3. 서버가 책 목차용 JSON Schema를 모델 호출에 포함한다.

4. 모델이 bookTitle, description, chapters 구조로 응답한다.

5. 서버가 스키마 검증을 다시 수행한다.

6. 검증된 JSON을 DB에 저장한다.

7. 같은 JSON으로 화면의 목차 UI를 렌더링한다.

이 구조를 만들면 AI 결과를 복사해서 붙여 넣을 필요가 없습니다. 모델이 만든 목차는 곧바로 카드 목록, 상세 페이지, 검색 인덱스, 후속 본문 생성 작업의 입력이 됩니다.

이 장의 핵심은 단순합니다. 사람이 읽는 AI 답변에서, 프로그램이 처리하는 AI 데이터로 넘어가야 합니다. 그 전환점에 JSON Schema와 Structured Outputs가 있습니다.

참고

¹Microsoft Learn - Structured outputs with Azure OpenAI