왜 Structured Output인가
LLM은 본질적으로 텍스트를 입력받아 텍스트를 반환하는 시스템이다. 이 인터페이스는 사람과의 대화에는 자연스럽지만, 소프트웨어 내부에서는 치명적인 약점이 된다. 특정 필드로 라우팅하거나, DB에 값을 저장하거나, 조건 분기를 처리해야 하는 순간부터 '텍스트 덩어리'는 '레코드'가 되어야 한다.
Structured Output은 이 간극을 메운다. 모델이 스키마에 맞는 텍스트를 출력하도록 유도하고, 애플리케이션이 이를 타입이 있는 객체로 파싱해 나머지 코드베이스에서 일반 도메인 타입처럼 다룰 수 있게 한다. Spring AI는 초창기부터 ChatClient.call().entity(...)를 통해 이 기능을 지원해왔다.
Spring AI 2.0의 .entity() 사용법
기본 사용 패턴은 단순하다. 먼저 원하는 응답 형태를 Java record로 정의한다.
record ActorsFilms(String actor, List<String> movies) {}
그리고 .content() 대신 .entity(...)로 호출을 마무리하면, 원시 텍스트 대신 타입이 있는 객체가 반환된다.
ActorsFilms films = chatClient.prompt()
.user("Generate the filmography for a random actor.")
.call()
.entity(ActorsFilms.class);
System.out.println(films.actor()); // "Tom Hanks"
System.out.println(films.movies()); // ["Forrest Gump", "Cast Away", ...]
한 가지 중요한 제약이 있다. .entity(...)는 .call() 전용이다. 타입 파싱은 완전한 응답이 필요하기 때문에, 청크 단위로 텍스트를 반환하는 .stream() 경로에서는 사용할 수 없다. Class, ParameterizedTypeReference, 커스텀 컨버터 등 모든 변형에 동일하게 적용되는 원칙이다.
Spring AI 2.0이 추가한 두 가지 신뢰성 레이어
Spring AI 2.0은 기존 인터페이스를 유지하면서 두 가지 새로운 제어 축을 추가했다.
Provider-native structured output은 모델 제공자(OpenAI, Anthropic 등)가 API 수준에서 지원하는 스키마 강제 기능을 활용한다. 프롬프트 엔지니어링에만 의존하던 방식과 달리, API 자체가 응답 형식을 보장하므로 파싱 실패 가능성이 크게 줄어든다.
Self-correcting schema validation은 모델 응답이 스키마를 위반했을 때 자동으로 재시도 및 교정을 수행하는 메커니즘이다. 기존 코드는 변경 없이 동작하며, 이 두 기능은 옵션으로 추가 활성화하는 방식이다.
실무 관점에서 이 조합이 중요한 이유는 명확하다. LLM 기반 파이프라인에서 가장 흔한 장애 지점이 바로 비정형 응답으로 인한 파싱 예외다. 재시도 로직을 직접 구현하거나 응답 검증 코드를 별도로 작성하던 보일러플레이트가 프레임워크 레벨로 흡수된다. 4년차 이상 개발자라면 이런 신뢰성 레이어가 운영 환경에서 얼마나 큰 차이를 만드는지 직관적으로 이해할 것이다.
정리
.entity(ActorsFilms.class)패턴으로 LLM 응답을 타입 안전한 Java 객체로 직접 수신할 수 있으며,.stream()경로에서는 사용 불가- Spring AI 2.0은 provider-native structured output과 self-correcting validation을 추가해 파싱 신뢰성을 높였고, 기존 코드와의 하위 호환성을 유지
- LLM 응답 파싱 실패와 재시도 로직을 프레임워크가 흡수함으로써, 애플리케이션 레이어의 방어 코드 부담을 줄일 수 있다