[Spring AI 2025 Renewal #4] Chat Models & Image Models

안녕하세요 dev_writer입니다.

 

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

 

Chat Models

Chat Model API는 개발자가 AI 기반의 채팅 완성 기능을 애플리케이션에 통합할 수 있도록 지원합니다. 이 API는 GPT (Generative Pre-trained Transformer)와 같은 사전 학습된 언어 모델을 활용하여, 사용자 입력에 대해 자연어로 인간과 유사한 응답을 생성합니다.

 

이 API는 일반적으로 프롬프트 또는 대화의 일부를 AI 모델에 전송하면, 모델이 학습된 데이터와 자연어 패턴에 대한 이해를 바탕으로 대화를 이어나가거나 완성하는 방식으로 작동합니다. 생성된 응답은 애플리케이션에 반환되며, 이를 사용자에게 표시하거나 추가 처리에 사용할 수 있습니다.

 

Spring AI의 Chat Model API는 다양한 AI 모델과의 상호작용을 위한 단순하고 이식 가능한 인터페이스로 설계되었습니다. 이러한 설계는 Spring의 모듈화 및 교체 가능성이라는 철학과 일치하며, 개발자가 최소한의 코드 변경만으로 서로 다른 AI 모델 간 전환이 가능하도록 합니다.

 

또한, 입력을 캡슐화하는 Prompt 클래스와 출력을 처리하는 ChatResponse와 같은 보조 클래스의 도움을 받아, Chat Model API는 AI 모델과의 통신을 통합된 방식으로 제공합니다. 이로 인해 요청 준비 및 응답 파싱의 복잡성을 관리하며, 개발자에게 직관적이고 단순화된 API 인터페이스를 제공합니다.

 

구현 가능한 모델 목록은 이용 가능한 구현체 섹션에서, 그리고 각 모델에 대한 자세한 비교는 Chat Models Comparison 섹션에서 확인할 수 있습니다.

 

API 개요

이 섹션은 Spring AI Chat Model API 인터페이스와 관련 클래스들에 대한 가이드를 제공합니다.

ChatModel

다음은 ChatModel 인터페이스의 정의입니다.

public interface ChatModel extends Model<Prompt, ChatResponse> {

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

    @Override
    ChatResponse call(Prompt prompt);
}

 

String 매개변수를 사용하는 call() 메서드는 초기 사용을 간소화하며, 보다 정교한 Prompt 및 ChatResponse 클래스를 사용하는 복잡성을 피할 수 있습니다.

 

하지만 실제 애플리케이션에서는 Prompt 인스턴스를 전달하고 ChatResponse를 반환하는 call() 메서드를 사용하는 경우가 더 일반적입니다.

StreamingChatModel

다음은 StreamingChatModel 인터페이스의 정의입니다.

public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {

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

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

 

stream() 메서드는 ChatModel과 유사하게 String 또는 Prompt 매개변수를 받아들이지만, 응답을 리액티브 Flux API를 통해 스트리밍 방식으로 처리합니다.

Prompt

Prompt는 하나의 ModelRequest로, 여러 개의 Message 객체와 선택적인 모델 요청 옵션을 캡슐화합니다.

다음 예시는 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() {...}

    // 생성자 및 유틸리티 메서드는 생략
}

Message

Message 인터페이스는 Prompt의 텍스트 콘텐츠, 메타데이터 속성의 컬렉션, 그리고 MessageType이라고 불리는 분류 정보를 캡슐화합니다. 해당 인터페이스는 다음과 같이 정의됩니다.

public interface Content {

    String getText();

    Map<String, Object> getMetadata();
}

public interface Message extends Content {

    MessageType getMessageType();
}

 

멀티 모달 메시지 타입은 MediaContent 인터페이스도 구현하며, 여러 개의 Media 콘텐츠 객체 목록을 제공합니다.

public interface MediaContent extends Content {

    Collection<Media> getMedia();

}

 

Message 인터페이스는 AI 모델이 처리할 수 있는 메시지의 카테고리에 따라 다양한 구현체를 제공합니다.

출처: Spring AI 공식 문서

 

Chat Completion 엔드포인트는 대화에서의 역할에 따라 메시지 유형을 구분하며, 이는 MessageType을 통해 효과적으로 매핑됩니다.

 

예를 들어, OpenAI는 시스템 (system), 사용자(user), 함수(function), 어시스턴트(assistant)와 같은 특정 대화 역할에 따른 메시지 유형을 인식합니다.

 

MessageType이라는 용어는 특정 메시지 포맷을 의미하는 것처럼 보일 수 있지만, 이 문맥에서는 대화에서 해당 메시지가 수행하는 역할을 나타냅니다.

 

특정 역할을 사용하지 않는 AI 모델의 경우, UserMessage 구현체가 표준 메시지 유형으로 작동하며, 일반적으로 사용자로부터 입력된 질문이나 명령을 나타냅니다.

 

이러한 역할 또는 메시지 유형의 맥락에서 Prompt와 Message 간의 관계 및 실질적인 적용 방식에 대해서는 Prompts 섹션에서 자세히 설명하고 있습니다.

ChatOptions

AI 모델에 전달할 수 있는 옵션들을 나타내는 클래스입니다. ChatOptions 클래스는 ModelOptions의 하위 클래스이며, AI 모델에 전달 가능한 몇 가지 이식 가능한 (portable) 옵션들을 정의하는 데 사용됩니다.

 

ChatOptions 클래스는 다음과 같이 정의됩니다.

public interface ChatOptions extends ModelOptions {

    String getModel();
    Float getFrequencyPenalty();
    Integer getMaxTokens();
    Float getPresencePenalty();
    List<String> getStopSequences();
    Float getTemperature();
    Integer getTopK();
    Float getTopP();
    ChatOptions copy();

}

 

또한, 각 AI 모델에 특화된 ChatModel 또는 StreamingChatModel 구현체는 모델 고유의 옵션들을 가질 수 있으며, 이를 AI 모델에 전달할 수 있습니다. 예를 들어, OpenAI Chat Completion 모델은 logitBias, seed, user와 같은 고유 옵션들을 제공합니다.

 

이러한 기능은 개발자가 애플리케이션 시작 시에 모델별 옵션을 설정하고, 실행 중에는 Prompt 요청을 통해 동적으로 덮어쓸 수 있게 해 주는 강력한 기능입니다.

 

Spring AI는 Chat Model을 구성하고 활용하기 위한 정교한 시스템을 제공합니다. 애플리케이션 시작 시 기본 구성을 설정할 수 있을 뿐 아니라, 요청 단위로 이 설정들을 유연하게 재정의할 수 있습니다.

 

이러한 접근 방식은 개발자가 다양한 AI 모델과 손쉽게 연동하고, 필요에 따라 파라미터를 조정할 수 있도록 하며, 이 모든 과정을 Spring AI 프레임워크의 일관된 인터페이스 내에서 처리할 수 있게 합니다.

 

아래의 플로우 다이어그램은 Spring AI가 Chat Model의 설정 및 실행을 어떻게 처리하는지를 시각적으로 설명하며, 시작 시 설정과 실행 중 옵션을 어떻게 결합하는지를 보여줍니다.

출처: Spring AI 공식 문서

1. 애플리케이션 시작 시 설정 (Start-up Configuration): ChatModel 또는 StreamingChatModel은 "시작 시 (Start-Up)" 채팅 옵션으로 초기화됩니다. 이러한 옵션은 ChatModel 초기화 시에 설정되며, 기본 구성값을 제공하기 위한 목적입니다.
2. 실행 시 설정 (Runtime Configuration): 각 요청마다 Prompt 객체에 실행 시 (Runtime) 채팅 옵션을 포함시킬 수 있으며, 이 옵션들은 시작 시 설정된 값을 재정의 (override)할 수 있습니다.
3. 옵션 병합 과정 (Option Merging Process): "Merge Options" 단계에서는 시작 시 설정과 실행 시 설정을 병합합니다. 실행 시 옵션이 제공되면, 시작 시 옵션보다 우선 적용됩니다.
4. 입력 처리 (Input Processing): "Convert Input" 단계에서는 입력된 지시사항 (instructions)을 모델 고유의 형식으로 변환합니다.
5. 출력 처리 (Output Processing): "Convert Output" 단계에서는 AI 모델의 응답을 표준화된 ChatResponse 형식으로 변환합니다.

시작 시 옵션과 실행 시 옵션을 분리함으로써, 전역 설정 (Global Configuration)과 요청 단위의 세부 조정 (Request-specific Customization)을 동시에 유연하게 지원할 수 있습니다.

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() {...}

    // 다른 메서드들은 생략
}

 

ChatResponse 클래스는 AI 모델의 출력 결과를 보유하며, 각 Generation 인스턴스는 하나의 프롬프트에 대해 생성된 하나 이상의 출력 중 하나를 나타냅니다. 또한, ChatResponse 클래스는 AI 모델의 응답에 대한 메타데이터를 담고 있는 ChatResponseMetadata 객체도 함께 포함하고 있습니다.

Generation

마지막으로, Generation 클래스는 ModelResult를 상속하여 모델의 출력(assistant 메시지) 및 관련 메타데이터를 나타냅니다.

public class Generation implements ModelResult<AssistantMessage> {

	private final AssistantMessage assistantMessage;
	private ChatGenerationMetadata chatGenerationMetadata;

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

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

    // 다른 메서드들은 생략
}

이용 가능한 구현체

이 다이어그램은 ChatModel과 StreamingChatModel이라는 통합 인터페이스가 다양한 AI 제공업체의 채팅 모델과 상호작용하는 데 사용됨을 보여줍니다. 이를 통해 클라이언트 애플리케이션에서는 일관된 API를 유지하면서도, 서로 다른 AI 서비스 간의 손쉬운 통합 및 전환이 가능해집니다.

출처: Spring AI 공식 문서

• OpenAI Chat Completion (스트리밍, 멀티 모달 & 함수 호출 지원)
• Microsoft Azure Open AI Chat Completion (스트리밍 & 함수 호출 지원)
• Ollama Chat Completion (스트리밍, 멀티 모달 & 함수 호출 지원)
• Hugging Face Chat Completion (스트리밍 지원 X)
• Google Vertex AI Gemini Chat Completion (스트리밍, 멀티 모달 & 함수 호출 지원)
• Amazon Bedrock
• Mistral AI Chat Completion (스트리밍 & 함수 호출 지원)
• Anthropic Chat Model (스트리밍 & 함수 호출 지원)

팁
채팅 모델 비교 섹션에서 사용 가능한 채팅 모델에 대한 자세한 비교를 찾아보세요.

Chat Model API

Spring AI Chat Model API는 Spring AI의 Generic Model API 위에 구축되어 있으며, 채팅 기능에 특화된 추상화 및 구현체를 제공합니다.

이로 인해 클라이언트 애플리케이션은 일관된 API를 유지하면서도 다양한 AI 서비스 간의 통합 및 전환을 손쉽게 수행할 수 있습니다.

출처: Spring AI 공식 문서

---

Image Models

Spring Image Model API는 이미지 생성에 특화된 다양한 AI 모델들과 상호작용하기 위한 단순하고 이식 가능한 인터페이스로 설계되었습니다.

 

이를 통해 개발자는 최소한의 코드 변경만으로 서로 다른 이미지 관련 모델 간에 전환할 수 있으며, 이러한 설계는 Spring의 모듈화 (Modularity) 및 교체 가능성 (Interchangeability) 철학과 부합합니다. 즉, 이미지 처리와 관련된 다양한 AI 기능에 애플리케이션을 빠르게 적응시킬 수 있도록 지원합니다.

 

또한, ImagePrompt (입력 캡슐화용), ImageResponse (출력 처리용)와 같은 보조 클래스의 지원을 통해, Image Model API는 이미지 생성 전용 AI 모델들과의 통신을 통합된 방식으로 관리합니다.

 

요청 준비 및 응답 파싱의 복잡성을 감추고, 직관적이고 간단한 API 기반의 이미지 생성 기능을 제공합니다.

 

Spring Image Model API는 Spring AI Generic Model API 위에 구축되어 있으며, 이미지 전용 기능을 위한 추상화 및 구현체를 제공합니다.

 

API 개요

이 섹션에서는 Spring Image Model API 인터페이스 및 관련 클래스에 대한 가이드를 제공합니다.

Image Model

아래는 ImageModel 인터페이스의 정의입니다.

@FunctionalInterface
public interface ImageModel extends Model<ImagePrompt, ImageResponse> {

    ImageResponse call(ImagePrompt request);

}

ImagePrompt

ImagePrompt는 여러 개의 ImageMessage 객체와 선택적인 모델 요청 옵션들을 캡슐화하는 ModelRequest입니다. 다음 예시는 생성자 및 기타 유틸리티 메서드를 제외한 ImagePrompt 클래스의 축약된 버전을 보여줍니다.

public class ImagePrompt implements ModelRequest<List<ImageMessage>> {

    private final List<ImageMessage> messages;

    private ImageOptions imageModelOptions;

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

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

    // 생성자 및 유틸리티 메서드는 생략
}

ImageMessage

ImageMessage 클래스는 이미지 생성에 사용될 텍스트와, 그 텍스트가 "생성 이미지에 미치는 영향력(가중치)"을 캡슐화합니다. 가중치를 지원하는 모델의 경우, 이 값은 양수 또는 음수로 설정될 수 있습니다.

public class ImageMessage {

    private String text;

    private Float weight;

    public String getText() {...}

    public Float getWeight() {...}

    // 생성자 및 유틸리티 메서드는 생략
}

ImageOptions

이미지 생성 모델에 전달할 수 있는 옵션들을 나타내는 인터페이스입니다. ImageOptions 인터페이스는 ModelOptions 인터페이스를 확장하며, AI 모델에 전달할 수 있는 일부 이식 가능한 (portable) 옵션들을 정의하는 데 사용됩니다.

 

ImageOptions 인터페이스는 다음과 같이 정의됩니다.

public interface ImageOptions extends ModelOptions {

    Integer getN();

    String getModel();

    Integer getWidth();

    Integer getHeight();

    String getResponseFormat(); // openai: url 또는 base64, stability ai: byte[] 또는 base64

}

 

또한, 각 AI 모델에 특화된 ImageModel 구현체는 모델 고유의 옵션들을 가질 수 있으며, 이러한 옵션들을 AI 모델에 전달할 수 있습니다.

 

예를 들어, OpenAI의 이미지 생성 모델은 quality, style 등과 같은 고유 옵션들을 제공합니다.

 

이 기능은 애플리케이션 시작 시 모델 별 옵션을 설정하고, 실행 중에는 ImagePrompt를 통해 해당 옵션들을 동적으로 재정의(override) 할 수 있도록 지원하는 강력한 기능입니다.

 

ImageResponse

ImageResponse 클래스의 구조는 다음과 같습니다.

public class ImageResponse implements ModelResponse<ImageGeneration> {

    private final ImageResponseMetadata imageResponseMetadata;

    private final List<ImageGeneration> imageGenerations;

    @Override
    public ImageGeneration getResult() {
        // 첫 번째 결과를 가져옴
    }

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

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

    // 다른 메서드들은 생략

}

 

ImageResponse 클래스는 AI 모델의 출력 결과를 가지며, 각 ImageGeneration 인스턴스는 하나의 프롬프트로부터 생성된 복수의 출력 중 하나를 나타냅니다.

 

또한, ImageResponse 클래스는 AI 모델 응답에 대한 메타데이터를 담고 있는 ImageResponseMetadata 객체도 포함하고 있습니다.

ImageGeneration

마지막으로 ImageGeneration 클래스는 ModelResult에서 확장되어 이 결과에 대한 출력 응답 및 관련 메타데이터를 나타냅니다.

public class ImageGeneration implements ModelResult<Image> {

    private ImageGenerationMetadata imageGenerationMetadata;

    private Image image;

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

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

    // 다른 메서드들은 생략

}

이용 가능한 구현체

ImageModel 구현은 다음 모델 공급자를 위해 사용됩니다.

• OpenAI Image Generation
• Azure OpenAI Image Generation
• QianFan Image Generation
• StabilityAI Image Generation
• ZhiPuAI Image Generation

API 문서

여기에서 Javadoc을 볼 수 있습니다.

 

Reference

• Spring AI : Chat Model API
• Spring AI : Image Model API