Docker Model Runner 채팅

Docker Model Runner 채팅 (Docker Model Runner Chat)

Docker Model Runner는 다양한 제공자의 광범위한 모델을 제공하는 AI 추론 엔진이에요. Spring AI는 기존의 OpenAI 기반 ChatClient를 재사용해 Docker Model Runner와 통합해요. base URL을 localhost:12434/engines/v1로 설정하고 제공되는 LLM 모델 중 하나를 선택하면 되죠. 이 글에서는 Docker Model Runner를 활성화하고 Spring AI와 함께 사용하는 방법을 알아볼게요.

출처: 문서

본문

Docker Model Runner는 다양한 제공자의 광범위한 모델을 제공하는 AI 추론 엔진(AI Inference Engine)이에요.

Spring AI는 기존 OpenAI 기반 ChatClient를 재사용해 Docker Model Runner와 통합해요. 이를 위해 base URL을 [localhost:12434/engines/v1](<http://localhost:12434/engines/v1>)로 설정하고 제공되는 LLM 모델 중 하나를 선택하세요.

Spring AI와 함께 Docker Model Runner를 사용하는 예제는 DockerModelRunnerWithOpenAiChatModelIT.java 테스트를 확인해보세요.

Prerequisite

• Mac용 Docker Desktop 4.40.0을 다운로드하세요.

다음 옵션 중 하나를 선택해 Model Runner를 활성화하세요:

Option 1:

• Model Runner 활성화 docker desktop enable model-runner --tcp 12434.

• base-url을 [localhost:12434/engines/v1](<http://localhost:12434/engines/v1>)로 설정하세요

Option 2:

• Model Runner 활성화 docker desktop enable model-runner.

• Testcontainers를 사용하고 base-url을 다음과 같이 설정하세요:

  @Container private static final DockerModelRunnerContainer DMR = new DockerModelRunnerContainer("alpine/socat:1.7.4.3-r0");

  @Bean public OpenAiChatModel chatModel() { var baseUrl = DMR.getOpenAIEndpoint(); return OpenAiChatModel.builder() .options(OpenAiChatOptions.builder().baseUrl(baseUrl).apiKey("test").build()) .build(); }

Docker Model Runner에 대해 더 자세히 알고 싶다면 Run LLMs Locally with Docker 블로그 글을 읽어보세요.

Auto-configuration

Spring AI는 OpenAI Chat Client에 대한 Spring Boot 자동 설정을 제공해요. 활성화하려면 프로젝트의 Maven pom.xml 파일에 다음 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 다음을 추가할 수도 있어요:

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

Chat Properties

Retry Properties

프리픽스 spring.ai.retry는 OpenAI 채팅 모델의 재시도 메커니즘을 구성할 수 있게 해주는 프로퍼티 프리픽스예요.

Connection Properties

프리픽스 spring.ai.openai는 OpenAI에 연결할 수 있게 해주는 프로퍼티 프리픽스예요.

Configuration Properties

프리픽스 spring.ai.openai.chat은 OpenAI의 채팅 모델 구현을 구성할 수 있게 해주는 프로퍼티 프리픽스예요.

Runtime Options

OpenAiChatOptions.java는 사용할 모델, temperature, frequency penalty 등 모델 구성을 제공해요.

시작 시 기본 옵션은 OpenAiChatModel(api, options) 생성자나 spring.ai.openai.chat.* 프로퍼티로 구성할 수 있어요.

런타임에는 Prompt 호출에 새 요청별 옵션을 추가해 기본 옵션을 재정의할 수 있어요. 예를 들어 특정 요청의 기본 모델과 temperature를 재정의하려면:

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OpenAiChatOptions.builder()
            .model("ai/gemma3:4B-F16")
        .build()
    ));

Tool Calling

Docker Model Runner는 선택한 모델이 지원할 때 툴 호출을 지원해요. Spring AI가 툴 실행 루프를 처리해요.

대부분의 애플리케이션에서는 자동 등록된 ToolCallingAdvisor와 함께 ChatClient를 사용하세요 — Tool Calling 참고. 루프를 직접 제어하는 저수준 제어가 필요하다면 ChatModel Tool Calling을 참고하세요.

Sample Controller

새 Spring Boot 프로젝트를 만들고, pom(또는 gradle) 의존성에 spring-ai-starter-model-openai를 추가하세요.

src/main/resources 디렉터리 아래에 application.properties 파일을 추가해 OpenAi 채팅 모델을 활성화하고 구성해요:

spring.ai.openai.api-key=test
spring.ai.openai.base-url=http://localhost:12434/engines/v1
spring.ai.openai.chat.model=ai/gemma3:4B-F16

# Docker Model Runner doesn't support embeddings, so we need to disable them.
spring.ai.model.embedding=none

채팅 모델을 텍스트 생성에 사용하는 간단한 @Controller 클래스 예시예요:

@RestController
public class ChatController {

    private final OpenAiChatModel chatModel;

    @Autowired
    public ChatController(OpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

더 알아보기 (Learn more)