Mistral AI

= Mistral AI Embeddings

Spring AI supports the Mistral AI’s text embeddings models.
Embeddings are vectorial representations of text that capture the semantic meaning of paragraphs through their position in a high dimensional vector space. Mistral AI Embeddings API offers cutting-edge, state-of-the-art embeddings for text, which can be used for many NLP tasks.

== Prerequisites

You will need to create an API with MistralAI to access MistralAI embeddings models.

Create an account at https://auth.mistral.ai/ui/registration[MistralAI registration page] and generate the token on the https://console.mistral.ai/api-keys/[API Keys page].
The Spring AI project defines a configuration property named spring.ai.mistralai.api-key that you should set to the value of the API Key obtained from console.mistral.ai.
Exporting an environment variable is one way to set that configuration property:

[source,shell]

export SPRING_AI_MISTRALAI_API_KEY=

=== Add Repositories and BOM

Spring AI artifacts are published in Spring Milestone and Snapshot repositories. Refer to the xref:getting-started.adoc#repositories[Repositories] section to add these repositories to your build system.

To help with dependency management, Spring AI provides a BOM (bill of materials) to ensure that a consistent version of Spring AI is used throughout the entire project. Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build system.

== Auto-configuration

Spring AI provides Spring Boot auto-configuration for the MistralAI Embedding Client.
To enable it add the following dependency to your project’s Maven pom.xml file:

[source, xml]

or to your Gradle build.gradle build file.

[source,groovy]

dependencies {
implementation ‘org.springframework.ai:spring-ai-mistral-ai-spring-boot-starter’

}

TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.

=== Embedding Properties

==== Retry Properties

The prefix spring.ai.retry is used as the property prefix that lets you configure the retry mechanism for the Mistral AI Embedding client.

[cols=”3,5,1”]
|====
| Property | Description | Default

| spring.ai.retry.max-attempts | Maximum number of retry attempts. | 10
| spring.ai.retry.backoff.initial-interval | Initial sleep duration for the exponential backoff policy. | 2 sec.
| spring.ai.retry.backoff.multiplier | Backoff interval multiplier. | 5
| spring.ai.retry.backoff.max-interval | Maximum backoff duration. | 3 min.
| spring.ai.retry.on-client-errors | If false, throw a NonTransientAiException, and do not attempt retry for 4xx client error codes | false
| spring.ai.retry.exclude-on-http-codes | List of HTTP status codes that should not trigger a retry (e.g. to throw NonTransientAiException). | empty
|====

==== Connection Properties

The prefix spring.ai.mistralai is used as the property prefix that lets you connect to MistralAI.

[cols=”3,5,1”]
|====
| Property | Description | Default

| spring.ai.mistralai.base-url | The URL to connect to | https://api.mistral.ai
| spring.ai.mistralai.api-key | The API Key | -
|====

==== Configuration Properties

The prefix spring.ai.mistralai.embedding is property prefix that configures the EmbeddingClient implementation for MistralAI.

[cols=”3,5,1”]
|====
| Property | Description | Default

| spring.ai.mistralai.embedding.enabled | Enable OpenAI embedding client. | true
| spring.ai.mistralai.embedding.base-url | Optional overrides the spring.ai.mistralai.base-url to provide embedding specific url | -
| spring.ai.mistralai.embedding.api-key | Optional overrides the spring.ai.mistralai.api-key to provide embedding specific api-key | -
| spring.ai.mistralai.embedding.metadata-mode | Document content extraction mode. | EMBED
| spring.ai.mistralai.embedding.options.model | The model to use | mistral-embed
| spring.ai.mistralai.embedding.options.encodingFormat | The format to return the embeddings in. Can be either float or base64. | -
|====

NOTE: You can override the common spring.ai.mistralai.base-url and spring.ai.mistralai.api-key for the ChatClient and EmbeddingClient implementations.
The spring.ai.mistralai.embedding.base-url and spring.ai.mistralai.embedding.api-key properties if set take precedence over the common properties.
Similarly, the spring.ai.mistralai.embedding.base-url and spring.ai.mistralai.embedding.api-key properties if set take precedence over the common properties.
This is useful if you want to use different MistralAI accounts for different models and different model endpoints.

TIP: All properties prefixed with spring.ai.mistralai.embedding.options can be overridden at runtime by adding a request specific <> to the EmbeddingRequest call.

=== Embedding Options [[embedding-options]]

The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/MistralAiEmbeddingOptions.java[MistralAiEmbeddingOptions.java] provides the MistralAI configurations, such as the model to use and etc.

The default options can be configured using the spring.ai.mistralai.embedding.options properties as well.

At start-time use the MistralAiEmbeddingClient constructor to set the default options used for all embedding requests.
At run-time you can override the default options, using a MistralAiEmbeddingOptions instance as part of your EmbeddingRequest.

For example to override the default model name for a specific request:

[source,java]

EmbeddingResponse embeddingResponse = embeddingClient.call(
new EmbeddingRequest(List.of(“Hello World”, “World is big and salvation is near”),
MistralAiEmbeddingOptions.builder()
.withModel(“Different-Embedding-Model-Deployment-Name”)

    .build()));

=== Sample Controller (Auto-configuration)

This will create a EmbeddingClient implementation that you can inject into your class.
Here is an example of a simple @Controller class that uses the EmbeddingClient implementation.

[source,application.properties]

spring.ai.mistralai.api-key=YOUR_API_KEY

spring.ai.mistralai.embedding.options.model=mistral-embed

[source,java]

@RestController
public class EmbeddingController {

private final EmbeddingClient embeddingClient;

@Autowired
public EmbeddingController(EmbeddingClient embeddingClient) {
    this.embeddingClient = embeddingClient;
}

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

}

== Manual Configuration

If you are not using Spring Boot, you can manually configure the OpenAI Embedding Client.
For this add the spring-ai-mistralai dependency to your project’s Maven pom.xml file:

[source, xml]

or to your Gradle build.gradle build file.

[source,groovy]

dependencies {
implementation ‘org.springframework.ai:spring-ai-mistralai’

}

TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.

NOTE: The spring-ai-mistralai dependency provides access also to the MistralAiChatClient.
For more information about the MistralAiChatClient refer to the link:../clients/mistralai-chat.html[MistralAI Chat Client] section.

Next, create an MistralAiEmbeddingClient instance and use it to compute the similarity between two input texts:

[source,java]

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

var embeddingClient = new MistralAiEmbeddingClient(mistralAiApi,
MistralAiEmbeddingOptions.builder()
.withModel(“mistral-embed”)
.withEncodingFormat(“float”)
.build());

EmbeddingResponse embeddingResponse = embeddingClient

    .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

The MistralAiEmbeddingOptions provides the configuration information for the embedding requests.
The options class offers a builder() for easy options creation.