1. 들어가며: 왜 굳이 Spring AI를 사용할까?
최근 Google AI Studio 등을 통해 제미나이(Gemini) API를 테스트해 보면, 웹 플레이그라운드에서는 몇 번의 클릭만으로 훌륭한 결과를 얻을 수 있습니다. 하지만 이를 실제 스프링 부트(Spring Boot) 애플리케이션에 통합하려고 Get code 버튼을 눌러보면 생각보다 복잡한 JSON 페이로드(contents, parts, generationConfig 등)와 마주하게 됩니다.
만약 WebClient나 RestClient로 이를 직접 호출한다면 다음과 같은 문제가 발생합니다.
- 벤더 종속성: OpenAI에서 Google Gemini로 모델을 변경할 때 요청/응답 DTO와 파싱 로직을 전면 재작성해야 합니다.
- 비정형 응답 처리의 고통: LLM이 반환한 문자열에서 JSON 블록만 정규식으로 발라내고 역직렬화하는 보일러플레이트 코드가 양산됩니다.
- 부가 기능 결합의 어려움: 이전 대화 맥락 유지(Multi-turn), 프롬프트 감사 로깅, 사내 문서 검색(RAG) 로직이 비즈니스 서비스 코드와 강하게 뒤엉킵니다.
Spring AI는 이러한 문제를 해결하기 위해 등장했습니다. 우리가 JdbcTemplate이나 Spring Data JPA를 통해 DB 벤더에 상관없이 일관된 데이터 접근 계층을 구성하듯, AI 모델 연동 영역에 스프링다운 추상화 계층을 제공합니다.
2. Spring AI 전체 아키텍처 및 기존 스프링 개념과의 비교
Spring AI의 내부 구성은 완전히 새로운 개념이 아닙니다. 기존 스프링 생태계에 익숙한 개발자라면 평소 다루던 컴포넌트와 1:1로 매핑하여 직관적으로 이해할 수 있습니다.
전체 아키텍처 계층 흐름
[ Application Layer (Controller / Service) ]
│
▼ 1. Fluent API 호출 (.prompt().user().call())
[ ChatClient ] ◄──► [ Structured Output Converter ] (Java Record 자동 변환)
│
▼ 2. 요청/응답 가로채기 및 문맥 보강 (Interceptor 체인)
[ Advisor Chain ]
├─ MessageChatMemoryAdvisor (이전 대화 조회 및 저장)
├─ QuestionAnswerAdvisor (VectorStore 기반 문서 검색 및 주입 - RAG)
└─ SimpleLoggerAdvisor (프롬프트 및 토큰 사용량 로깅)
│
▼ 3. 표준 모델 인터페이스 호출 (PSA)
[ ChatModel / EmbeddingModel ]
├─ @Tool (자바 서비스 메서드 직접 호출)
└─ VectorStore ◄── ETL Pipeline (DocumentReader -> Transformer -> Writer)
│
▼ 4. 외부 AI 공급자 HTTP 통신
[ Google Gemini / OpenAI / Anthropic / Ollama ]
핵심 구성요소 비교표
| 기능 영역 | Spring AI 핵심 컴포넌트 | 대응되는 기존 스프링 개념 | 주요 역할 및 실행 흐름에서의 책임 |
| 호출 진입점 | ChatClient | RestClient / WebClient | 개발자가 직접 호출하는 Fluent API. 프롬프트 조립 및 응답 타입 지정을 담당합니다. |
| 모델 추상화 | ChatModel, EmbeddingModel | DataSource / JdbcTemplate | 제미나이, OpenAI 등 벤더별 HTTP API 스펙 차이를 숨기는 표준 인터페이스(PSA)입니다. |
| 출력 변환 | StructuredOutputConverter | Jackson ObjectMapper | 프롬프트에 JSON 스키마 지시문을 자동 주입하고, LLM 응답을 Java record로 역직렬화합니다. |
| 가로채기/확장 | Advisor API | Filter / HandlerInterceptor | 요청 전후를 가로채 대화 기억(ChatMemory) 주입, RAG 문서 결합, 로깅 등을 체인 형태로 처리합니다. |
| 외부 데이터 연동 | VectorStore, ETL Pipeline | Spring Data Repository, Spring Batch | 문서를 읽고 분할(TokenTextSplitter)하여 벡터 DB에 적재하거나 유사도 검색을 수행합니다. |
3. 코드로 보는 Spring AI 핵심 구성 연결 (Google Gemini 기준)
실제 Spring Boot 3.x 환경에서 위 아키텍처의 핵심 요소(ChatClient, Advisor, Structured Output)가 어떻게 조립되어 동작하는지 살펴보겠습니다.
3.1. 의존성 및 application.yml 설정
Google AI Studio에서 발급받은 API 키를 환경변수(GEMINI_API_KEY)로 주입받아 설정합니다. 모델 추상화 계층 덕분에 코드 변경 없이 설정만으로 제미나이 모델을 지정할 수 있습니다.
spring:
ai:
google:
genai:
api-key: ${GEMINI_API_KEY}
chat:
options:
model: gemini-2.5-flash
temperature: 0.3 # 정형 데이터 추출 시에는 낮은 temperature 권장
3.2. ChatClient 조립 및 Structured Output 호출 예제
아래 코드는 사용자 질문을 받아 Advisor로 로깅 및 대화 기억을 처리하고, 최종 응답을 Java Record 객체로 즉시 변환해 반환하는 서비스 예제입니다.
package com.example.springai.service;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class ArchitectureGuideService {
private final ChatClient chatClient;
// 1. 정형화된 응답을 매핑할 불변 DTO (Java Record) 정의
public record TechReviewResponse(
String topic,
String coreSummary,
List<String> keyComponents,
String recommendedUseCase
) {}
// 2. ChatClient.Builder를 주입받아 공통 Advisor 체인 구성
public ArchitectureGuideService(ChatClient.Builder builder) {
this.chatClient = builder
.defaultSystem("당신은 엔터프라이즈 백엔드 및 아키텍처 전문가입니다. 핵심만 명확하게 답변하세요.")
.defaultAdvisors(
new MessageChatMemoryAdvisor(new InMemoryChatMemory()), // 멀티턴 대화 상태 유지
new SimpleLoggerAdvisor() // 실제 전송되는 프롬프트와 메타데이터 로깅
)
.build();
}
// 3. Fluent API를 통한 호출 및 자바 객체 자동 변환
// 주의: 외부 LLM HTTP 호출은 응답 지연이 길어질 수 있으므로 @Transactional을 선언하지 않습니다.
public TechReviewResponse analyzeComponent(String conversationId, String componentName) {
return chatClient.prompt()
.user(u -> u.text("{component}의 핵심 역할과 실무 활용처를 분석해 줘.")
.param("component", componentName))
.advisors(a -> a.param(MessageChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY, conversationId))
.call()
.entity(TechReviewResponse.class); // StructuredOutputConverter가 동작하는 지점
}
}
위 코드에서 .entity(TechReviewResponse.class)를 호출하면, Spring AI는 내부적으로 TechReviewResponse의 필드 구조를 JSON Schema로 변환하여 프롬프트 하단에 자동으로 덧붙여 전송합니다. 개발자가 프롬프트에 직접 JSON 포맷을 명시하고 파싱할 필요가 없습니다.
4. 실무 아키텍처 관점의 고려사항
튜토리얼 수준을 넘어 실제 운영 환경에 Spring AI 구성요소를 도입할 때는 데이터 흐름과 리소스 관리 측면에서 다음 4가지 포인트를 반드시 짚고 넘어가야 합니다.
① 외부 LLM 호출과 DB 트랜잭션 경계 분리 (Connection Pool 고갈 방지)
가장 흔히 범하는 실수 중 하나가 @Transactional이 선언된 서비스 메서드 내부에서 chatClient.prompt().call()을 동기 방식으로 호출하는 것입니다. LLM API 응답은 짧게는 1~2초에서 길게는 10초 이상 소요됩니다. 이 시간 동안 DB 커넥션을 물고 있으면 HikariCP 커넥션 풀이 순식간에 고갈되어 전체 시스템 장애로 이어집니다. 데이터 조회/저장과 외부 AI 호출의 트랜잭션 경계는 반드시 분리해야 합니다.
② Structured Output의 스키마 검증과 예외 처리
StructuredOutputConverter가 프롬프트에 JSON 스키마를 주입하더라도, 모델의 특성이나 토큰 잘림(Max Output Tokens 초과) 현상으로 인해 간혹 불완전한 JSON이 반환되어 역직렬화 예외가 발생할 수 있습니다. 따라서 핵심 데이터 파이프라인에 적용할 때는 RetryTemplate을 통한 재시도 정책이나 파싱 실패 시의 Fallback 처리가 필수적입니다.
③ ChatMemory의 영속화와 컨텍스트 윈도우 제어
예제에서 사용한 InMemoryChatMemory는 단일 서버 테스트용입니다. 다중 인스턴스(Scale-out) 환경에서는 Redis나 RDBMS 기반의 ChatMemory 구현체를 사용해야 하며, 대화가 길어질수록 누적 토큰 비용이 기하급수적으로 증가하므로 최근 N개의 메시지만 유지하는 윈도우 크기 제한(Window Size Limit)과 TTL 만료 정책을 함께 설계해야 합니다.
④ 감사 로깅(Audit)과 메타데이터 수집
SimpleLoggerAdvisor나 커스텀 Advisor를 활용하면 ChatResponseMetadata에서 요청당 소모된 프롬프트 토큰(Prompt Tokens)과 생성 토큰(Generation Tokens) 수치를 정확히 추출할 수 있습니다. 이를 별도의 이력 테이블이나 로그 저장소에 비동기로 적재해 두면, 추후 부서별/기능별 API 비용 산정과 프롬프트 품질 튜닝의 핵심 지표로 활용할 수 있습니다.
5. 마무리 및 도입 체크리스트
Spring AI는 단순히 AI API 호출 코드를 줄여주는 유틸리티가 아니라, 엔터프라이즈 환경에서 요구하는 확장성, 관측 가능성(Observability), 데이터 파이프라인 통합을 스프링 표준 방식으로 풀어낸 아키텍처 프레임워크입니다.
첫 프로젝트를 구성하며 블로그나 실무에 적용해 보실 때 아래 체크리스트를 기준으로 하나씩 검증해 보시기 바랍니다.
- [ ] 환경 변수 분리: API 키(GEMINI_API_KEY)가 코드나 Git 저장소에 노출되지 않고 환경변수 또는 외부 설정으로 안전하게 주입되었는가?
- [ ] 로깅 활성화: SimpleLoggerAdvisor와 로깅 레벨(logging.level.org.springframework.ai.chat.client.advisor=DEBUG)을 설정하여 실제 프롬프트 원문을 눈으로 확인했는가?
- [ ] 트랜잭션 분리: LLM 호출 구간이 DB @Transactional 범위 밖에 위치하도록 설계되었는가?
- [ ] 출력 타입 안전성: 단순 문자열 반환 대신 Java record와 .entity()를 활용해 응답 구조의 타입 안전성을 확보했는가?
'개발(Full) > Java & Spring' 카테고리의 다른 글
| [Spring AI] 백엔드 개발자의 시각에서 본 Spring AI: 내부 메커니즘(JPA 비유)과 실무 도입 시 반드시 알아야 할 함정들 (0) | 2026.11.14 |
|---|---|
| [Java/Spring] WebClient로 암호화 데이터 전송 시 '+' 기호 유실 문제 원인과 해결법 (URL Encoding의 함정) (0) | 2026.05.17 |
| Specification 패턴 : 복잡한 비즈니스 규칙을 조합 및 재사용하는 전략 (0) | 2025.05.11 |
| Adapter 패턴 : 호환되지 않는 인터페이스를 연결하는 설계 전략 (0) | 2025.05.11 |
| Strategy 패턴과 활용 사례: 로직 분기 문 줄이기 (0) | 2025.05.11 |
