Function Calling

你可以使用 OpenAiChatClient 注册自定义 Java 函数,并让 OpenAI 模型智能地选择输出 JSON 对象,其中包含调用一个或多个已注册函数的参数。这让你可以将 LLM 功能与外部工具和 API 连接起来。OpenAI 模型经过训练,可以检测何时应调用函数,并响应遵循函数签名的 JSON。 OpenAI API 不会直接调用该函数;相反,该模型会生成 JSON,你可以使用 JSON 在你的代码中调用函数,并将结果返回到该模型以完成对话。 Spring AI 提供灵活且用户友好的方法来注册和调用自定义函数。通常,自定义函数需要提供函数 namedescription 和函数调用 signature(作为 JSON 架构)来让模型知道该函数期望哪些参数。description 帮助模型了解何时调用函数。 作为开发者,你需要实现接收 AI 模型发送的函数调用参数并向模型响应结果的函数。你的函数可以依次调用其他第三方服务来提供结果。 Spring AI 让这件事变得像定义一个 @Bean 定义一样简单,该定义返回一个 java.util.Function,并在调用 ChatClient 时将 bean 名称作为一个选项提供。 底层 Spring 将你的 POJO(函数)与适当的适配器代码打包在一起,使之能够与 AI 模型交互,省去了编写繁琐样板代码的步骤。底层基础架构的基础是 FunctionCallback.java 接口以及配套的 FunctionCallbackWrapper.java 实用程序类,对 Java 回调函数的实现和注册进行了简化。

How it works

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

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

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

模型客户端交互在 Spring AI Function Calling Flow 图表中说明。

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

Quick Start

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

当提示模型的响应需要回答诸如 `"波士顿的天气怎么样?"`此类问题时,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);
	}
}

Registering Functions as Beans

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

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

Plain Java Functions

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

在内部,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 模型确定调用哪个客户端函数。

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

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

FunctionCallback Wrapper

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

@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,并将其注册为 OpenAiChatClient 中的 CurrentWeather 函数。它还提供了描述 (2) 和可选的响应转换器 (3),以将响应转换为模型所期望的文本。

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

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

Specifying functions in Chat Options

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

OpenAiChatClient chatClient = ...

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

ChatResponse response = chatClient.call(new Prompt(List.of(userMessage),
		OpenAiChatOptions.builder().withFunction("CurrentWeather").build())); // (1) 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

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

Register/Call Functions with Prompt Options

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

OpenAiChatClient chatClient = ...

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

var promptOptions = OpenAiChatOptions.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));

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

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

FunctionCallbackInPromptIT.java 集成测试给出了使用 OpenAiChatClient 注册函数并在提示请求中使用它的完整示例。

Appendices:

Spring AI Function Calling Flow

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

openai chatclient function call

OpenAI API Function Calling Flow

以下图表展示了 OpenAI API Function Calling 的流程:

openai function calling flow

OpenAiApiToolFunctionCallIT.java 给出了如何使用 OpenAI API 函数调用的完整示例。它基于 OpenAI Function Calling tutorial