函数调用

此页面描述了旧版的函数调用 API，该 API 已被弃用，并将在下一版本中移除。当前版本请参阅工具调用。更多信息请参阅迁移指南。

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

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

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

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

Spring AI 使这一过程变得简单，只需定义一个返回 java.util.Function 的 @Bean 定义，并在调用 ChatModel 时将 bean 名称作为选项提供即可。

底层实现中，Spring 会使用适当的适配器代码封装您的 POJO（即函数），从而实现与 AI 模型的交互，省去了编写繁琐的样板代码。底层基础设施的基础是 ToolCallback.java 接口以及配套的 Builder 工具类，用于简化 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 将创建一个 ToolCallback 实例，该实例添加了通过 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 schema 尽可能具有描述性，从而帮助 AI 模型选择正确的函数进行调用。

FunctionCallbackWithPlainFunctionBeanIT.java 演示了这种方法。

FunctionToolCallback 包装器

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

@Configuration
static class Config {

	@Bean
	public FunctionToolCallback weatherFunctionInfo() {

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

}

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

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

FunctionToolCallback 在内部根据 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().tools("CurrentWeather").build())); // 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

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

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

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

OpenAiChatModel chatModel = ...

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

var promptOptions = OpenAiChatOptions.builder()
	.toolCallbacks(List.of(FunctionToolCallback.builder("CurrentWeather", new MockWeatherService()) // (1) function name and instance
        .description("Get the weather in location") // (2) function description
        .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()
    .model(OpenAiApi.ChatModel.GPT_4_O.getValue())
    .toolCallbacks(List.of(FunctionToolCallback.builder("getCurrentWeather", this.weatherFunction)
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build()))
    .toolContext(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 函数调用教程。