21_Spring AI 干货笔记之 Mistral AI 聊天

一、Mistral AI 聊天

Spring AI 支持来自 Mistral AI 的各种 AI 语言模型。您可以与 Mistral AI 的语言模型进行交互，并基于 Mistral 模型创建多语言对话助手。

Mistral AI 也提供了与 OpenAI API 兼容的端点。请查阅 OpenAI API 兼容性部分，了解如何使用 Spring AI 的 OpenAI 集成来与 Mistral 端点通信。

二、先决条件

您需要创建一个 Mistral AI API 密钥来访问其语言模型。

在 Mistral AI 注册页面创建账户，并在 API 密钥页面生成令牌。

Spring AI 项目定义了一个名为 spring.ai.mistralai.api-key 的配置属性，您应将其设置为从 console.mistral.ai 获取的 API 密钥值。

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

yaml 复制代码

spring.ai.mistralai.api-key=<您的-mistralai-api-密钥>

为了在处理 API 密钥等敏感信息时增强安全性，您可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：

yaml 复制代码

# 在 application.yml 中
spring:
  ai:
    mistralai:
      api-key: ${MISTRALAI_API_KEY}

yaml 复制代码

# 在您的环境或 .env 文件中
export MISTRALAI_API_KEY=<您的-mistralai-api-密钥>

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

java 复制代码

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

2.1 添加仓库和 BOM

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

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

三、自动配置

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

Spring AI 为 Mistral AI 聊天客户端提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：

xml 复制代码

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

或者添加到您的 Gradle build.gradle 构建文件中。

groovy 复制代码

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

请参阅 "依赖管理" 部分，将 Spring AI BOM 添加到您的构建文件中。

3.1 聊天属性

3.1.1 重试属性

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

3.1.2 连接属性

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

3.1.3 配置属性

聊天自动配置的启用和禁用现在通过前缀为 spring.ai.model.chat 的顶级属性进行配置。

要启用：spring.ai.model.chat=mistral（默认已启用）。

要禁用：spring.ai.model.chat=none（或任何不匹配 mistral 的值）。

此项更改是为了支持配置多个模型。

前缀 spring.ai.mistralai.chat 是用于配置 Mistral AI 聊天模型实现的属性前缀。

您可以覆盖聊天模型和嵌入模型实现的通用属性 spring.ai.mistralai.base-url 和 spring.ai.mistralai.api-key。如果设置了 spring.ai.mistralai.chat.base-url 和 spring.ai.mistralai.chat.api-key 属性，它们将优先于通用属性。如果您想为不同的模型和不同的模型端点使用不同的 Mistral AI 账户，这将非常有用。
所有以 spring.ai.mistralai.chat.options 为前缀的属性都可以在运行时通过向 Prompt 调用添加请求特定的 "运行时选项" 来覆盖。

四、运行时选项

MistralAiChatOptions.java 提供了模型配置，例如要使用的模型、温度、频率惩罚等。

在启动时，可以通过 MistralAiChatModel(api, options) 构造函数或 spring.ai.mistralai.chat.options.* 属性来配置默认选项。

在运行时，您可以通过向 Prompt 调用添加新的、特定于请求的选项来覆盖默认选项。例如，为特定请求覆盖默认模型和温度：

java 复制代码

ChatResponse response = chatModel.call(
    new Prompt(
        "生成 5 个著名海盗的名字。",
        MistralAiChatOptions.builder()
            .model(MistralAiApi.ChatModel.LARGE.getValue())
            .temperature(0.5)
        .build()
    ));

除了模型特定的 MistralAiChatOptions，您还可以使用可移植的 ChatOptions 实例，该实例通过 ChatOptions#builder() 创建。

五、函数调用

您可以将自定义 Java 函数注册到 MistralAiChatModel，并让 Mistral AI 模型智能地选择输出包含调用一个或多个已注册函数参数的 JSON 对象。这是一种将 LLM 功能与外部工具和 API 连接的强大技术。阅读更多关于工具调用的信息。

六、多模态

多模态性是指模型能够同时理解和处理来自各种源的信息，包括文本、图像、音频和其他数据格式。Mistral AI 支持文本和视觉模态。

6.1 视觉

提供视觉多模态支持的 Mistral AI 模型包括 pixtral-large-latest。更多信息请参阅视觉指南。

Mistral AI 的用户消息 API 可以将 base64 编码的图像或图像 URL 列表与消息结合。Spring AI 的 Message 接口通过引入 Media 类型来支持多模态 AI 模型。此类型包含消息中媒体附件的数据和详细信息，使用 Spring 的 org.springframework.util.MimeType 和用于原始媒体数据的 org.springframework.core.io.Resource。

以下是从 MistralAiChatModelIT.java 中提取的代码示例，演示了用户文本与图像的融合。

java 复制代码

var imageResource = new ClassPathResource("/multimodal.test.png");

var userMessage = new UserMessage("解释一下你在这张图片中看到了什么？",
        new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource));

ChatResponse response = chatModel.call(new Prompt(this.userMessage,
        ChatOptions.builder().model(MistralAiApi.ChatModel.PIXTRAL_LARGE.getValue()).build()));

或者使用图像 URL 的等效方式：

java 复制代码

var userMessage = new UserMessage("解释一下你在这张图片中看到了什么？",
        new Media(MimeTypeUtils.IMAGE_PNG,
                URI.create("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png")));

ChatResponse response = chatModel.call(new Prompt(this.userMessage,
        ChatOptions.builder().model(MistralAiApi.ChatModel.PIXTRAL_LARGE.getValue()).build()));

您也可以传递多个图像。

该示例显示了一个模型以 multimodal.test.png 图像作为输入：

以及文本消息"解释一下你在这张图片中看到了什么？"，并生成类似以下的响应：

这是一个水果碗的图像，设计简单。碗由金属制成，带有弯曲的金属丝边缘，形成一个开放的结构，使得水果可以从各个角度被看到。碗内有两根黄色的香蕉放在一个红色的苹果上。香蕉稍微过熟，表皮上的棕色斑点表明了这一点。碗的顶部有一个金属环，可能用作提手。碗被放置在一个平面上，背景颜色中性，清晰地展示了碗内的水果。

七、OpenAI API 兼容性

Mistral 与 OpenAI API 兼容，您可以使用 Spring AI 的 OpenAI 客户端与 Mistral 通信。为此，您需要将 OpenAI 基础 URL 配置为 Mistral AI 平台：spring.ai.openai.chat.base-url=https://api.mistral.ai，并选择 Mistral 模型：spring.ai.openai.chat.options.model=mistral-small-latest，并设置 Mistral AI API 密钥：spring.ai.openai.chat.api-key=<您的 MISTRAL API 密钥>。

有关通过 Spring AI OpenAI 使用 Mistral 的示例，请查阅 MistralWithOpenAiChatModelIT.java 测试。

八、示例控制器（自动配置）

创建一个新的 Spring Boot 项目，并将 spring-ai-starter-model-mistral-ai 添加到您的 pom（或 gradle）依赖项中。

在 src/main/resources 目录下添加一个 application.properties 文件，以启用和配置 Mistral AI 聊天模型：

yaml 复制代码

spring.ai.mistralai.api-key=您的_API_密钥
spring.ai.mistralai.chat.options.model=mistral-small
spring.ai.mistralai.chat.options.temperature=0.7

请将 api-key 替换为您的 Mistral AI 凭据。

这将创建一个 MistralAiChatModel 实现，您可以将其注入到您的类中。以下是一个简单的 @RestController 类示例，该类使用聊天模型进行文本生成。

java 复制代码

@RestController
public class ChatController {

    private final MistralAiChatModel chatModel;

    @Autowired
    public ChatController(MistralAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map<String,String> generate(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
        var prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

九、手动配置

MistralAiChatModel 实现了 ChatModel 和 StreamingChatModel，并使用低级的 MistralAiApi 客户端连接到 Mistral AI 服务。

将 spring-ai-mistral-ai 依赖项添加到项目的 Maven pom.xml 文件中：

xml 复制代码

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

或者添加到您的 Gradle build.gradle 构建文件中。

groovy 复制代码

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

请参阅 "依赖管理" 部分，将 Spring AI BOM 添加到您的构建文件中。

接下来，创建一个 MistralAiChatModel 并将其用于文本生成：

java 复制代码

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

var chatModel = new MistralAiChatModel(this.mistralAiApi, MistralAiChatOptions.builder()
                .model(MistralAiApi.ChatModel.LARGE.getValue())
                .temperature(0.4)
                .maxTokens(200)
                .build());

ChatResponse response = this.chatModel.call(
    new Prompt("生成 5 个著名海盗的名字。"));

// 或者用于流式响应
Flux<ChatResponse> response = this.chatModel.stream(
    new Prompt("生成 5 个著名海盗的名字。"));

MistralAiChatOptions 为聊天请求提供配置信息。MistralAiChatOptions.Builder 是一个流畅的选项构建器。

9.1 低级 MistralAiApi 客户端

MistralAiApi 是一个轻量级的 Java 客户端，用于 Mistral AI API。

以下是一个简单的代码片段，展示了如何以编程方式使用该 API：

java 复制代码

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

ChatCompletionMessage chatCompletionMessage =
    new ChatCompletionMessage("Hello world", Role.USER);

// 同步请求
ResponseEntity<ChatCompletion> response = this.mistralAiApi.chatCompletionEntity(
    new ChatCompletionRequest(List.of(this.chatCompletionMessage), MistralAiApi.ChatModel.LARGE.getValue(), 0.8, false));

// 流式请求
Flux<ChatCompletionChunk> streamResponse = this.mistralAiApi.chatCompletionStream(
        new ChatCompletionRequest(List.of(this.chatCompletionMessage), MistralAiApi.ChatModel.LARGE.getValue(), 0.8, true));

有关更多信息，请参阅 MistralAiApi.java 的 JavaDoc。

9.2 MistralAiApi 示例

MistralAiApiIT.java 测试提供了一些关于如何使用这个轻量级库的通用示例。

PaymentStatusFunctionCallingIT.java 测试展示了如何使用低级 API 调用工具函数。基于 Mistral AI 函数调用教程。

十、Mistral AI OCR

Spring AI 支持使用 Mistral AI 进行光学字符识别（OCR）。这允许您从文档中提取文本和图像数据。

10.1 先决条件

您需要创建一个 Mistral AI API 密钥来访问其语言模型。在 Mistral AI 注册页面创建账户，并在 API 密钥页面生成令牌。

10.2 添加依赖项

要使用 Mistral AI OCR API，您需要将 spring-ai-mistral-ai 依赖项添加到您的项目中。

xml 复制代码

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

或者添加到您的 Gradle build.gradle 构建文件中。

groovy 复制代码

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

10.3 低级 MistralOcrApi 客户端

MistralOcrApi 为 Mistral AI OCR API 提供了一个轻量级的 Java 客户端。

以下是一个简单的代码片段，展示了如何以编程方式使用该 API：

java 复制代码

MistralOcrApi mistralAiApi = new MistralOcrApi(System.getenv("MISTRAL_AI_API_KEY"));

String documentUrl = "https://arxiv.org/pdf/2201.04234";
MistralOcrApi.OCRRequest request = new MistralOcrApi.OCRRequest(
        MistralOcrApi.OCRModel.MISTRAL_OCR_LATEST.getValue(), "test_id",
        new MistralOcrApi.OCRRequest.DocumentURLChunk(documentUrl), List.of(0, 1, 2), true, 5, 50);

ResponseEntity<MistralOcrApi.OCRResponse> response = mistralAiApi.ocr(request);

有关更多信息，请参阅 MistralOcrApi.java 的 JavaDoc。

10.4 MistralOcrApi 示例

MistralOcrApiIT.java 测试提供了一些关于如何使用这个轻量级库的通用示例。