[Spring AI 2025 Renewal #2] Chat Client API

안녕하세요 dev_writer입니다.

 

이번 시간에는 Spring AI 공식 문서 중 Chat Client API에 대한 내용을 번역한 내용을 전달해 드리겠습니다.

 

Chat Client API

ChatClient는 AI 모델과의 통신을 위한 유창한 (fluent) API를 제공합니다. 이 API는 동기 (synchronous) 방식과 스트리밍 (streaming) 방식의 프로그래밍 모델을 모두 지원합니다.

 

이 fluent API는 AI 모델에 입력으로 전달되는 Prompt를 구성하는 요소들을 단계적으로 조립할 수 있는 메서드를 제공합니다. Prompt는 AI 모델의 출력과 동작을 유도하기 위한 지시문 (instructional text)을 포함하며, API 관점에서 볼 때 Prompt는 메시지들의 집합으로 구성됩니다.

 

AI 모델은 주로 두 가지 유형의 메시지를 처리합니다: 사용자 메시지 (user message)와 시스템 메시지 (system messages)입니다. 사용자 메시지는 사용자가 직접 입력한 내용을 의미하고, 시스템 메시지는 대화의 흐름을 안내하기 위해 시스템에서 생성된 메시지입니다.

 

이러한 메시지들에는 종종 플레이스홀더 (placeholder)가 포함되어 있으며, 이는 실행 시점에 사용자 입력에 따라 대체되어 AI 모델의 응답을 사용자 맞춤형으로 조정하는 데 활용됩니다.

플레이스홀더 (placeholder)의 사용 예 중 일부인 PromptTemplate 에 대해 알고 싶으신 분들은 아래 글을 참고하시기 바랍니다.
- [Spring AI 🤖] Spring AI에서 프롬프트를 더욱 효과적으로 작성하는 방법 (feat. PromptTemplate) 

 

또한, 사용할 AI 모델의 이름이나 생성되는 응답의 무작위성 또는 창의성을 조절하는 temperature 설정과 같은 Prompt 옵션도 함께 지정할 수 있습니다.

 

ChatClient 생성하기

ChatClient는 ChatClient.Builder 객체를 통해 생성됩니다. Spring Boot의 자동 구성 기능을 사용하는 ChatModel에 대해 자동으로 구성된 ChatClient.Builder 인스턴스를 얻거나, 직접 프로그래밍 방식으로 생성할 수 있습니다.

 

자동 구성된 ChatClient.Builder 사용하기

가장 간단한 사용 사례에서는, Spring AI가 제공하는 Spring Boot 자동 구성 기능을 통해 ChatClient.Builder의 프로토타입 빈 (bean)이 자동으로 생성되며, 이를 여러분의 클래스에 주입하여 사용할 수 있습니다.

 

다음은 사용자의 간단한 요청에 대해 문자열 응답을 받는 예제입니다.

@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()
            .user(userInput)
            .call()
            .content();
    }
}

 

이 간단한 예제에서 사용자 입력은 user message의 내용을 설정합니다. call() 메서드는 AI 모델에 요청을 전송하며, content() 메서드는 AI 모델의 응답을 문자열 (String)로 반환합니다.

 

ChatClient를 프로그래밍 방식으로 생성하기

spring.ai.chat.client.enabled=false로 속성을 설정하면, ChatClient.Builder의 자동 구성을 비활성화할 수 있습니다. 이 방식은 여러 개의 챗 모델을 함께 사용하는 경우에 유용합니다.

 

이 경우, 필요한 각 ChatModel에 대해 프로그래밍 방식으로 ChatClient.Builder 인스턴스를 직접 생성하면 됩니다:

ChatModel myChatModel = ... // 일반적으로 자동 주입됨

ChatClient.Builder builder = ChatClient.builder(this.myChatModel);

// 또는 기본 빌더 설정으로 ChatClient 생성:

ChatClient chatClient = ChatClient.create(this.myChatModel);

 

ChatClient Fluent API

ChatClient의 Fluent API는 오버로딩된 prompt 메서드를 통해 세 가지 방식으로 Prompt를 생성할 수 있도록 지원합니다. 각 방식은 Fluent API의 시작점 역할을 합니다.

• prompt(): 인자를 받지 않는 이 메서드는 Fluent API를 시작하는 기본적인 방법입니다. 사용자 메시지, 시스템 메시지 등 Prompt의 여러 구성 요소를 체계적으로 작성할 수 있도록 지원합니다.
• prompt(Prompt prompt): 이 메서드는 Prompt 인스턴스를 인자로 받아 사용자가 Prompt의 비-Fluent API를 사용하여 미리 구성한 Prompt 객체를 그대로 전달할 수 있게 합니다.
• prompt(String context): 이 메서드는 사용자 입력 텍스트를 바로 전달할 수 있도록 한 편의성 메서드입니다. 앞서 설명한 오버로드 방식과 유사하나, 문자열 하나만으로 Prompt를 간단히 구성할 수 있습니다.

 

ChatClient 응답 처리

ChatClient, Prompt, Generations, ChatResponse에 대해 더 알고 싶으신 분들은 아래 글을 참고하시기 바랍니다.
- [Spring AI 🤖] Spring AI를 적용해보자!

 

ChatClient API는 API 모델로부터 받은 응답을 다양한 방식으로 가공할 수 있도록 지원합니다.

ChatResponse 반환

AI 모델의 응답은 ChatResponse 타입으로 정의된 풍부한 구조를 갖고 있습니다. 이 응답에는 응답이 어떻게 생성되었는지에 대한 메타데이터가 포함되며, 각각의 메타데이터를 가진 여러 개의 응답 (Generations)도 포함될 수 있습니다. 메타데이터에는 응답을 생성하는 데 사용된 토큰 수가 포함되어 있으며, 각 토큰은 대략 단어의 3/4 정도에 해당합니다. 이 정보는 중요합니다. 왜냐하면 호스팅 된 AI 모델은 요청 당 사용된 토큰 수를 기준으로 요금을 부과하기 때문입니다.

 

아래는 call() 메서드 이후에 chatResponse()를 호출하여 메타데이터를 포함한 ChatResponse 객체를 반환하는 예제입니다.

ChatResponse chatResponse = chatClient.prompt()
    .user("Tell me a joke")
    .call()
    .chatResponse();

 

엔티티 반환

AI 모델로부터 반환된 문자열을 매핑하여 엔티티 클래스로 반환하고자 하는 경우가 많습니다. entity() 메서드는 이러한 기능을 제공합니다.

 

예를 들어, 다음과 같은 Java record가 있을 때:

record ActorFilms(String actor, List<String> movies) {}

 

AI 모델의 출력 결과를 아래와 같이 해당 record로 손쉽게 매핑할 수 있습니다:

ActorFilms actorFilms = chatClient.prompt()
    .user("Generate the filmography for a random actor.")
    .call()
    .entity(ActorFilms.class);

 

또한, 제네릭 리스트와 같은 타입을 지정할 수 있도록 오버로딩된 entity 메서드 entity(ParameterizedTypeReference<T> type) 도 제공합니다:

List<ActorFilms> actorFilms = chatClient.prompt()
    .user("Generate the filmography of 5 movies for Tom Hanks and Bill Murray.")
    .call()
    .entity(new ParameterizedTypeReference<List<ActorFilms>>() {});

 

스트리밍 응답 반환

stream() 메서드를 사용하면 비동기 방식으로 AI 응답을 받을 수 있습니다. 아래는 그 예시입니다:

Flux<String> output = chatClient.prompt()
    .user("Tell me a joke")
    .stream()
    .content();

 

또한 Flux<ChatResponse> 형태로 ChatResponse 전체를 스트리밍 할 수도 있습니다. 향후에는 stream() 메서드를 사용할 때도 Java 엔티티를 바로 반환할 수 있는 편의 메서드가 제공될 예정입니다. 현재는 응답을 수집한 후 명시적으로 Structured Output Converter를 사용하여 변환해야 합니다. 아래는 그 예시이며, 이 과정은 추후 설명될 Fluent API의 파라미터 사용 예시도 함께 보여줍니다.

개인적으로 학습했던 BeanOutputConverter (StructuredOutputConverter의 구현체)에 대해 알고 싶으신 분들은 아래 글을 참고하시기 바랍니다.
- [Spring AI 🤖] 이미지를 분석하고 JSON 포맷팅을 해보자! (feat. EatToFit)

 

var converter = new BeanOutputConverter<>(new ParameterizedTypeReference<List<ActorsFilms>>() {});

Flux<String> flux = this.chatClient.prompt()
    .user(u -> u.text("""
                        Generate the filmography for a random actor.
                        {format}
                      """)
            .param("format", this.converter.getFormat()))
    .stream()
    .content();

String content = this.flux.collectList().block().stream().collect(Collectors.joining());

List<ActorFilms> actorFilms = this.converter.convert(this.content);

 

call() 반환 값

call() 메서드를 호출한 이후에는 다양한 형태로 응답을 반환받을 수 있습니다:

• String content(): 응답의 내용을 String 형태로 반환합니다.
• ChatResponse chatResponse(): 여러 개의 생성 결과 (Generations)와 응답 메타데이터 (예: 사용된 토큰 수 등)를 포함하는 ChatResponse 객체를 반환합니다.
• entity(): 응답을 Java 타입의 엔티티로 반환합니다.
• entity(ParameterizedTypeReference<T> type): 제네릭 컬렉션 타입의 엔티티를 반환할 때 사용합니다. 예: List<MyEntity>
• entity(Class<T> type): 단일 엔티티 타입을 반환할 때 사용합니다.
• entity(StructuredOutputConverter<T> structuredOutputConverter): 문자열을 엔티티 타입으로 변환하기 위한 StructuredOutputConverter 인스턴스를 지정합니다.

또한, call() 대신 stream() 메서드를 사용할 수도 있습니다.

 

stream() 반환 값

stream() 메서드를 호출한 이후에는 다음과 같은 방식으로 응답을 받을 수 있습니다:

• Flux<String> content(): AI 모델이 생성하는 문자열을 실시간으로 스트리밍 형태(Flux)로 반환합니다.
• Flux<ChatResponse> chatResponse(): 응답 메타데이터를 포함하는 ChatResponse 객체를 스트리밍 형태(Flux)로 반환합니다.

 

기본값 사용

@Configuration 클래스 내에서 시스템 텍스트의 기본값을 설정하여 ChatClient를 생성하면 런타임 코드가 간결해집니다.

 

기본값을 설정하면 매 요청마다 시스템 텍스트를 지정할 필요 없이 사용자 텍스트만 지정하면 됩니다.

 

기본 시스템 텍스트

다음 예시는 시스템 텍스트를 항상 해적의 말투로 응답하도록 설정하는 방법을 보여줍니다. 이 설정은 @Configuration 클래스 안에서 ChatClient 인스턴스를 정의함으로써, 런타임 코드에서 중복 설정을 피할 수 있습니다.

@Configuration
class Config {

    @Bean
    ChatClient chatClient(ChatClient.Builder builder) {
        return builder.defaultSystem("You are a friendly chat bot that answers question in the voice of a Pirate")
                .build();
    }

}

 

그리고 이를 호출하는 @RestController는 아래와 같습니다.

@RestController
class AIController {

	private final ChatClient chatClient;

	AIController(ChatClient chatClient) {
		this.chatClient = chatClient;
	}

	@GetMapping("/ai/simple")
	public Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
		return Map.of("completion", this.chatClient.prompt().user(message).call().content());
	}
}

 

curl로 호출하면 아래와 같이 나옵니다.

❯ curl localhost:8080/ai/simple
{"completion":"Why did the pirate go to the comedy club? To hear some arrr-rated jokes! Arrr, matey!"}

 

파라미터가 포함된 기본 시스템 텍스트

다음 예제에서는 시스템 텍스트에 플레이스홀더 { voice }를 사용하여, 디자인 타임이 아닌 런타임에 말투를 지정할 수 있도록 구성합니다.

@Configuration
class Config {

    @Bean
    ChatClient chatClient(ChatClient.Builder builder) {
        return builder.defaultSystem("You are a friendly chat bot that answers question in the voice of a {voice}")
                .build();
    }

}

 

컨트롤러에서는 아래와 같이 시스템 텍스트에 동적으로 파라미터를 주입합니다:

 

@RestController
class AIController {
	private final ChatClient chatClient;

	AIController(ChatClient chatClient) {
		this.chatClient = chatClient;
	}

	@GetMapping("/ai")
	Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message, String voice) {
		return Map.of("completion",
				this.chatClient.prompt()
						.system(sp -> sp.param("voice", voice))
						.user(message)
						.call()
						.content());
	}

}

 

httpie를 사용한 실행 결과 예시는 아래와 같습니다.

http localhost:8080/ai voice=='Robert DeNiro'

{
    "completion": "You talkin' to me? Okay, here's a joke for ya: Why couldn't the bicycle stand up by itself? Because it was two tired! Classic, right?"
}

 

기타 기본값 설정

Client.Builder 수준에서 프롬프트의 기본 구성을 지정할 수 있습니다.

• defaultOptions(ChatOptions chatOptions): ChatOptions 클래스에서 정의된 공통 옵션 또는 OpenAiChatOptions와 같은 모델별 옵션을 설정할 수 있습니다. 모델별 ChatOptions 구현에 대한 자세한 내용은 JavaDocs를 참고하십시오.
• defaultFunction(String name, String description, java.util.function.Function<I, O> function): 사용자 텍스트에서 참조될 함수 이름, 함수의 목적을 설명하는 설명, 그리고 실제 실행될 Java 함수 인스턴스를 설정합니다. AI 모델은 이 정보를 기반으로 적절한 함수를 선택해 실행할 수 있습니다.
• defaultFunctions(String... functionNames): 애플리케이션 컨텍스트에 정의된 Function 빈의 이름들을 지정합니다.
• defaultUser(String text), defaultUser(Resource text), defaultUser(Consumer<UserSpec> userSpecConsumer): 사용자 입력 텍스트의 기본값을 설정할 수 있습니다. 특히 Consumer<UserSpec>은 람다 표현식을 통해 텍스트와 기본 파라미터를 함께 정의할 수 있게 해 줍니다.
• defaultAdvisors(Advisor... advisor): 프롬프트를 생성하는 데 사용되는 데이터를 수정하거나 보강하는 Advisor를 설정합니다. 예: QuestionAnswerAdvisor는 사용자 입력에 기반한 관련 문맥 정보를 프롬프트에 추가하여 RAG(Retrieval-Augmented Generation, 검색 증강 생성)를 구현합니다.
• defaultAdvisors(Consumer<AdvisorSpec> advisorSpecConsumer): AdvisorSpec을 활용하여 여러 Advisor를 람다 방식으로 등록할 수 있도록 지원합니다.

 

이러한 기본값들은 런타임에서 해당하는 메서드를 통해 재정의할 수 있습니다. (default 접두사 없이 사용)

• options(ChatOptions chatOptions)
• function(...), functions(...)
• user(...)
• advisors(...), advisors(Consumer<AdvisorSpec>)

 

Advisors

Advisors API는 Spring 애플리케이션에서 AI 기반 상호작용을 가로채고, 수정하며, 확장할 수 있는 유연하고 강력한 수단을 제공합니다.

 

AI 모델을 사용자 입력으로 호출할 때, 일반적인 패턴 중 하나는 프롬프트에 문맥 정보를 추가하거나 보강하는 것입니다.

 

이러한 문맥 정보 (contextual data)는 다양한 형태일 수 있으며, 일반적으로 다음 두 가지 유형이 자주 사용됩니다.

• 사용자 정의 데이터: AI 모델이 학습하지 않은 자체 데이터입니다. 모델이 유사한 데이터를 학습했더라도, 추가된 문맥 데이터가 응답 생성 시 우선적으로 반영됩니다.
• 대화 이력 (Conversational History): 챗 모델 API는 상태를 유지하지 않기 때문에, 예를 들어 AI 모델에 이름을 알려줘도 이후 요청에서 기억하지 못합니다. 따라서 이전 대화 내용을 반영하고 싶다면, 매 요청마다 해당 이력을 함께 전송해야 합니다.

ChatClient에서의 Advisor 설정

ChatClient의 Fluent API는 Advisor 구성을 위한 AdvisorSpec 인터페이스를 제공합니다. 이 인터페이스는 파라미터를 추가하거나, 여러 개의 파라미터를 한 번에 설정하거나, 하나 이상의 Advisor를 체인에 추가할 수 있는 메서드들을 제공합니다.

interface AdvisorSpec {
    AdvisorSpec param(String k, Object v);
    AdvisorSpec params(Map<String, Object> p);
    AdvisorSpec advisors(Advisor... advisors);
    AdvisorSpec advisors(List<Advisor> advisors);
}

 

중요
Advisor가 체인에 추가되는 순서는 매우 중요합니다.
이 순서는 각 Advisor의 실행 순서를 결정하며, 각 Advisor는 프롬프트나 문맥을 어떤 방식으로든 수정합니다.
하나의 Advisor가 수행한 변경 사항은 체인의 다음 Advisor로 전달되어 연속적으로 적용됩니다.

 

ChatClient.builder(chatModel)
    .build()
    .prompt()
    .advisors(
        new MessageChatMemoryAdvisor(chatMemory),
        new QuestionAnswerAdvisor(vectorStore)
    )
    .user(userText)
    .call()
    .content();

 

이 구성에서는 MessageChatMemoryAdvisor가 먼저 실행되어 대화 기록을 프롬프트에 추가합니다. 그런 다음 QuestionAnswerAdvisor는 사용자의 질문과 추가된 대화 기록을 기반으로 검색을 수행하여 잠재적으로 더 관련성이 높은 결과를 제공합니다.

 

Question Answer Advisor에 대해 알아보기

 

Retrieval Augmented Generation (RAG)

Retrieval Augmented Generation 가이드를 참고하세요.

 

Chat Memory

ChatMemory 인터페이스는 채팅 대화 이력을 저장하기 위한 저장소를 나타냅니다. 이 인터페이스는 다음과 같은 기능을 제공합니다:

• 대화에 메시지를 추가하는 메서드
• 대화로부터 메시지를 조회하는 메서드
• 대화 이력을 초기화(삭제) 하는 메서드

현재 ChatMemory의 구현체는 두 가지가 있습니다:

• InMemoryChatMemory: 메모리 기반의 휘발성 저장 방식
• CassandraChatMemory: TTL (유효 기간)을 가진 지속성 저장 방식

예를 들어, 하루 동안 유효한 CassandraChatMemory 인스턴스를 생성하려면 다음과 같이 작성할 수 있습니다:

CassandraChatMemory.create(
    CassandraChatMemoryConfig.builder()
        .withTimeToLive(Duration.ofDays(1))
        .build()
);

 

다음 Advisor 구현체들은 ChatMemory를 활용하여 대화 이력을 프롬프트에 반영합니다. 각 Advisor는 메모리를 프롬프트에 삽입하는 방식에서 차이가 있습니다:

• MessageChatMemoryAdvisor: 대화 이력을 메시지의 컬렉션 형태로 프롬프트에 추가합니다.
• PromptChatMemoryAdvisor: 대화 이력을 시스템 텍스트 안에 삽입하여 프롬프트를 보강합니다.
• VectorStoreChatMemoryAdvisor: 생성자에 다음과 같은 구성 요소를 포함합니다.

VectorStoreChatMemoryAdvisor(
    VectorStore vectorStore,
    String defaultConversationId,
    int chatHistoryWindowSize,
    int order
)

 

이 생성자를 사용하면 다음과 같은 작업을 수행할 수 있습니다.

• 문서를 관리하고 질의하기 위한 VectorStore 인스턴스를 지정할 수 있습니다.
• 컨텍스트에 대화 ID가 제공되지 않았을 경우 사용할 기본 대화 ID를 설정할 수 있습니다.
• 대화 이력을 조회할 윈도우 크기를 토큰 단위로 정의할 수 있습니다.
• Chat Advisor 시스템에서 사용할 시스템 텍스트를 제공할 수 있습니다.
• 이 Advisor의 체인 내 우선순위 (실행 순서)를 설정할 수 있습니다.

VectorStoreChatMemoryAdvisor.builder() 메서드를 사용하면 다음 항목들을 설정할 수 있습니다:

• 기본 대화 ID (defaultConversationId)
• 대화 이력을 조회할 윈도우 크기 (토큰 단위)
• 대화 이력의 조회 순서 (order)

이제 여러 Advisor를 사용하는 예제 @Service 구현이 아래에 나옵니다:

import static org.springframework.ai.chat.client.advisor.AbstractChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY;
import static org.springframework.ai.chat.client.advisor.AbstractChatMemoryAdvisor.CHAT_MEMORY_RETRIEVE_SIZE_KEY;

@Service
public class CustomerSupportAssistant {

    private final ChatClient chatClient;

    public CustomerSupportAssistant(ChatClient.Builder builder, VectorStore vectorStore, ChatMemory chatMemory) {

        this.chatClient = builder
            .defaultSystem("""
                You are a customer chat support agent of an airline named "Funnair". Respond in a friendly,
                helpful, and joyful manner.

                Before providing information about a booking or cancelling a booking, you MUST always
                get the following information from the user: booking number, customer first name and last name.

                Before changing a booking you MUST ensure it is permitted by the terms.

                If there is a charge for the change, you MUST ask the user to consent before proceeding.
                """)
            .defaultAdvisors(
                new MessageChatMemoryAdvisor(chatMemory),     // 대화 메모리 보강
                new QuestionAnswerAdvisor(vectorStore),       // RAG 보강
                new SimpleLoggerAdvisor()                     // 로깅
            )
            .defaultFunctions("getBookingDetails", "changeBooking", "cancelBooking")  // 함수 호출 설정
            .build();
    }

    public Flux<String> chat(String chatId, String userMessageContent) {

        return this.chatClient.prompt()
            .user(userMessageContent)
            .advisors(a -> a
                .param(CHAT_MEMORY_CONVERSATION_ID_KEY, chatId)
                .param(CHAT_MEMORY_RETRIEVE_SIZE_KEY, 100))
            .stream()
            .content();
    }
}

 

 

Question Answer Advisor에 대해 알아보기

 

로깅 (Logging)

SimpleLoggerAdvisor는 ChatClient의 요청 및 응답 데이터를 로그로 기록하는 Advisor입니다. 이 기능은 AI와의 상호작용을 디버깅하거나 모니터링할 때 유용하게 사용할 수 있습니다.

 

팁
Spring AI는 LLM과 Vector Store 간의 상호작용에 대한 가시성 (Obserability)을 지원합니다.
자세한 내용은 Obserability 가이드를 참고하시기 바랍니다.

 

로깅을 활성화하려면 ChatClient를 생성할 때 SimpleLoggerAdvisor를 Advisor 체인에 추가해야 합니다. 이 Advisor는 체인의 마지막쯤에 추가하는 것이 권장됩니다.

ChatResponse response = ChatClient.create(chatModel).prompt()
    .advisors(new SimpleLoggerAdvisor())
    .user("Tell me a joke?")
    .call()
    .chatResponse();

 

로그를 확인하려면 application.properties 또는 application.yml 파일에 다음과 같이 로깅 레벨을 설정합니다:

logging.level.org.springframework.ai.chat.client.advisor=DEBUG

 

AdvisedRequest와 ChatResponse에서 어떤 정보를 로그로 출력할지 직접 커스터마이징 할 수도 있습니다. 다음 생성자를 사용합니다:

SimpleLoggerAdvisor(
    Function<AdvisedRequest, String> requestToString,
    Function<ChatResponse, String> responseToString
)

 

사용 예:

SimpleLoggerAdvisor customLogger = new SimpleLoggerAdvisor(
    request -> "Custom request: " + request.userText(),
    response -> "Custom response: " + response.getResult()
);

 

이렇게 하면 로깅되는 내용을 상황에 맞게 조정할 수 있습니다.

 

팁
운영 환경에서는 민감한 정보를 로깅하지 않도록 각별히 주의해야 합니다.

 

Reference

• Spring AI : Chat Client API