Mistral Function Calling

你可以用 MistralAiChatClient 注册自定义的 Java 函数，并且让 Mistral AI 模型智能地选择输出一个 JSON 对象，里面包含调用一个或多个已注册函数的参数。这允许你将 LLM 能力与外部工具和 API 相连接。mistral_small_latest 和 mistral_large_latest 模型经过训练，以检测何时应该调用函数，并用符合函数签名的 JSON 作出响应。

You can register custom Java functions with the MistralAiChatClient and have the Mistral AI models intelligently choose to output a JSON object containing arguments to call one or many of the registered functions. This allows you to connect the LLM capabilities with external tools and APIs. The mistral_small_latest and mistral_large_latest models are trained to detect when a function should be called and to respond with JSON that adheres to the function signature.

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

The MistralAI API does not call the function directly; instead, the model generates JSON that you can use to call the function in your code and return the result back to the model to complete the conversation.

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

Currently the MistralAI API doesn’t support parallel function calling, similarly to the OpenAI API, Azure OpenAI API, and Vertex AI Gemini API.

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

Spring AI provides flexible and user-friendly ways to register and call custom functions. In general, the custom functions need to provide a function name, description, and the function call signature (as JSON schema) to let the model know what arguments the function expects. The description helps the model to understand when to call the function.

作为一个开发者，你需要实现一个函数，它获取从 AI 模型发送的函数调用参数，并用结果返回给模型。你的函数又可以调用其他第三方服务来提供结果。

As a developer, you need to implement a functions that takes the function call arguments sent from the AI model, and respond with the result back to the model. Your function can in turn invoke other 3rd party services to provide the results.

Spring AI 让这件事变得像定义一个 @Bean 定义一样简单，该定义返回一个 java.util.Function，并在调用 ChatClient 时将 bean 名称作为一个选项提供。

Spring AI makes this as easy as defining a @Bean definition that returns a java.util.Function and supplying the bean name as an option when invoking the ChatClient.

底层 Spring 将你的 POJO（函数）与适当的适配器代码打包在一起，使之能够与 AI 模型交互，省去了编写繁琐样板代码的步骤。底层基础架构的基础是 FunctionCallback.java 接口以及配套的 FunctionCallbackWrapper.java 实用程序类，对 Java 回调函数的实现和注册进行了简化。

Under the hood, Spring wraps your POJO (the function) with the appropriate adapter code that enables interaction with the AI Model, saving you from writing tedious boilerplate code. The basis of the underlying infrastructure is the FunctionCallback.java interface and the companion FunctionCallbackWrapper.java utility class to simplify the implementation and registration of Java callback functions.

How it works

假设我们希望 AI 模型用它没有的信息进行响应，例如给定位置的当前温度。

Suppose we want the AI model to respond with information that it does not have, for example the current temperature at a given location.

我们可以向 AI 模型提供有关我们自己函数的元数据，它可以在处理你的提示时使用这些元数据检索该信息。

We can provide the AI model with metadata about our own functions that it can use to retrieve that information as it processes your prompt.

例如，如果在处理提示时，AI 模型确定它需要有关给定位置温度的附加信息，它将启动服务端生成的请求/响应交互。AI 模型会调用一个客户端函数。AI 模型将方法调用详细信息作为 JSON 提供，客户端负责执行该函数并返回响应。

For example, if during the processing of a prompt, the AI Model determines that it needs additional information about the temperature in a given location, it will start a server side generated request/response interaction. The AI Model invokes a client side function. The AI Model provides method invocation details as JSON and it is the responsibility of the client to execute that function and return the response.

Spring AI 极大地简化了你需要为支持函数调用而编写的代码。它为你代理了函数调用会话。你可以简单地提供你的函数定义，作为 @Bean，然后在命令提示选项中提供该函数的 bean 名称。你还可以引用多个函数 bean 名称作为提示。

Spring AI greatly simplifies code you need to write to support function invocation. It brokers the function invocation conversation for you. You can simply provide your function definition as a @Bean and then provide the bean name of the function in your prompt options. You can also reference multiple function bean names in your prompt.

Quick Start

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

Let’s create a chatbot that answer questions by calling our own function. To support the response of the chatbot, we will register our own function that takes a location and returns the current weather in that location.

当提示模型的响应需要回答诸如 `"波士顿的天气怎么样？"`此类问题时，AI 模型将调用客户端，提供位置值作为传递给函数的参数。这种类似 RPC 的数据以 JSON 形式传递。

When the response to the prompt to the model needs to answer a question such as "What’s the weather like in Boston?" the AI model will invoke the client providing the location value as an argument to be passed to the function. This RPC-like data is passed as JSON.

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

Our function can some SaaS based weather service API and returns the weather response back to the model to complete the conversation. In this example we will use a simple implementation named MockWeatherService that hard codes the temperature for various locations.

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

The following MockWeatherService.java represents the weather service 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);
	}
}

Registering Functions as Beans

利用 MistralAiChatClient Auto-Configuration，你可以通过多种方式将自定义函数注册为 Spring 上下文中的 Bean。

With the MistralAiChatClient Auto-Configuration you have multiple ways to register custom functions as beans in the Spring context.

我们从描述最友好的 POJO 选项开始。

We start with describing the most POJO friendly options.

Plain Java Functions

在此方法中，你可以根据你定义任何其他 Spring 托管对象的方式在应用程序上下文中定义 @Beans。

In this approach you define @Beans in your application context as you would any other Spring managed object.

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

Internally, Spring AI ChatClient will create an instance of a FunctionCallbackWrapper wrapper that adds the logic for it being invoked via the AI model. The name of the @Bean is passed as a ChatOption.

@Configuration
static class Config {

	@Bean
	@Description("Get the weather in location") // function description
	public Function<MockWeatherService.Request, MockWeatherService.Response> weatherFunction1() {
		return new MockWeatherService();
	}
	...
}

@Description 注释是可选的，并且提供了一个函数描述 (2)，它帮助模型理解何时调用函数。这是一个重要的属性设置，有助于 AI 模型确定要调用的客户端侧函数。

The @Description annotation is optional and provides a function description (2) that helps the model to understand when to call the function. It is an important property to set to help the AI model determine what client side function to invoke.

提供函数描述的另一种选择是在 MockWeatherService.Request 上的 @JacksonDescription 注释来提供函数描述：

Another option to provide the description of the function is to the @JacksonDescription annotation on the MockWeatherService.Request to provide the function description:

@Configuration
static class Config {

	@Bean
	public Function<Request, Response> currentWeather3() { // (1) bean name as function name.
		return new MockWeatherService();
	}
	...
}

@JsonClassDescription("Get the weather in location") // (2) function description
public record Request(String location, Unit unit) {}

最好使用诸如此类的信息注释请求对象，以便该函数生成 JSON 架构尽可能的描述性，以帮助 AI 模型选择要调用的正确函数。

It is a best practice to annotate the request object with information such that the generates JSON schema of that function is as descriptive as possible to help the AI model pick the correct function to invoke.

PaymentStatusBeanIT.java 展示了这种方法。

The PaymentStatusBeanIT.java demonstrates this approach.

PaymentStatusBeanOpenAiIT 使用 OpenAI API 实现了相同的功能。MistralAI 在这方面与 OpenAI 几乎相同。

The PaymentStatusBeanOpenAiIT implements the same function using the OpenAI API. MistralAI is almost identical to OpenAI in this regard.

FunctionCallback Wrapper

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

Another way register a function is to create FunctionCallbackWrapper wrapper like this:

@Configuration
static class Config {

	@Bean
	public FunctionCallback weatherFunctionInfo() {

		return new FunctionCallbackWrapper<>("CurrentWeather", // (1) function name
				"Get the weather in location", // (2) function description
				(response) -> "" + response.temp() + response.unit(), // (3) Response Converter
				new MockWeatherService()); // function code
	}
	...
}

它封装第三方 MockWeatherService 函数，并将其作为 CurrentWeather 函数注册到 MistralAiChatClient。它还提供了一个描述 (2) 和一个可选的响应转换器 (3)，将响应转换为模型期望的文本。

It wraps the 3rd party, MockWeatherService function and registers it as a CurrentWeather function with the MistralAiChatClient. It also provides a description (2) and an optional response converter (3) to convert the response into a text as expected by the model.

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

By default, the response converter does a JSON serialization of the Response object.

FunctionCallbackWrapper 内部将函数调用签名解析为基于 MockWeatherService.Request 类的函数调用签名。

The FunctionCallbackWrapper internally resolves the function call signature based on the MockWeatherService.Request class.

Specifying functions in Chat Options

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

To let the model know and call your CurrentWeather function you need to enable it in your prompt requests:

MistralAiChatClient chatClient = ...

UserMessage userMessage = new UserMessage("What's the weather like in Paris?");

ChatResponse response = chatClient.call(new Prompt(List.of(userMessage),
		MistralAiChatOptions.builder().withFunction("CurrentWeather").build())); // (1) Enable the function

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

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

Above user question will trigger 3 calls to CurrentWeather function (one for each city) and produce the final response.

Register/Call Functions with Prompt Options

除了自动配置，你还可以动态地使用你的提示请求注册回调函数：

In addition to the auto-configuration you can register callback functions, dynamically, with your Prompt requests:

MistralAiChatClient chatClient = ...

UserMessage userMessage = new UserMessage("What's the weather like in Paris?");

var promptOptions = MistralAiChatOptions.builder()
	.withFunctionCallbacks(List.of(new FunctionCallbackWrapper<>(
		"CurrentWeather", // name
		"Get the weather in location", // function description
		new MockWeatherService()))) // function code
	.build();

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

命令提示中注册的函数默认在这个请求期间启用。

The in-prompt registered functions are enabled by default for the duration of this request.

此方法允许根据用户输入动态选择要调用的不同函数。

This approach allows to dynamically chose different functions to be called based on the user input.

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

The PaymentStatusPromptIT.java integration test provides a complete example of how to register a function with the MistralAiChatClient and use it in a prompt request.