函数调用

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

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

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

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

Spring AI 使这变得像定义一个返回`java.util.Function`的`@Bean`定义并将 bean 名称作为选项在调用`ChatModel`时提供一样容易。

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

工作原理

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

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

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

模型-客户端交互在Spring AI 函数调用流程图中进行了说明。

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

将函数注册为 Bean

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

我们首先介绍最友好的 POJO 选项。

纯 Java 函数

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

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

@Configuration
static class Config {

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

}

`@Description` 注解是可选的，它提供了一个函数描述，帮助模型理解何时调用该函数。这是一个重要的属性，有助于 AI 模型确定要调用哪个客户端函数。

提供函数描述的另一个选项是在`MockWeatherService.Request`上使用`@JsonClassDescription`注解。

@Configuration
static class Config {

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

}

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

最佳实践是在请求对象上添加注释，以便该函数的生成的 JSON 模式尽可能具有描述性，以帮助 AI 模型选择正确的函数来调用。

示例代码FunctionCallbackWithPlainFunctionBeanIT.java 演示了这种方法。

FunctionCallback 包装器

注册函数的另一种方法是创建如下所示的FunctionCallback

@Configuration
static class Config {

	@Bean
	public FunctionCallback weatherFunctionInfo() {

    return FunctionCallback.builder()
        .description("Get the weather in location") // (2) function description
        .function("CurrentWeather", new MockWeatherService()) // (1) function name and instance
        .inputType(MockWeatherService.Request.class) // (3) function input type
        .build();
	}

}

它包装了第三方MockWeatherService函数，并将其注册为OpenAiChatModel中的CurrentWeather函数。它还提供了一个描述 (2) 和一个输入类型 (3)，用于生成函数调用的 JSON Schema。

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

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

在聊天选项中指定函数

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

OpenAiChatModel chatModel = ...

UserMessage userMessage = new UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?");

ChatResponse response = this.chatModel.call(new Prompt(this.userMessage,
		OpenAiChatOptions.builder().withFunction("CurrentWeather").build())); // Enable the function

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

上述用户问题将触发对CurrentWeather函数的3次调用（每个城市一次），最终响应将类似于：

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

测试代码OpenAiFunctionCallbackIT.java 演示了这种方法。

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

除了自动配置之外，你还可以使用你的Prompt请求动态注册回调函数。

OpenAiChatModel chatModel = ...

UserMessage userMessage = new UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?");

var promptOptions = OpenAiChatOptions.builder()
	.withFunctionCallbacks(List.of(FunctionCallback.builder()
        .description("Get the weather in location") // (2) function description
        .function("CurrentWeather", new MockWeatherService()) // (1) function name and instance
        .inputType(MockWeatherService.Request.class) // (3) function input type
        .build())) // function code
	.build();

ChatResponse response = this.chatModel.call(new Prompt(this.userMessage, this.promptOptions));

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

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

集成测试FunctionCallbackInPromptIT.java 提供了一个完整的示例，说明如何使用OpenAiChatModel注册函数并在提示请求中使用它。

工具上下文支持

Spring AI 现在支持通过工具上下文将额外的上下文信息传递给函数回调。此功能允许你提供可在函数执行中使用的额外数据，从而增强函数调用的灵活性和功能。

上下文信息作为java.util.BiFunction的第二个参数传入。ToolContext包含一个不可变的Map<String,Object>，允许你访问键值对。

如何使用工具上下文

你可以在构建聊天选项时设置工具上下文，并为你的回调使用 BiFunction

BiFunction<MockWeatherService.Request, ToolContext, MockWeatherService.Response> weatherFunction =
    (request, toolContext) -> {
        String sessionId = (String) toolContext.getContext().get("sessionId");
        String userId = (String) toolContext.getContext().get("userId");

        // Use sessionId and userId in your function logic
        double temperature = 0;
        if (request.location().contains("Paris")) {
            temperature = 15;
        }
        else if (request.location().contains("Tokyo")) {
            temperature = 10;
        }
        else if (request.location().contains("San Francisco")) {
            temperature = 30;
        }

        return new MockWeatherService.Response(temperature, 15, 20, 2, 53, 45, MockWeatherService.Unit.C);
    };

OpenAiChatOptions options = OpenAiChatOptions.builder()
    .withModel(OpenAiApi.ChatModel.GPT_4_O.getValue())
    .withFunctionCallbacks(List.of(FunctionCallback.builder()
        .function("getCurrentWeather", this.weatherFunction)
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build()))
    .withToolContext(Map.of("sessionId", "123", "userId", "user456"))
    .build();

在这个例子中，weatherFunction被定义为一个 BiFunction，它同时接受请求和工具上下文作为参数。这允许你在函数逻辑中直接访问上下文。

然后，你可以在调用聊天模型时使用这些选项

UserMessage userMessage = new UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?");
ChatResponse response = chatModel.call(new Prompt(List.of(this.userMessage), options));

这种方法允许你将特定于会话或特定于用户的信息传递给你的函数，从而实现更具上下文性和个性化的响应。

附录

Spring AI 函数调用流程

下图说明了OpenAiChatModel函数调用的流程

openai chatclient function call

OpenAI API 函数调用流程

下图说明了 OpenAI API 函数调用的流程

示例代码OpenAiApiToolFunctionCallIT.java 提供了如何使用 OpenAI API 函数调用的完整示例。它基于OpenAI 函数调用教程。