Ollama 임베딩 설정

Ollama를 쓰면 다양한 AI 모델을 로컬에서 실행하고 그 모델들로 임베딩을 생성할 수 있어요. 임베딩은 부동소수점 숫자의 벡터(목록)예요. 두 벡터 사이의 거리가 작을수록 연관성이 크고, 클수록 연관성이 작아요. OllamaEmbeddingModel 구현은 Ollama의 Embeddings API 엔드포인트를 활용해요.

출처: 공식문서

사전 준비 (Prerequisites)

먼저 Ollama 인스턴스에 접근할 수 있어야 해요. 몇 가지 방법이 있는데, 그중 대표적인 건 다음과 같아요.

Ollama 다운로드·설치 후 로컬 머신에서 실행
Testcontainers로 Ollama 구성·실행

애플리케이션에서 쓸 모델은 Ollama 모델 라이브러리에서 pull할 수 있어요.

ollama pull <model-name>

수천 개의 무료 GGUF Hugging Face 모델도 pull할 수 있어요.

자동 설정 (Auto-Configuration)

Spring AI는 Ollama 임베딩 모델에 대한 Spring Boot 자동 설정을 제공해요. 활성화하려면 Maven pom.xml 또는 Gradle build.gradle에 spring-ai-starter-model-ollama 의존성을 추가하면 돼요.

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

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

기본 프로퍼티 (Base Properties)

Ollama에 연결하는 설정은 spring.ai.ollama 프리픽스를 사용해요.

Ollama 통합 초기화와 모델 자동 pull 관련 프로퍼티예요.

임베딩 프로퍼티 (Embedding Properties)

임베딩 자동 설정의 켜고 끔은 spring.ai.model.embedding 프리픽스로 제어해요. 켜려면 spring.ai.model.embedding=ollama(기본값), 끄려면 spring.ai.model.embedding=none으로 설정하면 돼요.

Ollama 임베딩 모델을 설정하는 프리픽스는 spring.ai.ollama.embedding 이에요. model, keep-alive, truncate 같은 Ollama 요청(고급) 파라미터와 Ollama 모델 프로퍼티를 포함해요.

나머지 options 프로퍼티는 Ollama Valid Parameters and Values와 Ollama Types에 기반해요.

spring.ai.ollama.embedding으로 시작하는 모든 프로퍼티는 런타임 옵션을 EmbeddingRequest 호출에 추가해 실행 시점에 덮어쓸 수 있어요.

런타임 옵션 (Runtime Options)

OllamaEmbeddingOptions.java는 사용할 모델, 저수준 GPU·CPU 튜닝 등 Ollama 구성을 제공해요.

참고: OllamaOptions 클래스는 deprecated 됐어요. 채팅 모델에는 OllamaChatOptions, 임베딩 모델에는 OllamaEmbeddingOptions를 사용하세요. 두 새 클래스는 타입 안전한 모델별 설정 옵션을 제공해요.

기본 옵션은 spring.ai.ollama.embedding 프로퍼티로 설정할 수 있어요. 시작 시점에는 OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaEmbeddingOptions options)으로 모든 임베딩 요청의 기본 옵션을 설정하고, 런타임에는 OllamaEmbeddingOptions 인스턴스를 EmbeddingRequest의 일부로 사용해 덮어쓸 수 있어요.

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("Different-Embedding-Model-Deployment-Name"))
            .truncates(false)
            .build());

모델 자동 풀 (Auto-pulling Models)

시작 시 모델을 자동으로 pull하도록 설정할 수 있어요.

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        embedding:
          additional-models:
            - mxbai-embed-large
            - nomic-embed-text

pull 전략을 특정 타입의 모델에만 적용하고 싶으면 임베딩 모델을 초기화 작업에서 제외할 수도 있어요.

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        embedding:
          include: false

이렇게 하면 임베딩 모델을 제외한 모든 모델에 pull 전략이 적용돼요.

HuggingFace 모델

Ollama는 기본적으로 모든 GGUF Hugging Face 임베딩 모델에 접근할 수 있어요. 이름으로 아무 모델이나 pull할 수 있고(ollama pull hf.co/<username>/<model-repository>), 자동 pull 전략으로도 설정할 수 있어요.

spring.ai.ollama.embedding.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=always

spring.ai.ollama.embedding.model: 사용할 Hugging Face GGUF 모델을 지정
spring.ai.ollama.init.pull-model-strategy=always: (선택) 시작 시 모델 자동 pull 활성화

프로덕션에서는 지연을 피하기 위해 모델을 미리 다운로드해 두는 게 좋아요: ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1

수동 설정 (Manual Configuration)

Spring Boot를 쓰지 않는다면 OllamaEmbeddingModel을 직접 구성할 수 있어요. spring-ai-ollama 의존성을 Maven pom.xml 또는 Gradle build.gradle에 추가하면 돼요.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>

dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama'
}

spring-ai-ollama 의존성은 OllamaChatModel에도 접근할 수 있게 해줘요. 그런 다음 OllamaEmbeddingModel 인스턴스를 만들고 두 입력 텍스트의 임베딩을 계산해요.

var ollamaApi = OllamaApi.builder().build();

var embeddingModel = new OllamaEmbeddingModel(this.ollamaApi,
        OllamaEmbeddingOptions.builder()
			.model(OllamaModel.MISTRAL.id())
            .build());

EmbeddingResponse embeddingResponse = this.embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("chroma/all-minilm-l6-v2-f32"))
            .truncate(false)
            .build());

OllamaEmbeddingOptions는 모든 임베딩 요청에 대한 설정 정보를 제공해요.

Ollama 임베딩 설정