[Spring AI 2025 Renewal #3] Advisors API

안녕하세요 dev_writer입니다.

 

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

 

Advisors API

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

 

Advisors API를 활용하면 더 정교하고, 재사용 가능하며, 유지보수가 용이한 AI 컴포넌트를 구현할 수 있습니다.

 

주요 이점으로는 반복적인 생성형 AI 패턴을 캡슐화하고, 대형 언어 모델 (LLM)로 송수신되는 데이터를 변환하며, 다양한 모델 및 사용 사례 전반에 걸쳐 이식성을 제공하는 것이 포함됩니다.

 

다음 예시와 같이 ChatClient API를 사용하여 기존 advisor들을 구성할 수 있습니다:

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        new MessageChatMemoryAdvisor(chatMemory), // chat-memory advisor
        new QuestionAnswerAdvisor(vectorStore)    // RAG advisor
    )
    .build();

String response = this.chatClient.prompt()
    // Set advisor parameters at runtime
    .advisors(advisor -> advisor.param("chat_memory_conversation_id", "678")
            .param("chat_memory_response_size", 100))
    .user(userText)
    .call()
	.content();

 

advisor는 builder의 defaultAdvisors() 메서드를 사용해 빌드 타임에 등록하는 것이 권장됩니다.

 

advisor는 관찰 가능성 (Observability) 스택에도 참여하므로, 실행과 관련된 메트릭 및 트레이스를 확인할 수 있습니다.

 

Question Answer Advisor에 대해 더 알아보기

 

핵심 컴포넌트

이 API는 스트리밍이 아닌 시나리오에 대해 CallAroundAdvisor 및 CallAroundAdvisorChain을 포함하고, 스트리밍 시나리오에 대해서는 StreamAroundAdvisor 및 StreamAroundAdvisorChain을 포함합니다. 또한 AdvisedRequest는 확정되지 않은 Prompt 요청을 나타내며, AdvisedResponse는 Chat Completion 응답을 나타냅니다. 둘 다 advisor 체인 전반에서 상태를 공유할 수 있는 advise-context를 포함합니다.

 

출처: Spring AI 공식 문서

 

nextAroundCall() 및 nextAroundStream()는 주요 advisor 메서드로, 일반적으로 확정되지 않은 Prompt 데이터를 검사하고, Prompt 데이터를 사용자 정의하거나 보강하며, advisor 체인에서 다음 엔티티를 호출하고, 선택적으로 요청을 차단하며, chat completion 응답을 검사하고, 처리 오류를 나타내기 위해 예외를 발생시키는 등의 동작을 수행합니다.

 

추가로, getOrder() 메서드는 체인에서 advisor의 순서를 결정하고, getName()은 고유한 advisor 이름을 제공합니다.

 

Spring AI 프레임워크에 의해 생성된 Advisor Chain은 getOrder() 값에 따라 정렬된 여러 advisor들을 순차적으로 호출할 수 있도록 합니다. 낮은 값이 먼저 실행됩니다. 마지막 advisor는 자동으로 추가되며, LLM에 요청을 전송합니다.

 

다음의 플로우 다이어그램은 advisor 체인과 Chat Model 간의 상호작용을 보여줍니다.

 

출처: Spring AI 공식 문서

 

1. Spring AI 프레임워크는 사용자의 Prompt로부터 AdvisedRequest를 생성하고, 비어 있는 AdvisorContext 객체를 함께 생성합니다.
2. 체인의 각 advisor는 해당 요청을 처리하며, 필요에 따라 요청을 수정할 수 있습니다. 또는 다음 엔티티 호출을 생략하여 요청을 차단할 수도 있습니다. 후자의 경우, 해당 advisor는 응답을 직접 작성할 책임이 있습니다.
3. 프레임워크에서 제공하는 최종 advisor는 요청을 Chat Model에 전송합니다.
4. Chat Model의 응답은 advisor 체인을 거쳐 다시 전달되며, AdvisedResponse로 변환됩니다. 이 응답에는 공유된 AdvisorContext 인스턴스가 포함됩니다.
5. 각 advisor는 응답을 처리하거나 수정할 수 있습니다.
6. 최종 AdvisedResponse는 ChatCompletion을 추출하여 클라이언트에 반환됩니다.

 

Advisor 순서

advisor 체인에서의 실행 순서는 getOrder() 메서드에 의해 결정됩니다. 다음은 이해해야 할 주요 사항입니다.

• order 값이 낮을수록 advisor는 먼저 실행됩니다.
• advisor 체인은 스택처럼 동작합니다.
  • 체인의 첫 번째 advisor는 요청을 가장 먼저 처리합니다.
  • 그리고 응답을 가장 마지막에 처리합니다.
• 실행 순서를 제어하려면:
  • Ordered.HIGHEST_PRECEDENCE에 가까운 값을 설정하면 advisor는 체인에서 가장 먼저 요청을 처리하고, 응답을 가장 마지막에 처리합니다.
  • Ordered.LOWEST_PRECEDENCE에 가까운 값을 설정하면 advisor는 체인에서 가장 마지막에 요청을 처리하고, 응답을 가장 먼저 처리합니다.
• order 값이 높을수록 우선순위는 낮게 해석됩니다.
• 여러 advisor가 같은 order 값을 가질 경우, 실행 순서는 보장되지 않습니다.

 

참고
order 값과 실행 순서 사이에 혼동이 있을 수 있는 이유는, advisor 체인이 스택처럼 동작하기 때문입니다: 우선순위가 가장 높은 advisor (가장 낮은 order 값)는 스택의 가장 위에 추가됩니다. 요청 처리 시에는 스택이 풀리면서 가장 먼저 실행됩니다. 응답 처리 시에는 스택이 다시 쌓이면서 가장 마지막에 실행됩니다.

 

다음은 Spring의 Ordered 인터페이스가 의미하는 바입니다.

public interface Ordered {

    /**
     * 가장 높은 우선순위를 나타내는 상수입니다.
     * @see java.lang.Integer#MIN_VALUE
     */
    int HIGHEST_PRECEDENCE = Integer.MIN_VALUE;

    /**
     * 가장 낮은 우선순위를 나타내는 상수입니다.
     * @see java.lang.Integer#MAX_VALUE
     */
    int LOWEST_PRECEDENCE = Integer.MAX_VALUE;

    /**
     * 이 객체의 order 값을 반환합니다.
     * <p>값이 높을수록 우선순위는 낮게 해석됩니다. 그 결과,
     * 가장 낮은 값을 가진 객체가 가장 높은 우선순위를 가지게 됩니다
     * (서블릿의 {@code load-on-startup} 값과 유사한 개념입니다).
     * <p>동일한 order 값을 가지는 경우, 해당 객체들의 정렬 위치는 임의로 결정됩니다.
     * @return order 값
     * @see #HIGHEST_PRECEDENCE
     * @see #LOWEST_PRECEDENCE
     */
    int getOrder();
}

 

팁
입력과 출력 양쪽 모두에서 체인의 첫 번째에 위치해야 하는 사용 사례의 경우:
- 각각의 측면에 대해 별도의 advisor를 사용하십시오.
- 이들 advisor에 서로 다른 order 값을 설정하십시오.
- advisor context를 사용하여 두 advisor 간에 상태를 공유하십시오.

 

API 개요

주요 Advisor 인터페이스들은 org.springframework.ai.chat.client.advisor.api 패키지에 위치해 있습니다. 자신만의 advisor를 생성할 때 마주하게 될 핵심 인터페이스는 다음과 같습니다.

public interface Advisor extends Ordered {

	String getName();

}

 

동기 및 리액티브 방식의 Advisor를 위한 두 개의 하위 인터페이스는 다음과 같습니다.

public interface CallAroundAdvisor extends Advisor {

    /**
     * ChatModel#call(Prompt) 메서드를 감싸는 around advice입니다.
     * @param advisedRequest advisor가 적용된 요청 객체
     * @param chain advisor 체인
     * @return 응답
     */
    AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain);

}

 

그리고

public interface StreamAroundAdvisor extends Advisor {

    /**
     * advisor가 적용된 요청 호출을 감싸는 around advice입니다.
     * @param advisedRequest advisor가 적용된 요청 객체
     * @param chain 실행될 advisor 체인
     * @return advisor가 적용된 요청의 결과
     */
    Flux<AdvisedResponse> aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain);

}

 

Advice의 체인을 계속 진행하려면, 자신의 Advice 구현 내에서 CallAroundAdvisorChain과 StreamAroundAdvisorChain을 사용하십시오.

// 동기 방식
AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) {
    // 체인의 다음 advisor를 호출하여 체인 계속 진행
    return chain.next(advisedRequest);
}

// 리액티브 (스트리밍) 방식
Flux<AdvisedResponse> aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) {
    // 체인의 다음 advisor를 호출하여 체인 계속 진행
    return chain.next(advisedRequest);
}

 

Advisor 구현

advisor를 생성하려면 CallAroundAdvisor 또는 StreamAroundAdvisor (또는 둘 다)를 구현하십시오.

 

구현해야 할 핵심 메서드는 비 스트리밍 advisor의 경우 nextAroundCall(), 스트리밍 advisor의 경우 nextAroundStream()입니다.

 

예시

우리는 관찰 (Observing) 및 보강 (Augmenting) 사례를 위한 advisor를 어떻게 구현하는지 보여주기 위해 몇 가지 실습 예제를 제공할 예정입니다.

로깅 Advisor

우리는 다음 advisor를 체인에서 호출하기 전과 후에 AdvisedRequest와 AdvisedResponse를 로깅하는 간단한 로깅 advisor를 구현할 수 있습니다.

이 advisor는 요청 및 응답을 관찰만 할 뿐 수정하지 않으며, 비 스트리밍과 스트리밍 시나리오 모두를 지원합니다.

public class SimpleLoggerAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {

	private static final Logger logger = LoggerFactory.getLogger(SimpleLoggerAdvisor.class);

	@Override
	public String getName() { // 1️⃣
		return this.getClass().getSimpleName();
	}

	@Override
	public int getOrder() { // 2️⃣
		return 0;
	}

	@Override
	public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) {

		logger.debug("BEFORE: {}", advisedRequest);

		AdvisedResponse advisedResponse = chain.nextAroundCall(advisedRequest);

		logger.debug("AFTER: {}", advisedResponse);

		return advisedResponse;
	}

	@Override
	public Flux<AdvisedResponse> aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) {

		logger.debug("BEFORE: {}", advisedRequest);

		Flux<AdvisedResponse> advisedResponses = chain.nextAroundStream(advisedRequest);

		return new MessageAggregator().aggregateAdvisedResponse(advisedResponses,
			advisedResponse -> logger.debug("AFTER: {}", advisedResponse)); // 3️⃣
	}
}

1. advisor에 고유한 이름을 제공하려면 getName() 메서드를 구현합니다.
2. getOrder() 값을 설정하여 실행 순서를 제어할 수 있습니다. 값이 낮을수록 먼저 실행됩니다.
3. MessageAggregator는 Flux 응답을 하나의 AdvisedResponse로 집계하는 유틸리티 클래스입니다.

이는 스트림 내 개별 항목이 아닌 전체 응답을 관찰하거나 로깅 등의 작업을 수행할 때 유용합니다.

단, MessageAggregator는 읽기 전용 (read-only) 작업이므로 응답을 수정할 수는 없습니다.

 

Re-Reading (Re2) Advisor

"Re-Reading Improves Reasoning in Large Language Models"라는 논문에서는 LLM의 추론 능력을 향상하는 Re-Reading (Re2) 기법을 소개합니다.

 

이 기법은 입력 프롬프트를 다음과 같이 보강합니다.

{Input_Query}
Read the question again: {Input_Query}

 

사용자의 입력 쿼리에 Re2 기법을 적용하는 advisor는 다음과 같이 구현할 수 있습니다.

public class ReReadingAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {

	private AdvisedRequest before(AdvisedRequest advisedRequest) { // 1️⃣

		Map<String, Object> advisedUserParams = new HashMap<>(advisedRequest.userParams());
		advisedUserParams.put("re2_input_query", advisedRequest.userText());

		return AdvisedRequest.from(advisedRequest)
			.userText("""
			    {re2_input_query}
			    Read the question again: {re2_input_query}
			    """)
			.userParams(advisedUserParams)
			.build();
	}

	@Override
	public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) { // 2️⃣
		return chain.nextAroundCall(this.before(advisedRequest));
	}

	@Override
	public Flux<AdvisedResponse> aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) { // 3️⃣ 
		return chain.nextAroundStream(this.before(advisedRequest));
	}

	@Override
	public int getOrder() { // 4️⃣
		return 0;
	}

	@Override
	public String getName() { // 5️⃣
		return this.getClass().getSimpleName();
	}
}

1. before 메서드는 Re-Reading 기법을 적용하여 사용자의 입력 쿼리를 보강합니다.
2. aroundCall 메서드는 비 스트리밍 요청을 가로채고 Re2 기법을 적용합니다.
3. aroundStream 메서드는 스트리밍 요청을 가로채고 Re2 기법을 적용합니다.
4. getOrder()를 통해 실행 순서를 제어할 수 있습니다. 값이 낮을수록 먼저 실행됩니다.
5. getName()은 advisor의 고유 이름을 제공합니다.

 

Spring AI 내장 Advisor

Spring AI 프레임워크는 AI 상호작용을 향상하기 위한 여러 내장 Advisor를 제공합니다. 아래는 사용 가능한 Advisor들의 개요입니다.

• Chat Memory Advisors: 이러한 Advisor들은 대화 이력을 chat memory 저장소에서 관리합니다.
  • MessageChatMemoryAdvisor: 메모리를 조회하여 메시지 컬렉션 형태로 프롬프트에 추가합니다. 이 방식은 대화 이력의 구조를 유지할 수 있지만, 모든 AI 모델이 이 형식을 지원하지는 않습니다.
  • PromptChatMemoryAdvisor: 메모리를 조회하여 프롬프트의 시스템 텍스트에 삽입합니다.
  • VectorStoreChatMemoryAdvisor: VectorStore에서 메모리를 조회하고, 이를 프롬프트의 시스템 텍스트에 삽입합니다. 대규모 데이터셋에서 관련 정보를 효율적으로 검색 및 삽입할 수 있어 유용합니다.
• Question Answering Advisor
  • QuestionAnswerAdvisor: VectorStore를 활용하여 질문-응답 기능을 제공합니다. 이는 RAG (Retrieval-Augmented Generation, 검색 증강 생성) 패턴을 구현합니다.
• Content Safety Advisor
  • SafeGuardAdvisor: 모델이 유해하거나 부적절한 콘텐츠를 생성하지 않도록 방지하는 간단한 Advisor입니다.

 

스트리밍 vs 비 스트리밍

출처: Spring AI 공식 문서

 

비 스트리밍 (Non-streaming) advisor는 완전한 요청 및 응답 객체를 기반으로 작동합니다.

스트리밍 (Streaming) advisor는 요청 및 응답을 연속적인 스트림으로 처리하며, 반응형 프로그래밍 개념 (예: 응답에 Flux 사용)을 기반으로 합니다.

@Override
public Flux<AdvisedResponse> aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) {

    return Mono.just(advisedRequest)
            .publishOn(Schedulers.boundedElastic())
            .map(request -> {
                // 이 코드는 블로킹 또는 논블로킹 스레드에서 실행될 수 있습니다.
                // next 호출 전 advisor 로직 실행
                return request;
            })
            .flatMapMany(request -> chain.nextAroundStream(request))
            .map(response -> {
                // next 호출 후 advisor 로직 실행
                return response;
            });
}

 

모범 사례

1. Advisor는 특정 작업에 집중하여 구현함으로써 모듈화를 높이십시오.
2. 필요할 경우 advisor 간 상태 공유를 위해 adviseContext를 활용하십시오.
3. 스트리밍과 비 스트리밍 버전 모두를 구현하여 최대한의 유연성을 확보하십시오.
4. 데이터 흐름이 올바르게 이루어지도록 advisor의 실행 순서를 신중하게 고려하십시오.

 

하위 호환성

중요
AdvisedRequest가 새 패키지로 이동되었습니다.

 

중대한 API 변경 사항

Advisor 인터페이스

• 1.0 M2 버전에서는 RequestAdvisor와 ResponseAdvisor라는 별도의 인터페이스가 있었습니다.
  • RequestAdvisor는 ChatModel.call 및 ChatModel.stream 메서드가 호출되기 이전에 실행되었습니다.
  • ResponseAdvisor는 해당 메서드가 호출된 이후에 실행되었습니다.
• 1.0 M3 버전에서는 위 인터페이스들이 다음으로 대체되었습니다.
  • CallAroundAdvisor
  • StreamAroundAdvisor
• 이전에 ResponseAdvisor의 일부였던 StreamResponseMode는 제거되었습니다.

 

Context Map 처리

• 1.0 M2 버전에서는
  • context map이 별도의 메서드 인자로 전달되었습니다.
  • 이 map은 변경 가능 (mutable) 하며 체인을 따라 전달되었습니다.
• 1.0 M3 버전에서는
  • context map이 이제 AdvisedRequest와 AdvisedResponse 레코드의 일부로 통합되었습니다.
  • map은 불변 (immutable)입니다.
  • context를 업데이트하려면 updateContext 메서드를 사용해야 하며, 이 메서드는 업데이트된 내용을 가진 새로운 변경 불가능한 map을 생성합니다.

1.0 M3에서 context를 업데이트하는 예시입니다.

@Override
public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) {

    this.advisedRequest = advisedRequest.updateContext(context -> {
        context.put("aroundCallBefore" + getName(), "AROUND_CALL_BEFORE " + getName());  // 여러 key-value 추가
        context.put("lastBefore", getName());  // 단일 key-value 추가
        return context;
    });

    // 메서드 구현 계속...
}

 

실제 적용해보기

사전 준비

먼저, start.spring.io 에서 Spring Web과 OpenAI 구현체를 의존받도록 설정해둡니다.

 

이후, application.properties에 다음 값들을 세팅해둡니다.

spring.application.name=demo
spring.ai.openai.chat.options.model={AI 모델 (ex: gpt-4o)}
spring.ai.openai.api-key={API 키}
logging.level.root=DEBUG // SimpleLoggerAdvisor를 이용할 때 필요

 

코드 작성: MessageChatMemoryAdvisor 적용 이전

MessageChatMemoryAdvisor를 적용하기 이전의 코드를 작성해보면 아래와 같습니다. 메시지를 받으면 바로 응답을 이끌어내는 home 메서드를 작성했습니다.

package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/")
    public String home(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

 

이후 실제로 실행해보면, 이름을 기억하지 못 하는 것을 확인할 수 있습니다. (테스트는 httpie로 진행했습니다.)

 

코드 작성: MessageChatMemoryAdvisor 적용 이후

이제 공식 문서에 소개된 MessageChatMemoryAdvisor를 적용해보면, 이름을 기억하고 있음을 볼 수 있습니다. (인메모리이기 때문에 완전히 종료 후 재실행하면 기억하지 못합니다.)

package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultAdvisors(
                        new MessageChatMemoryAdvisor(new InMemoryChatMemory())
                )
                .build();
    }

    @GetMapping("/")
    public String home(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

 

추가로 로깅을 할 수 있는 SimpleLoggerAdvisor를 적용해봅시다.

SimpleLoggerAdvisor 적용

SimpleLoggerAdvisor는 이 구현체만 기존의 코드에 붙이면 됩니다.

package com.example.demo;

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.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultAdvisors(
                        new SimpleLoggerAdvisor(),
                        new MessageChatMemoryAdvisor(new InMemoryChatMemory())
                )
                .build();
    }

    @GetMapping("/")
    public String home(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

 

애플리케이션 로그 레벨을 DEBUG로 설정하면, 아래와 같이 요청과 응답에 대한 로깅이 진행됨을 볼 수 있습니다.

요청 로그

응답 로그

 

Reference

• Spring AI : Advisors API
• Dan Vega : Conversational History in Java based Generative AI Applications