Function Calling

Mistral Function Calling（函数调用）

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

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

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

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

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

Spring AI 使这一切变得简单，只需定义一个@Bean返回 a 的定义java.util.Function并在调用ChatClient.

在底层，Spring 使用适当的适配器代码包装您的 POJO（函数），以支持与 AI 模型的交互，从而使您免于编写繁琐的样板代码。底层基础设施的基础是FunctionCallback.java接口和配套的FunctionCallbackWrapper.java 实用程序类，用于简化 Java 回调函数的实现和注册。

怎么运行的

假设我们希望人工智能模型以它没有的信息做出响应，例如：给定位置的当前温度。

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

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

Spring AI 函数调用流程图说明了模型与客户端的交互。

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

快速开始

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

当对模型提示的响应需要回答问题时，例如"What’s the weather like in Boston?"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);
    }
}

将函数注册为 Bean

通过 MistralAiChatClient 自动配置，您可以通过多种方式将自定义函数注册为 Spring 上下文中的 bean。

我们首先描述对 POJO 最友好的选项。

普通 Java 函数

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

在内部， Spring AI ChatClient 将创建一个 FunctionCallbackWrapper 实例， 为通过AI模型调用它添加逻辑的包装器。

这个 @Bean 作为一个 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 模型确定要调用的客户端函数。

另一种选择是通过注释@JacksonDescription 来注解 MockWeatherService.Request提供函数描述：

@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 模型选择要调用的正确函数。

FunctionCallbackWithPlainFunctionBeanIT.java 演示了这种方法。

FunctionCallback Wrapper

另外一种注册函数的方式是像下面一样，创建 FunctionCallbackWrapper 包装器：

@Configuration
static class Config {

    @Bean
    public FunctionCallback weatherFunctionInfo() {

        return FunctionCallbackWrapper.builder(new MockWeatherService())
            .withName("CurrentWeather") // (1) function name
            .withDescription("Get the current weather in a given location") // (2) function description
            .withSchemaType(SchemaType.OPEN_API) // (3) schema type. Compulsory for Gemini function calling.
            .build();
    }
    ...
}

它包装了第 3 方MockWeatherService函数并将其注册为 OpenAiChatClient 中名称叫做 CurrentWeather的函数.它还提供描述 (2) 和可选的响应转换器 (3)，以将响应转换为模型预期的文本。

注意:

• 默认情况下，响应转换器对响应对象进行 JSON 序列化。
• 内部 FunctionCallbackWrapper 根据 MockWeatherService.Request 类解析函数调用签名。

在 Chat Options 中申明函数

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

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

上述用户问题将触发 3 次CurrentWeather函数调用（每个城市一次），最终响应将如下所示：

Here is the current weather for the requested cities:
- San Francisco, CA: 30.0°C
- Tokyo, Japan: 10.0°C
- Paris, France: 15.0°C

带有提示选项的注册/调用函数

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

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

提示：默认情况下，在此请求期间启用提示注册功能。

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

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