Mistral AI 嵌入

Spring AI 支持 Mistral AI 的文本嵌入模型。 嵌入是文本的向量表示，通过它们在高维向量空间中的位置来捕获段落的语义含义。Mistral AI 嵌入 API 为文本提供了尖端、最先进的嵌入，可用于许多 NLP 任务。

前提条件

您需要使用 MistralAI 创建一个 API 才能访问 MistralAI 嵌入模型。

在 MistralAI 注册页面 创建帐户，并在 API 密钥页面 生成令牌。

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 表达式语言 (SpEL) 引用环境变量：

# 在 application.yml 中
spring:
  ai:
    mistralai:
      api-key: ${MISTRALAI_API_KEY}
# 在您的环境或 .env 文件中
export MISTRALAI_API_KEY=<your-mistralai-api-key>

您也可以在应用程序代码中以编程方式设置此配置：

// 从安全源或环境变量中检索 API 密钥
String apiKey = System.getenv("MISTRALAI_API_KEY");

添加仓库和 BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。 请参阅 工件仓库 部分以将这些仓库添加到您的构建系统。

为了帮助进行依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用的 Spring AI 版本一致。请参阅 依赖管理 部分以将 Spring AI BOM 添加到您的构建系统。

自动配置

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。 有关更多信息，请参阅 升级说明。

Spring AI 为 MistralAI 嵌入模型提供了 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 添加到您的构建文件。

嵌入属性

重试属性

前缀 spring.ai.retry 用作属性前缀，允许您配置 Mistral AI 嵌入模型的重试机制。

属性 描述 默认值

spring.ai.retry.max-attempts

最大重试次数。

10

spring.ai.retry.backoff.initial-interval

指数退避策略的初始休眠持续时间。

2 秒

spring.ai.retry.backoff.multiplier

退避间隔乘数。

5

spring.ai.retry.backoff.max-interval

最大退避持续时间。

3 分钟

spring.ai.retry.on-client-errors

如果为 false，则抛出 NonTransientAiException，并且不尝试对 4xx 客户端错误代码进行重试

false

spring.ai.retry.exclude-on-http-codes

不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。

空

spring.ai.retry.on-http-codes

应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。

空

连接属性

前缀 spring.ai.mistralai 用作属性前缀，允许您连接到 MistralAI。

属性 描述 默认值

spring.ai.mistralai.base-url

要连接的 URL

[role="bare"][role="bare"]https://api.mistral.ai

spring.ai.mistralai.api-key

API 密钥

-

配置属性

嵌入自动配置的启用和禁用现在通过前缀为 spring.ai.model.embedding 的顶级属性进行配置。 要启用，spring.ai.model.embedding=mistral（默认启用） 要禁用，spring.ai.model.embedding=none（或任何与 mistral 不匹配的值） 此更改是为了允许配置多个模型。

前缀 spring.ai.mistralai.embedding 是配置 MistralAI EmbeddingModel 实现的属性前缀。

属性 描述 默认值

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 密钥

-

spring.ai.mistralai.embedding.metadata-mode

文档内容提取模式。

EMBED

spring.ai.mistralai.embedding.options.model

要使用的模型

mistral-embed

spring.ai.mistralai.embedding.options.encodingFormat

返回嵌入的格式。可以是 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.options 的属性都可以在运行时通过向 EmbeddingRequest 调用添加请求特定的 运行时选项 来覆盖。

运行时选项

MistralAiEmbeddingOptions.java 提供了 MistralAI 配置，例如要使用的模型等。

默认选项也可以使用 spring.ai.mistralai.embedding.options 属性进行配置。

在启动时，使用 MistralAiEmbeddingModel 构造函数设置用于所有嵌入请求的默认选项。 在运行时，您可以使用 MistralAiEmbeddingOptions 实例作为 EmbeddingRequest 的一部分来覆盖默认选项。

例如，要覆盖特定请求的默认模型名称：

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

示例控制器

这将创建一个 EmbeddingModel 实现，您可以将其注入到您的类中。 这是一个使用 EmbeddingModel 实现的简单 @Controller 类的示例。

spring.ai.mistralai.api-key=YOUR_API_KEY
spring.ai.mistralai.embedding.options.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);
    }
}

手动配置

如果您不使用 Spring Boot，可以手动配置 OpenAI 嵌入模型。 为此，将 spring-ai-mistral-ai 依赖项添加到您项目的 Maven pom.xml 文件中：

<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 添加到您的构建文件。

spring-ai-mistral-ai 依赖项还提供对 MistralAiChatModel 的访问。 有关 MistralAiChatModel 的更多信息，请参阅 MistralAI 聊天客户端 部分。

接下来，创建一个 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() 以方便选项创建。