Spring AI Structured Output이란 무엇일까?

블로그 후기 멘토진

← 블로그 목록으로 돌아가기

author

JSCODE 시니

category

Spring AI

createdAt

Jun 13, 2026 09:50 AM

isPublic

isPublic

series

실무에 바로 적용하는 Spring AI: Spring 서비스에 챗봇·RAG·MCP 도입하기

slug

understanding-spring-ai-structured-output

type

post

updatedAt

✅ 1. Spring AI Structured Output이란 무엇일까?

AI 모델이 뱉어내는 예측 불가능한 문자열(String) 형태의 답변을, 백엔드 서버가 즉시 사용할 수 있는 정형화된 데이터 규격(JSON, 자바 객체, 리스트 등)으로 강제하고 변환해주는 프레임워크 지원 기능

AI의 답변을 문자열로 받게 되면, 프론트엔드나 모바일 앱에서 해당 문자열을 쪼개고 파싱하는 정규식 코드를 직접 작성해야 함

Structured Output 기능을 사용하면, 백엔드 로직은 AI의 응답을 String이 아닌 처음부터 자바 DTO나 List<String> 같은 깔끔한 객체 형태로 바로 건네받을 수 있음.

✅ 2. 동작 방식

Spring AI는 AI 모델의 지원 여부에 따라 두 가지 방식으로 응답을 구조화(Converter)함.

프롬프트 주입 방식

프롬프트의 맨 마지막에 ‘JSON 스키마 규격에 맞춰서 응답해라’ 라는 지시문을 합성하여 보내는 소프트웨어적 방식
구형 모델이나 JSON 모드를 켜는 API가 없는 모델에서도 범용적으로 사용 가능함

Built-in JSON Mode

API 호출 시 아예 response_format: { type: "json_object" }라는 JSON 전용 하드웨어 스위치를 켜서 사용하는 방식
OpenAI(GPT-4) 등 이 기능을 지원하는 특정 LLM 모델에서만 사용 가능함.
응답을 원하는 형태로 100% 강제할 수 있어 변환 실패율이 0에 수렴함

✅ 3. 3가지 핵심 컨버터

Spring AI는 실무에서 자주 쓰이는 데이터 형태를 위해 3가지 기본 컨버터를 지원함.

BeanOutputConverter<T>

AI의 답변을 개발자가 직접 만든 커스텀 자바 클래스(DTO 또는 Record)로 변환함.

ListOutputConverter

답변을 단순한 List<String> 형태로 반환함.

MapOutputConverter

답변을 Map<String, Object> 형태의 키-값 쌍으로 반환함.