Mistral AI 嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Spring AI 支持 Mistral AI 的文本嵌入模型。嵌入是通过高维向量空间中的位置捕捉段落语义的向量化表示。Mistral AI Embeddings API 提供最先进的文本嵌入技术，适用于多种自然语言处理任务。

先决条件

你需要创建 Mistral AI API 以访问其嵌入模型。

请前往 Mistral AI 注册页面 创建账户，并在 API Key 页面生成访问令牌。

Spring AI 项目定义了名为 spring.ai.mistralai.api-key 的配置属性，需设置为从 console.mistral.ai 获取的 API Key 值。

你可以在 application.properties 文件中配置此属性：

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

为提升 API Key 等敏感信息的安全性，可使用 Spring 表达式语言（SpEL）引用环境变量：

# In application.yml
spring:
  ai:
    mistralai:
      api-key: ${MISTRALAI_API_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");

添加仓库和 BOM

Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。请参考 “Artifact 仓库” 部分，将这些仓库添加到你的构建系统中。

为了便于依赖管理，Spring AI 提供了一个 BOM，以确保在整个项目中使用一致的 Spring AI 版本。请参考 “依赖管理” 部分，将 Spring AI BOM 添加到你的构建系统中。

自动配置

Spring AI 的自动配置和 starter 模块的构件名称发生了重大变化。请参阅 升级说明 以获取更多信息。

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 sec.

spring.ai.retry.backoff.multiplier

退避间隔乘数。

5

spring.ai.retry.backoff.max-interval

最大退避时长。

3 min.

spring.ai.retry.on-client-errors

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

false

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

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

empty

spring.ai.retry.on-http-codes

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

empty

连接配置

前缀 spring.ai.mistralai 用作属性前缀，用于配置与 MistralAI 的连接。

属性 说明 默认值

spring.ai.mistralai.base-url

要连接到的 URL

api.mistral.ai

spring.ai.mistralai.api-key

API Key

-

配置属性

启用和禁用嵌入自动配置现在通过以 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 嵌入模型。

true

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.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 构造函数设置所有嵌入请求所使用的默认选项。在运行时，可以通过在 EmbeddingRequest 中使用 MistralAiEmbeddingOptions 实例来覆盖默认选项。

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

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()));

示例 Controller

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

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，可以手动配置 MistralAI 嵌入模型。为此，请将 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() 方法，便于选项的创建。