Spring AI 키워드 정리 - 1

Spring AI 아키텍처

[ 개발자 ] →

ChatClient / ChatModel →

Prompt (Message 묶음 + ChatOptions) →

AI 모델 호출 (.call() / .stream()) →

ChatResponse

키워드 정리

ChatModel

• AI 모델과 직접 통신하는 저수준의 인터페이스

• 세밀한 제어에 사용

• Spring AI 에서 모든 AI 모델은 이 인터페이스를 구현하여 호출

public interface ChatModel extends Model<Prompt, ChatResponse> {
    default String call(String message) { ... }  // 단순 문자열 호출
    ChatResponse call(Prompt prompt);            // 풀 옵션 호출
}

ChatClient

• ChatModel 을 감싸는 고수준의 Fluent API

• 보통 일반적인 개발에 사용

// ChatClient 생성 (보통 Bean으로 등록)
@Bean
public ChatClient chatClient(ChatModel chatModel) {
    return ChatClient.builder(chatModel)
        .defaultSystem("당신은 친절한 고객 서비스 AI입니다.")
        .build();
}

// 사용
@Service
public class CustomerService {

    private final ChatClient chatClient;

    // 단순 텍스트 응답
    public String ask(String question) {
        return chatClient.prompt()
            .user(question)
            .call()
            .content(); // String 반환
    }
}

Prompt

• AI에게 보내는 요청 전체를 담는 객체로 Message 타입의 List 와 ChatOption 으로 구성됨

public class Prompt implements ModelRequest<List<Message>> {
    private final List<Message> messages;  // 메시지 목록
    private ChatOptions modelOptions;      // 모델 설정값
}

Message

• 대화의 한줄

• 타입을 여러가지로 놓고 사용함

// Message 종류 (MessageType)
SystemMessage  → AI의 역할/행동 지침을 설정 (ex: "너는 번역 전문가야")
UserMessage    → 사용자가 보낸 메시지
AssistantMessage → AI가 이전에 답한 메시지 (대화 히스토리용)

// 직접 구성하는 예시
Message system = new SystemMessage("당신은 Java 전문 개발자입니다.");
Message user   = new UserMessage("Lambda 표현식이 뭔가요?");

Prompt prompt = new Prompt(List.of(system, user));
ChatResponse response = chatModel.call(prompt);

call(), stream()

• 응답을 받는 방식들

// call() : 응답이 완전히 생성될 때까지 기다렸다가 한 번에 반환
// → 일반 REST API처럼 동작
public String callExample() {
    return chatClient.prompt()
        .user("스프링이 뭔가요?")
        .call()         // ← 동기, 블로킹
        .content();     // String 반환
}

// stream() : 토큰이 생성될 때마다 실시간으로 반환
// → ChatGPT 웹에서 글자가 하나씩 나오는 그 효과
// → WebFlux의 Flux<String>으로 반환됨
public Flux<String> streamExample() {
    return chatClient.prompt()
        .user("스프링이 뭔가요?")
        .stream()       // ← 비동기, 논블로킹
        .content();     // Flux<String> 반환
}

ChatOptions

• AI 모델에게 보내는 파라미터 설정값

• 모델 종류, 창의성 (temperature), 최대 토큰 수 등을 조절

• 빌더의 옵션 순으로 적용됨

// 공통 인터페이스 (어떤 모델이든 공통)
public interface ChatOptions {
    String getModel();           // 사용할 모델명
    Float getTemperature();      // 창의성 (0.0 ~ 1.0, 높을수록 창의적)
    Integer getMaxTokens();      // 최대 응답 길이
    Float getTopP();             // 다음 토큰 선택 다양성
    List<String> getStopSequences(); // 특정 문자열에서 응답 중단
}

// 실제 사용 예시 (OpenAI 기준)
Prompt prompt = new Prompt(
    "Java의 장점을 설명해줘",
    OpenAiChatOptions.builder()
        .model("gpt-4o")
        .temperature(0.7f)   // 적당히 창의적으로
        .maxTokens(500)      // 500 토큰 이내로
        .build()
);