Mistral 调用功能

您可以注册自定义的 Java 函数到 MistralAiChatClient，让 Mistral AI 模型智能地选择输出一个包含调用一个或多个已注册函数参数的 JSON 对象。这使您能够将 LLM 能力与外部工具和 API 连接起来。mistral_small_latest 和 mistral_large_latest 模型经过训练，可检测何时调用函数，并回复符合函数签名的 JSON。

MistralAI API 并不直接调用函数；相反，模型生成 JSON，您可以在代码中使用该 JSON 调用函数，并将结果返回给模型以完成对话。

目前，MistralAI API 不支持并行函数调用，类似于 OpenAI API、Azure OpenAI API 和 Vertex AI Gemini API。

Spring AI 提供了灵活且用户友好的方式来注册和调用自定义函数。通常情况下，自定义函数需要提供一个函数 name、description，以及函数调用 signature（作为 JSON 模式），以便让模型知道函数期望的参数。 description 帮助模型理解何时调用函数。

作为开发人员，您需要实现一个函数，接收来自 AI 模型的函数调用参数，并将结果返回给模型。您的函数可以进一步调用其他第三方服务来提供结果。

Spring AI 只需定义一个返回 java.util.Function 的 @Bean 定义，并在调用 ChatClient 时提供 bean 名称作为选项，就可以轻松实现这一点。

在幕后，Spring 会使用适当的适配器代码对您的 POJO（函数）进行封装，以实现与 AI 模型的交互，节省您编写繁琐样板代码的工作。底层基础设施的基础是 FunctionCallback.java 接口和配套的 FunctionCallbackWrapper.java 实用类，用于简化 Java 回调函数的实现和注册。

工作原理

假设我们希望 AI 模型回复有关其尚不具备的信息，例如给定位置的当前温度。

我们可以向 AI 模型提供关于我们自己函数的元数据，使其在处理您的提示时能够检索到该信息。

例如，在处理提示的过程中，如果 AI 模型确定需要有关特定位置温度的额外信息，它将启动服务器端生成的请求/响应交互。AI 模型调用客户端函数。AI 模型以 JSON 形式提供方法调用详细信息，客户端有责任执行该函数并返回响应。

Spring AI 大大简化了您需要编写的支持函数调用的代码。它为您经纪了函数调用对话。您只需将函数定义为 @Bean，然后在提示选项中提供函数的 bean 名称。您还可以在提示中引用多个函数 bean 名称。

快速入门

让我们创建一个聊天机器人，通过调用我们自己的函数来回答问题。为了支持聊天机器人的响应，我们将注册我们自己的函数，该函数需要一个位置并返回该位置的当前天气。

当响应到模型提示需要回答问题，例如“波士顿天气如何？”时，AI模型将调用客户端，将位置值作为传递给该函数的参数。此类类似于RPC的数据以JSON格式传递。

我们的函数可以使用一些基于SaaS的天气服务API，并将天气响应返回给模型以完成对话。在此示例中，我们将使用一个简单的实现，名为MockWeatherService，该实现为各种位置硬编码温度。

以下的MockWeatherService.java表示天气服务API：

public class MockWeatherService implements Function<Request, Response> {

	public enum Unit { C, F }
	public record Request(String location, Unit unit) {}
	public record Response(double temp, Unit unit) {}

	public Response apply(Request request) {
		return new Response(30.0, Unit.C);
	}
}

将函数注册为Beans

有多种方式可使用MistralAiChatClient自动配置将自定义函数作为bean注册到Spring上下文中。

我们从描述最适合POJO的选项开始描述。

基本Java函数

在这种方法中，您像其他Spring托管对象一样在应用程序上下文中定义@Beans。

在内部，Spring AI ChatClient将创建一个FunctionCallbackWrapper包装器的实例，该实例添加了通过AI模型调用它的逻辑。@Bean的名称作为ChatOption传递。

@Configuration
static class Config {

	@Bean
	@Description("获取指定位置的天气") // 函数说明
	public Function<MockWeatherService.Request, MockWeatherService.Response> weatherFunction1() {
		return new MockWeatherService();
	}
	...
}

@Description注解是可选的，并提供函数说明（2），以帮助模型理解何时调用该函数。设置此属性很重要，以帮助AI模型确定要调用的客户端函数。

提供函数说明的另一种选项是对MockWeatherService.Request使用@JacksonDescription注解提供函数说明：

@Configuration
static class Config {

	@Bean
	public Function<Request, Response> currentWeather3() { // (1) 使用bean名称作为函数名称。
		return new MockWeatherService();
	}
	...
}

@JsonClassDescription("获取指定位置的天气") // (2) 函数说明
public record Request(String location, Unit unit) {}

将请求对象注释为尽可能描述性，使生成的该函数JSON Schema尽可能具有描述性以帮助AI模型选择正确的函数调用，这是一种最佳实践。

PaymentStatusBeanIT.java演示了此方法。

PaymentStatusBeanOpenAiIT使用OpenAI API实现相同的函数。 MistralAI在这方面与OpenAI几乎是相同的。

FunctionCallback包装器

注册函数的另一种方法是创建FunctionCallbackWrapper包装器，如下所示：

@Configuration
static class Config {

	@Bean
	public FunctionCallback weatherFunctionInfo() {

		return new FunctionCallbackWrapper<>("CurrentWeather", // (1) 函数名称
				"获取指定位置的天气", // (2) 函数说明
				(response) -> "" + response.temp() + response.unit(), // (3) 响应转换器
				new MockWeatherService()); // 函数代码
	}
	...
}

它将第三方的MockWeatherService函数包装，并将其注册为具有MistralAiChatClient的CurrentWeather函数。它还提供了描述（2）和可选的响应转换器（3）以将响应转换为模型期望的文本。

默认情况下，响应转换器执行Response对象的JSON序列化。

FunctionCallbackWrapper在内部根据MockWeatherService.Request类解析函数调用签名。

在聊天选项中指定函数

要让模型知道并调用你的CurrentWeather函数，你需要在提示请求中启用它：

MistralAiChatClient chatClient = ...

UserMessage userMessage = new UserMessage("巴黎的天气如何？");

ChatResponse response = chatClient.call(new Prompt(List.of(userMessage),
		MistralAiChatOptions.builder().withFunction("CurrentWeather").build())); // (1) 启用函数

logger.info("响应: {}", response);

以上用户问题将触发对CurrentWeather函数的3次调用（每个城市一次），并生成最终响应。

使用提示选项注册/调用函数

除了自动配置外，你还可以在提示请求中动态注册回调函数：

MistralAiChatClient chatClient = ...

UserMessage userMessage = new UserMessage("巴黎的天气如何？");

var promptOptions = MistralAiChatOptions.builder()
	.withFunctionCallbacks(List.of(new FunctionCallbackWrapper<>(
		"CurrentWeather", // 名称
		"获取地点的天气", // 函数描述
		new MockWeatherService()))) // 函数代码
	.build();

ChatResponse response = chatClient.call(new Prompt(List.of(userMessage), promptOptions));

内部提示注册的函数在此请求期间默认启用。

这种方法允许根据用户输入动态选择不同的函数进行调用。

PaymentStatusPromptIT.java集成测试提供了如何向MistralAiChatClient注册函数并在提示请求中使用它的完整示例。