Mistral AI 聊天

Spring AI 支持来自 Mistral AI 的各类 AI 语言模型。你可以与 Mistral AI 语言模型交互，并基于 Mistral 模型创建一个多语言对话助手。

TIP

Mistral AI 也提供一个与 OpenAI API 兼容的端点。

查看 OpenAI API 兼容性一节，了解如何用 Spring AI OpenAI 集成与一个 Mistral 端点对话。

前置条件

你需要在 Mistral AI 创建一个 API 才能访问 Mistral AI 语言模型。

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

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

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

properties

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

为在 handling 诸如 API 密钥这类敏感信息时获得更强的安全性，你可以使用 Spring 表达式语言（SpEL）引用一个自定义环境变量：

yaml

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

bash

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

你也可以在应用代码中以编程方式设置此配置属性：

java

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

添加仓库与 BOM

Spring AI 的制品发布在 Maven Central 和 Spring Snapshot 仓库中。参见制品仓库一节，把这些仓库添加到你的构建系统。

为便于依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保整个项目中使用一致版本的 Spring AI。参见依赖管理一节，把 Spring AI BOM 添加到你的构建系统。

自动配置

NOTE

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'
}

TIP

参见依赖管理一节，把 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 用作连接 OpenAI 的属性前缀。

属性	描述	默认值
spring.ai.mistralai.base-url	要连接到的 URL	https://api.mistral.ai
spring.ai.mistralai.api-key	API 密钥	-

配置属性

NOTE

聊天自动配置的启用与禁用，现通过以 spring.ai.model.chat 为前缀的顶层属性来配置。

要启用，spring.ai.model.chat=mistral（默认启用）

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

做出此变更是为了支持配置多个模型。

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

属性	描述	默认值
spring.ai.mistralai.chat.enabled (Removed and no longer valid)	启用 Mistral AI 聊天模型。	true
spring.ai.model.chat	启用 Mistral AI 聊天模型。	mistral
spring.ai.mistralai.chat.base-url	可选，覆盖 `spring.ai.mistralai.base-url` 属性以提供一个聊天专用 URL。	-
spring.ai.mistralai.chat.api-key	可选，覆盖 `spring.ai.mistralai.api-key` 以提供一个聊天专用 API 密钥。	-
spring.ai.mistralai.chat.model	要使用的 Mistral AI 聊天模型	`open-mistral-7b`、`open-mixtral-8x7b`、`open-mixtral-8x22b`、`mistral-small-latest`、`mistral-large-latest`
spring.ai.mistralai.chat.temperature	用于控制的采样温度，影响生成补全的表观创造性。较高的值使输出更随机，较低的值使结果更聚焦、更确定。不建议在同一补全请求中同时修改 `temperature` 与 `top_p`，因为这两个设置的相互作用难以预测。	0.8
spring.ai.mistralai.chat.max-tokens	在聊天补全中要生成的最大令牌数。输入令牌与生成令牌的总长度受模型上下文窗口长度限制。	-
spring.ai.mistralai.chat.safe-prompt	指示是否在所有对话之前注入一个安全提示词。	false
spring.ai.mistralai.chat.random-seed	此特性处于 Beta。若指定，我们的系统会尽力做确定性采样，使带相同 seed 与参数的重复请求返回相同结果。	-
spring.ai.mistralai.chat.stop	若检测到该令牌则停止生成。或在提供数组时，检测到其中某个令牌时停止。	-
spring.ai.mistralai.chat.top-p	temperature 采样的替代方案，即核采样，模型会考虑具有 top_p 概率质量的那些令牌的结果。所以 0.1 意味着只考虑构成前 10% 概率质量的令牌。我们通常建议调整此项或 `temperature`，但不要同时调整两者。	-
spring.ai.mistralai.chat.response-format	指定模型必须输出格式的對象。设为 `{ "type": "json_object" }` 会启用 JSON 模式，保证模型生成的消息是合法 JSON。带上所供模式设为 `{ "type": "json_schema" }` 会启用原生结构化输出，保证模型匹配你提供的 JSON 模式。更多细节见 structured-output 一节。	-
spring.ai.mistralai.chat.reasoning-effort	控制可调节推理模型的推理力度级别。有效值包括 `high` 或 `none`。	-
spring.ai.mistralai.chat.tools	模型可调用工具列表。目前作为工具只支持函数。用它提供一个模型可为其生成 JSON 输入的函数列表。	-
spring.ai.mistralai.chat.tool-choice	控制模型调用哪个（若有）函数。`none` 表示模型不会调用函数而生成一条消息。`auto` 表示模型可在生成消息或调用函数之间选择。通过 `{"type: "function", "function": {"name": "my_function"}}` 指定某个特定函数会强制模型调用该函数。无函数存在时 `none` 为默认；有函数存在时 `auto` 为默认。	-
spring.ai.mistralai.chat.tool-callbacks	注册到 ChatModel 的工具回调。	-

NOTE

你可以为 ChatModel 和 EmbeddingModel 实现覆盖通用的 spring.ai.mistralai.base-url 和 spring.ai.mistralai.api-key。

若设置了 spring.ai.mistralai.chat.base-url 和 spring.ai.mistralai.chat.api-key 属性，它们优先于通用属性。当你想为不同模型、不同模型端点使用不同的 Mistral AI 账户时，这很有用。

TIP

所有以 spring.ai.mistralai.chat 为前缀的属性，都可通过在 Prompt 调用中添加请求专用的 chat-options 在运行时被覆盖。

运行时选项

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

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

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

java

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        MistralAiChatOptions.builder()
            .model(MistralAiApi.ChatModel.MISTRAL_LARGE.getValue())
            .temperature(0.5)
        .build()
    ));

TIP

除模型特定的 MistralAiChatOptions 外，你还可以使用一个可移植的 ChatOptions 实例，通过 ChatOptions#builder() 创建。

工具调用

MistralAiChatModel 支持工具调用。模型可以请求执行工具，但它自己并不运行工具——由 Spring AI 处理执行。

对于大多数应用，请搭配自动注册的 ToolCallingAdvisor 使用 ChatClient —— 参见工具调用。若需要由你自己驱动该循环的底层控制，参见 ChatModel 工具调用。

结构化输出

Mistral AI 通过 JSON Schema 支持原生结构化输出，确保模型生成的响应严格符合你指定的结构。此特性对 Mistral Small 及更新的模型可用。

用 ChatClient 配合原生结构化输出

使用结构化输出最简单的方式，是用 ChatClient 高层 API 和 ENABLE_NATIVE_STRUCTURED_OUTPUT 顾问：

java

record ActorsFilms(String actor, List<String> movies) {}

ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt()
    .advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
    .user("Generate the filmography of 5 movies for Tom Hanks.")
    .call()
    .entity(ActorsFilms.class);

这种方式会自动：

从你的 Java 类生成一个 JSON 模式
配置模型使用原生结构化输出
把响应解析为你指定的类型

直接使用 ResponseFormat

为了更多控制，你可以把 ResponseFormat 类与 MistralAiChatOptions 一起使用：

java

record MovieRecommendation(String title, String director, int year, String plotSummary) {}

var options = MistralAiChatOptions.builder()
    .model(MistralAiApi.ChatModel.MISTRAL_SMALL.getValue())
    .responseFormat(ResponseFormat.jsonSchema(MovieRecommendation.class))
    .build();

ChatResponse response = chatModel.call(
    new Prompt("Recommend a classic science fiction movie.", options));

ResponseFormat 类提供若干工厂方法：

ResponseFormat.text() - 返回纯文本输出（默认）
ResponseFormat.jsonObject() - 返回合法 JSON（不做模式强制）
ResponseFormat.jsonSchema(Class<?>) - 从 Java 类生成模式
ResponseFormat.jsonSchema(String) - 使用一个 JSON 模式字符串
ResponseFormat.jsonSchema(Map) - 使用一个 JSON 模式 map

JSON 模式 vs 结构化输出

Mistral AI 支持两种 JSON 相关模式：

JSON 模式（json_object）：保证合法 JSON 输出，但不强制特定结构
结构化输出（json_schema）：保证输出匹配你的 JSON 模式

java

// JSON Mode - any valid JSON
var jsonMode = MistralAiChatOptions.builder()
    .responseFormat(ResponseFormat.jsonObject())
    .build();

// Structured Output - specific schema enforced
var structuredOutput = MistralAiChatOptions.builder()
    .responseFormat(ResponseFormat.jsonSchema(MyClass.class))
    .build();

关于结构化输出的更多信息，参见结构化输出文档。

推理模型

Mistral 提供两种推理方式：

可调节：在 Mistral Small 4 和 Mistral Medium 3.5 上通过 reasoning_effort 参数可用。让模型能以不同程度进行思考。
原生：对 Magistral 模型家族可用。这些模型总会生成推理轨迹，并为深度推理任务专门打造。

推理力度

你可以用 MistralAiChatOptions 里的 reasoningEffort 属性配置推理力度。这让你能调整模型在生成响应前用于推理的计算量。

java

var options = MistralAiChatOptions.builder()
    .model(MistralAiApi.ChatModel.MISTRAL_SMALL.getValue()) // Or any adjustable reasoning model
    .reasoningEffort(MistralAiApi.ChatCompletionRequest.ReasoningEffort.HIGH)
    .build();

ChatResponse response = chatModel.call(
    new Prompt("Solve this complex math problem...", options));

推理内容

Mistral 推理模型会暴露其内部思维链与引用。 Spring AI 把它们从 API 响应映射到消息元数据。

你可以从 AssistantMessage 访问以下元数据键：

reference_content：把模型响应关联到其源文档以供溯源与引用的唯一键。
thinking_content：模型用以得出最终答案的分步推理过程（仅对推理模型可访问）。
reference_thinking_content：把模型的推理步骤关联到其源文档以供溯源与引用的唯一键（可能仅对推理模型可访问）。

java

ChatResponse response = chatModel.call(new Prompt("Solve this complex math problem..."));

AssistantMessage message = response.getResult().getOutput();

// Access the thinking content from metadata
String thinking = (String) message.getMetadata().get(MistralAiChatModel.THINKING_CONTENT_METADATA);
if (thinking != null && !thinking.isEmpty()) {
    System.out.println("Model's thinking process:");
    System.out.println(thinking);
}

多模态

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

视觉

Mistral AI 模型提供视觉多模态支持。更多信息参见 Vision 指南。

Mistral AI User Message 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("Explain what do you see on this picture?",
        new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource));

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

或图像 URL 的等价写法：

java

var userMessage = new UserMessage("Explain what do you see on this picture?",
        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.MISTRAL_LARGE.getValue()).build()));

TIP

你也可以传入多张图像。

这个示例展示模型以 multimodal.test.png 图像作为输入：

连同文本消息 "Explain what do you see on this picture?"，并生成一个像这样的响应：

This is an image of a fruit bowl with a simple design. The bowl is made of metal with curved wire edges that
create an open structure, allowing the fruit to be visible from all angles. Inside the bowl, there are two
yellow bananas resting on top of what appears to be a red apple. The bananas are slightly overripe, as
indicated by the brown spots on their peels. The bowl has a metal ring at the top, likely to serve as a handle
for carrying. The bowl is placed on a flat surface with a neutral-colored background that provides a clear
view of the fruit inside.

OpenAI API 兼容性

Mistral 与 OpenAI API 兼容，你可以用 Spring AI OpenAI 客户端与 Mistral 对话。为此，你需要把 OpenAI base URL 配置到 Mistral AI 平台：spring.ai.openai.chat.base-url=https://api.mistral.ai/v1，选择一个 Mistral 模型：spring.ai.openai.chat.model=mistral-small-latest，并设置 Mistral AI API 密钥：spring.ai.openai.chat.api-key=<YOUR MISTRAL API KEY。

查看 MistralWithOpenAiChatModelIT.java 测试，其中有在 Spring AI OpenAI 之上使用 Mistral 的示例。

示例控制器（自动配置）

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

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

application.properties

spring.ai.mistralai.api-key=YOUR_API_KEY
spring.ai.mistralai.chat.model=mistral-small-latest
spring.ai.mistralai.chat.temperature=0.7

TIP

用你的 Mistral AI 凭据替换 api-key。

这会创建一个可注入到你类中的 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 = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        var prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

手动配置

MistralAiChatModel 实现了 ChatModel 和 StreamingChatModel，并使用底层 api 连接到 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'
}

TIP

参见依赖管理一节，把 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.MISTRAL_LARGE.getValue())
                .temperature(0.4)
                .maxTokens(200)
                .build());

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

// Or with streaming responses
Flux<ChatResponse> response = this.chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));

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

底层 MistralAiApi 客户端

MistralAiApi 为 Mistral AI API 提供一个轻量级 Java 客户端。

下面是一个演示如何以编程方式使用该 API 的简单片段：

java

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

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

// Sync request
ResponseEntity<ChatCompletion> response = this.mistralAiApi.chatCompletionEntity(
    new ChatCompletionRequest(List.of(this.chatCompletionMessage), MistralAiApi.ChatModel.MISTRAL_LARGE.getValue(), 0.8, false));

// Streaming request
Flux<ChatCompletionChunk> streamResponse = this.mistralAiApi.chatCompletionStream(
        new ChatCompletionRequest(List.of(this.chatCompletionMessage), MistralAiApi.ChatModel.MISTRAL_LARGE.getValue(), 0.8, true));

关于更多信息，遵循 MistralAiApi.java 的 JavaDoc。

MistralAiApi 示例

MistralAiApiIT.java 测试提供了一些关于如何使用该轻量库的通用示例。
PaymentStatusFunctionCallingIT.java 测试展示如何用底层 API 调用工具函数。基于 Mistral AI 函数调用教程。

Mistral AI OCR

Spring AI 支持用 Mistral AI 做光学字符识别（OCR）。这让你能从文档中提取文本和图像数据。

前置条件

你需要在 Mistral AI 创建一个 API 才能访问 Mistral AI 语言模型。在 Mistral AI 注册页创建账户，并在 API Keys 页生成令牌。

添加依赖

要使用 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'
}

底层 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。

MistralOcrApi 示例

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

顾问（Advisor）API

聊天模型 API

嵌入模型 API

Amazon Bedrock

VertexAI

图像模型 API

音频模型

转录 API

文本转语音（TTS）API

审核模型

MCP 服务端 Boot Starter

MCP 注解

Mistral AI 聊天

前置条件

添加仓库与 BOM

自动配置

聊天属性

重试属性

连接属性

配置属性

运行时选项

工具调用

结构化输出

用 ChatClient 配合原生结构化输出

直接使用 ResponseFormat

JSON 模式 vs 结构化输出

推理模型

推理力度

推理内容

多模态

视觉

OpenAI API 兼容性

示例控制器（自动配置）

手动配置

底层 MistralAiApi 客户端

MistralAiApi 示例

Mistral AI OCR

前置条件

添加依赖

底层 MistralOcrApi 客户端

MistralOcrApi 示例

友情链接