SpringAI는 ChatClient, Advisors, Prompt, Model, Structured Output을 통해 AI 대화 흐름을 스프링 방식으로 구성하게 해주는 프레임워크이다. 대화, RAG, 객체 변환까지 백엔드 로직 안에서 일관되게 처리할 수 있다.

SpringAI 구성요소

ChatClient

• AI 대화의 시작과 끝을 관리하는 컨트롤러 역할

@RestController
class MyController {
	
	private final ChatClient chatClient;
	
	public MyController(ChatClient.Builder chatClientBuilder) {
		this.chatClient = chatClientBuilder.build();
	}
	
	@GetMapping("/ai")
	String generation(String userInput) {
		return this.chatClient
			.prompt() // prompt() 메서드를 시작으로 전체 대화 과정을 제어
			.user(userInput)
			.call()
			.content();
	}
}

• AI 모델과 대화를 주고받는 모든 과정을 총괄하고 제어하는 최상위 핵심 인터페이스
• ChatClient는 대화 파이프라인을 스프링에서 쉽게 관리하기 위해 제작됨
• 대화 기록을 기억해야 하거나 사내 데이터 추가, AI 답변을 자바 객체로 변환하는 등 수많은 전후 처리 작업 가능

Advisors

• 스프링 웹 개발 시 인터셉터, 필터 등의 역할과 동일
• 유저가 보낸 질문이 AI 모델로 넘어가기 직전, 중간에 개입하여 질문을 가공하거나 필요한 배경지식(Context)을 주입함
• 주로 이전 대화 기록을 불러와 질문에 붙여주거나, Vector DB 관련 문서를 찾아와 참고 자료로 결합해주는 역할을 수행

ChatMemory chatMemory = ...
VectorStore vectorStore = ...

var chatClient = ChatClient.builder(chatModel)
	.defaultAdvisors(
		MessageChatMemoryAdvisor.builder(chatMemory).build(), // chat memory
		QuestionAnswerAdvisor.builder(vectorStore).build() // RAG
	)
	.build();
	
var converationId = "123";

String response = this.chatClient.prompt()
	.advisors(advisor -> advisor.param(ChatMemory.CONVERSATION_ID, converstionId))
	.user("지난번에 물어본 장소의 날씨 다시 알려줘")
	.call()
	.content();

Prompts

• 최종 프롬프트 생성
• Advisor가 수집한 배경지식과 유저가 처음 입력한 내용을 결합하여, AI 모델이 완벽하게 이해할 수 있는 최종 프롬프트를 완성하는 단계
• SpringAI에서 AI MODEL에 전달되는 데이터의 형태는 문자열이 아니라 Prompt라는 전용 객체

Prompt 객체 내부 구조

• List<Message> : 대화의 맥락을 구성하는 여러 종류의 메시지 묶음
• ChatOptions : 온도, 사용할 모델명과 같은 AI 실행 옵션

Message Type

Prompt 안에 담기는 Message는 역할에 따라 4가지 타입이 존재한다.

1. SYSTEM
   • AI의 성격, 직업, 행동 지침, 제약 사항 등을 설정하는 메시지
   • "당신은 10년차 자바 개발자이다. 모든 답변은 마크다운으로 출력해줘"
2. USER
   • 실제 서비스를 사용하는 유저가 입력한 질문이나 지시 내용
   • "SpringAI에서 ChatClient가 뭐야?"
3. ASSISTANT
   • AI가 이전에 대답했던 응답 내용을 챗봇이 기억하고 이어가기 위해 ChatMemory에 덧붙이는 메시지
4. TOOL
   • AI가 외부 API나 함수를 호출하고 돌아온 결과값을 담는 특수 메시지

PromptTemplate

유저의 질문 구조는 고정되어 있지 않다. 유저의 입력값에 따라 질문 내용이 매번 바뀌어야 하므로 PromptTemplate을 사용한다. 자바 웹 개발시 사용하는 타임리프처럼 프롬프트 중간에 구멍({변수명})을 뚫어놓고 실행 시점에 값을 채워 넣는 기능이다.

• 비즈니스 로직과 프롬프트 문구 분리로 유지보수성 증가

// 1. 구멍이 뚫려 있는 템플릿 문자열 준비
String templateText = "초보자를 위해 {topic}의 핵심 개념을 3줄로 요약해줘";
PromptTemplate promptTemplate = new PromptTemplate(templateText);

// 2. 런타임 변수 값을 MAP으로 매핑하여 완전한 Prompt 객체 생성
Map<String, Object> variables = Map.of("topic", "SpringAI의 PromptTemplate");
Prompt prompt = promptTemplate.create(variables);

// 3. AI 모델에 전달
ChatResponse response = chatModel.call(prompt);

Models

• AI 모델 실행 인터페이스
• 완성된 최종 프롬프트를 실제 외부 AI API에 던져 답변을 받음
• 이 단계에서 설정에 따라 데이터를 한 번에 통째로 받을지, 글자 단위 실시간 스트리밍으로 받을지 응답 규격이 결정됨
• application.yml과 같은 설정 파일에서 API 키와 의존성 라이브러리만 교체하여 사용 가능

중요한 4가지 Model 타입

AI가 처리할 수 있는 데이터의 형태에 따라 인터페이스가 나누어져 있다.

1. ChatModel
   • 텍스트 대화 엔진
   • 텍스트를 입력받아 텍스트를 반환하는 모델
2. EmbeddingModel
   • Vector 변환 엔진
   • RAG 시스템의 핵심
   • 텍스트를 입력받아 Vector DB에 저장할 수 있도록 숫자 배열로 변환해주는 모델
3. ImageModel
   • 이미지 생성 엔진
   • 텍스트 프롬프트를 입력받아 이미지 생성
4. AudioModel
   • 음성 처리 엔진
   • 음성을 텍스트로 변환하거나, 텍스트를 음성으로 변환하는 모델

위 4가지 타입 외에도 더 있으니 참고!

Structured Output

• 후처리 및 객체 변환
• AI 모델이 뱉어낸 줄글 형태의 텍스트 답변을 받아, 백엔드 로직에서 즉시 사용할 수 있도록 정해진 자바 객체나 JSON 규격으로 자동 파싱해주는 변환 단계

동작 방식

1. 프롬프트 주입 방식
   • 프롬프트 마지막에 JSON 스키마 규격에 맞춰 응답이라는 지시문을 합성하여 보내는 방식
   • 구형 모델이나 JSON 모드를 켜는 API가 없는 모델에서도 범용적으로 사용 가능
2. Built-in JSON Mode
   • API 호출 시 response_format: {type : "json_object"}라는 JSON 전용 하드웨어 스위치를 켜서 사용하는 방식
   • OpenAI 등 이 기능을 지원하는 특정 LLM 모델에서만 사용 가능
   • 응답을 원하는 형태로 100% 강제할 수 있어 변환 실패율이 0에 수렴