Mistral AI 임베딩

Mistral AI 임베딩 (Mistral AI Embeddings)

Spring AI는 Mistral AI의 텍스트 임베딩 모델을 지원해요. 임베딩은 고차원 벡터 공간에서의 위치를 통해 문단의 의미를 포착하는 텍스트의 벡터 표현이에요. 이 글에서는 사용 가능한 모델, 의존성 설정, 런타임 옵션까지 알아볼게요.

출처: 문서

본문

Spring AI는 Mistral AI의 텍스트 임베딩 모델을 지원해요. 임베딩은 고차원 벡터 공간에서의 위치를 통해 문단의 의미적 의미를 포착하는 텍스트의 벡터 표현이에요. Mistral AI Embeddings API는 텍스트를 위한 최첨단의(state-of-the-art) 임베딩을 제공하며, 이는 많은 NLP 작업에 사용될 수 있어요.

Available Models

Mistral AI는 각각 다른 사용 사례에 최적화된 두 가지 임베딩 모델을 제공해요:

Model	Dimensions	Use Case	Description
mistral-embed	1024	General text	의미 검색, 클러스터링, 텍스트 유사도 작업에 적합한 범용 임베딩 모델. 자연어 콘텐츠에 이상적.
codestral-embed	1536	Code	코드 유사도, 코드 검색, 코드 저장소를 사용한 검색-증강 생성(RAG)에 최적화된 특수 임베딩 모델. 코드 의미를 이해하도록 특별히 설계된 더 고차원 임베딩을 제공해요.

모델을 선택할 때:

• 문서, 기사 또는 사용자 쿼리 같은 일반 텍스트 콘텐츠에는 mistral-embed를 사용하세요

• 코드, 기술 문서 작업, 또는 코드 인지(code-aware) RAG 시스템 구축 시에는 codestral-embed를 사용하세요

Prerequisites

MistralAI 임베딩 모델에 접근하려면 MistralAI로 API를 만들어야 해요.

MistralAI registration page에서 계정을 만들고 API Keys page에서 토큰을 생성하세요.

Spring AI 프로젝트는 spring.ai.mistralai.api-key라는 구성 프로퍼티를 정의하는데, 여기에 console.mistral.ai에서 얻은 API Key 값을 설정해야 해요.

이 구성 프로퍼티를 application.properties 파일에 설정할 수 있어요:

spring.ai.mistralai.api-key=<your-mistralai-api-key>

API 키 같은 민감한 정보를 다룰 때 보안을 강화하려면, Spring Expression Language(SpEL)를 사용해 환경 변수를 참조할 수 있어요:

# In application.yml
spring:
  ai:
    mistralai:
      api-key: ${MIST...KEY}

# In your environment or .env file
export MISTRALAI_API_KEY=<your-mistralai-api-key>

또한 애플리케이션 코드에서 프로그래밍 방식으로 이 구성을 설정할 수도 있어요:

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("MISTRALAI_API_KEY");

Add Repositories and BOM

Spring AI 아티팩트는 Maven Central과 Spring Snapshot 저장소에 게시돼요. 빌드 시스템에 이러한 저장소를 추가하려면 Artifact Repositories 섹션을 참고하세요.

의존성 관리를 돕기 위해 Spring AI는 프로젝트 전체에서 일관된 Spring AI 버전을 사용하도록 보장하는 BOM(bill of materials)을 제공해요. 빌드 시스템에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고하세요.

Auto-configuration

__	Spring AI 자동 설정과 스타터 모듈 아티팩트 이름에 큰 변경이 있었어요. 자세한 내용은 upgrade notes를 참고해주세요.

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

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

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

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

__	빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

Embedding Properties

Retry Properties

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

Property	Description	Default
spring.ai.retry.max-attempts	최대 재시도 횟수.	10
spring.ai.retry.backoff.initial-interval	지수 백오프 정책의 초기 대기 시간.	2 sec.
spring.ai.retry.backoff.multiplier	백오프 간격 배수.	5
spring.ai.retry.backoff.max-interval	최대 백오프 시간.	3 min.
spring.ai.retry.on-client-errors	false면 4xx 클라이언트 오류 코드에 대해 NonTransientAiException을 던지고 재시도하지 않음	false
spring.ai.retry.exclude-on-http-codes	재시도를 유발하지 않아야 하는 HTTP 상태 코드 목록 (예: NonTransientAiException을 던지기 위해).	empty
spring.ai.retry.on-http-codes	재시도를 유발해야 하는 HTTP 상태 코드 목록 (예: TransientAiException을 던지기 위해).	empty

Connection Properties

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

Property	Description	Default
spring.ai.mistralai.base-url	연결할 URL	api.mistral.ai
spring.ai.mistralai.api-key	API 키	-

Configuration Properties

__	임베딩 자동 설정의 활성화/비활성화는 이제 프리픽스 spring.ai.model.embedding이 붙은 최상위 프로퍼티로 설정해요. 활성화하려면 spring.ai.model.embedding=mistral (기본값으로 활성화됨). 비활성화하려면 spring.ai.model.embedding=none (또는 mistral과 일치하지 않는 어떤 값). 이 변경은 여러 모델의 설정을 허용하기 위한 것이에요.

프리픽스 spring.ai.mistralai.embedding은 MistralAI의 EmbeddingModel 구현을 구성하는 프로퍼티 프리픽스예요.

Property	Description	Default
spring.ai.mistralai.embedding.enabled (제거됨, 더 이상 유효하지 않음)	OpenAI 임베딩 모델 활성화.	true
spring.ai.model.embedding	OpenAI 임베딩 모델 활성화.	mistral
spring.ai.mistralai.embedding.base-url	선택적으로 spring.ai.mistralai.base-url을 재정의하여 임베딩 전용 URL 제공	-
spring.ai.mistralai.embedding.api-key	선택적으로 spring.ai.mistralai.api-key를 재정의하여 임베딩 전용 api-key 제공	-
spring.ai.mistralai.embedding.metadata-mode	문서 내용 추출 모드.	EMBED
spring.ai.mistralai.embedding.model	사용할 모델	mistral-embed
spring.ai.mistralai.embedding.encoding-format	임베딩을 반환할 형식. float 또는 base64 중 하나.	-

__	ChatModel과 EmbeddingModel 구현에 대해 공통 spring.ai.mistralai.base-url과 spring.ai.mistralai.api-key를 재정의할 수 있어요. spring.ai.mistralai.embedding.base-url과 spring.ai.mistralai.embedding.api-key 프로퍼티가 설정되면 공통 프로퍼티보다 우선해요. 마찬가지로 spring.ai.mistralai.chat.base-url과 spring.ai.mistralai.chat.api-key 프로퍼티가 설정되면 공통 프로퍼티보다 우선해요. 서로 다른 모델과 서로 다른 모델 엔드포인트에 서로 다른 MistralAI 계정을 사용하려 할 때 유용해요.

__	spring.ai.mistralai.embedding 프리픽스가 붙은 모든 프로퍼티는 런타임에 EmbeddingRequest 호출에 요청별 Runtime Options를 추가해 재정의할 수 있어요.

Runtime Options

MistralAiEmbeddingOptions.java는 사용할 모델 같은 MistralAI 구성을 제공해요.

기본 옵션은 spring.ai.mistralai.embedding 프로퍼티로도 구성할 수 있어요.

시작 시 MistralAiEmbeddingModel 생성자를 사용해 모든 임베딩 요청에 사용될 기본 옵션을 설정해요. 런타임에는 EmbeddingRequest의 일부로 MistralAiEmbeddingOptions 인스턴스를 사용해 기본 옵션을 재정의할 수 있어요.

예를 들어 특정 요청의 기본 모델 이름을 재정의하려면:

// Using mistral-embed for general text
EmbeddingResponse textEmbeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        MistralAiEmbeddingOptions.builder()
            .withModel("mistral-embed")
        .build()));

// Using codestral-embed for code
EmbeddingResponse codeEmbeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("public class HelloWorld {}", "def hello_world():"),
        MistralAiEmbeddingOptions.builder()
            .withModel("codestral-embed")
        .build()));

Sample Controller

이렇게 하면 클래스에 주입할 수 있는 EmbeddingModel 구현이 생성돼요. EmbeddingModel 구현을 사용하는 간단한 @Controller 클래스 예시예요:

spring.ai.mistralai.api-key=YOUR_API_KEY
spring.ai.mistralai.embedding.model=mistral-embed

@RestController
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        var embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

Manual Configuration

Spring Boot를 사용하지 않는다면 OpenAI Embedding Model을 수동으로 구성할 수 있어요. 이를 위해 프로젝트의 Maven pom.xml 파일에 spring-ai-mistral-ai 의존성을 추가하세요:

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

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

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

__	빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

__	spring-ai-mistral-ai 의존성은 MistralAiChatModel에도 접근할 수 있게 해줘요. MistralAiChatModel에 대한 자세한 내용은 MistralAI Chat Client 섹션을 참고하세요.

다음으로 MistralAiEmbeddingModel 인스턴스를 만들고 두 입력 텍스트 사이의 유사도를 계산하는 데 사용해요:

var mistralAiApi = new MistralAiApi(System.getenv("MISTRAL_AI_API_KEY"));

var embeddingModel = new MistralAiEmbeddingModel(this.mistralAiApi,
        MistralAiEmbeddingOptions.builder()
                .withModel("mistral-embed")
                .withEncodingFormat("float")
                .build());

EmbeddingResponse embeddingResponse = this.embeddingModel
        .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

MistralAiEmbeddingOptions는 임베딩 요청의 구성 정보를 제공해요. 옵션 클래스는 쉬운 옵션 생성을 위한 builder()를 제공해요.

더 알아보기 (Learn more)