ChatModel API — 채팅 완성 기능을 애플리케이션에 통합하기

Chat Model API는 AI 기반 채팅 완성(chat completion) 기능을 애플리케이션에 통합할 수 있게 해주는 API예요. GPT 같은 사전 훈련된 언어 모델을 활용해서 사용자 입력에 대해 자연어로 사람 같은 응답을 생성하죠.

동작 방식은 간단해요. 프롬프트나 대화의 일부를 AI 모델에 보내면, 모델이 훈련 데이터와 자연어 패턴 이해에 기반해 대화의 완성·연속을 생성하고, 완성된 응답이 애플리케이션에 돌아옵니다. 애플리케이션은 그 응답을 사용자에게 보여주거나 추가 처리에 씁니다.

Spring AI Chat Model API는 다양한 AI 모델과 상호작용하기 위한 단순하고 이식 가능한(portable) 인터페이스로 설계됐어요. 최소한의 코드 변경만으로 다른 모델로 전환할 수 있게 해주죠. 이 설계는 Spring의 모듈성·상호교환성 철학과 맞닿아 있어요. 입력을 캡슐화하는 Prompt 같은 동반 클래스와 출력을 처리하는 ChatResponse 덕분에, Chat Model API는 AI 모델과의 통신을 통일하고 요청 준비·응답 파싱의 복잡성을 관리해 직접적이고 단순한 API 상호작용을 제공합니다.

출처: 공식문서

API 개요

이 절에서는 Spring AI Chat Model API 인터페이스와 관련 클래스들을 안내해요.

ChatModel

public interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {

	default String call(String message) {...}

    @Override
	ChatResponse call(Prompt prompt);
}

String 파라미터를 받는 call() 메서드는 더 정교한 Prompt·ChatResponse 클래스의 복잡성을 피해 초기 사용을 단순화해요. 실제 애플리케이션에서는 Prompt 인스턴스를 받아 ChatResponse를 반환하는 call() 메서드를 더 자주 씁니다.

StreamingChatModel

public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {

    default Flux<String> stream(String message) {...}

    @Override
	Flux<ChatResponse> stream(Prompt prompt);
}

stream() 메서드는 ChatModel과 비슷하게 String이나 Prompt 파라미터를 받지만, reactive Flux API로 응답을 스트리밍해요.

Prompt

public class Prompt implements ModelRequest<List<Message>> {

    private final List<Message> messages;

    private ChatOptions modelOptions;

	@Override
	public ChatOptions getOptions() {...}

	@Override
	public List<Message> getInstructions() {...}

    // constructors and utility methods omitted
}

Message 인터페이스는 Prompt의 텍스트 콘텐츠, 메타데이터 속성 모음, MessageType으로 알려진 분류를 캡슐화해요. 인터페이스는 다음과 같이 정의됩니다.

public interface Content {

	String getText();

	Map<String, Object> getMetadata();
}

public interface Message extends Content {

	MessageType getMessageType();
}

멀티모달 메시지 타입은 Media 콘텐츠 객체 목록을 제공하는 MediaContent 인터페이스도 구현해요.

public interface MediaContent extends Content {

	Collection<Media> getMedia();

}

Message 인터페이스는 AI 모델이 처리할 수 있는 메시지 카테고리에 대응하는 여러 구현체를 갖고 있어요. 채팅 완성 엔드포인트는 대화 역할(conversational role)에 따라 메시지 카테고리를 구분하는데, MessageType이 이를 효과적으로 매핑합니다. 예를 들어 OpenAI는 system, user, function, assistant 같은 대화 역할에 대한 메시지 카테고리를 인식해요.

MessageType이 특정 메시지 포맷을 암시하는 것처럼 들릴 수 있지만, 이 문맥에서는 메시지가 대화에서 맡는 역할을 가리킨다는 점을 기억하세요. 특정 역할을 쓰지 않는 AI 모델의 경우 UserMessage 구현이 표준 카테고리로 동작하며, 보통 사용자가 만든 질문이나 지시를 나타내요. Prompt와 Message의 실질적 관계와 역할·메시지 카테고리를 이해하려면 Prompts 절의 상세 설명을 보면 돼요.

Chat Options

AI 모델에 전달할 수 있는 옵션을 나타내요. ChatOptions 클래스는 ModelOptions의 하위 클래스로, AI 모델에 전달할 수 있는 소수의 이식 가능한 옵션을 정의할 때 쓰입니다. ChatOptions 클래스는 다음과 같이 정의돼요.

public interface ChatOptions extends ModelOptions {

	String getModel();
	Double getFrequencyPenalty();
	Integer getMaxTokens();
	Double getPresencePenalty();
	List<String> getStopSequences();
	Double getTemperature();
	Integer getTopK();
	Double getTopP();
	ChatOptions.Builder<?> mutate();

}

또한 모델별 ChatModel/StreamingChatModel 구현체마다 AI 모델에 전달할 수 있는 전용 옵션을 가질 수 있어요. 예를 들어 OpenAI Chat Completion 모델은 logitBias, seed, user 같은 전용 옵션을 가집니다.

Spring AI는 Chat Model을 설정·사용하기 위한 정교한 시스템을 제공해요. 시작 시점에 기본 설정을 정해 두고, 요청별로 이 설정을 덮어쓸 수 있는 유연성을 제공하죠. 이 접근 덕분에 Spring AI가 제공하는 일관된 인터페이스 안에서 다양한 AI 모델을 쉽게 다루고 필요에 따라 파라미터를 조정할 수 있어요.

ChatModel.call() / ChatModel.stream()을 쓸 때 넘기는 prompt에는 모델에 설정된 옵션을 완전히 덮어쓸 옵션의 전체 집합이 담겨 있어야 합니다(또는 모델 기본값을 쓰려면 Prompt에 null 옵션을 사용). ChatClient 추상화는 요청별로 기본 옵션을 덮어쓰는 "델타" 커스터마이저를 제공하는 점진적 접근을 허용해요.

다음 흐름도는 Spring AI가 Chat Model을 설정·실행하는 방식을 보여줘요.

시작 시점 설정(Start-up Configuration) — ChatModel/StreamingChatModel이 "Start-Up" Chat Options로 초기화돼요. 이 옵션들은 ChatModel 초기화 시 설정되며 기본 설정을 제공하기 위한 거예요.
런타임 설정(Runtime Configuration) — 요청마다 Prompt가 Runtime Chat Options를 담을 수 있는데, 이 옵션들은 시작 시점 옵션을 완전히 덮어써요.
입력 처리(Input Processing) — "Convert Input" 단계가 입력 지시를 네이티브·모델별 포맷으로 변환해요.
출력 처리(Output Processing) — "Convert Output" 단계가 모델의 응답을 표준화된 ChatResponse 포맷으로 변환해요.

ChatResponse

ChatResponse 클래스의 구조는 다음과 같아요.

public class ChatResponse implements ModelResponse<Generation> {

    private final ChatResponseMetadata chatResponseMetadata;
	private final List<Generation> generations;

	@Override
	public ChatResponseMetadata getMetadata() {...}

    @Override
	public List<Generation> getResults() {...}

    // other methods omitted
}

ChatResponse 클래스는 AI 모델의 출력을 담아요. 각 Generation 인스턴스는 하나의 프롬프트에서 나온 잠재적 출력 여러 개 중 하나를 포함하죠. ChatResponse 클래스는 AI 모델 응답에 대한 메타데이터인 ChatResponseMetadata도 함께 담습니다.

Generation

마지막으로 Generation 클래스는 ModelResult를 확장해 모델 출력(어시스턴트 메시지)과 관련 메타데이터를 나타냅니다.

public class Generation implements ModelResult<AssistantMessage> {

	private final AssistantMessage assistantMessage;
	private ChatGenerationMetadata chatGenerationMetadata;

	@Override
	public AssistantMessage getOutput() {...}

	@Override
	public ChatGenerationMetadata getMetadata() {...}

    // other methods omitted
}

사용 가능한 구현체

통합 인터페이스인 ChatModel과 StreamingChatModel은 다양한 프로바이더의 AI 채팅 모델과 상호작용하는 데 쓰입니다. 클라이언트 애플리케이션에 일관된 API를 유지하면서 서로 다른 AI 서비스의 통합·전환을 쉽게 만들어 주죠.

OpenAI Chat Completion (스트리밍·멀티모달·함수 호출 지원)
Ollama Chat Completion (스트리밍·멀티모달·함수 호출 지원)
Mistral AI Chat Completion (스트리밍·함수 호출 지원)
Anthropic Chat Completion (스트리밍·함수 호출 지원)

Chat Model API

Spring AI Chat Model API는 Spring AI Generic Model API 위에 Chat 특화 추상화와 구현체를 얹어 만들어져요. 이 설계 덕분에 클라이언트 애플리케이션에 일관된 API를 유지하면서 서로 다른 AI 서비스의 통합·전환이 쉬워집니다.

더 알아보기

ChatClient API — 더 고급 플루언트 API로 같은 모델 위에서 작업하기
Prompts — Prompt·Message·PromptTemplate 자세히 보기
Tool Calling — 모델이 함수를 호출하도록 도구 연결하기
Structured Output — 결과를 타입 안전한 객체로 받기