Gemini Function Calling

函数调用让开发者可以在其代码中创建函数描述，然后将该描述传递给请求中的语言模型。来自模型的响应包括与描述匹配的函数的名称以及调用该函数所需的参数。你可以使用 VertexAiGeminiChatClient 注册自定义 Java 函数，并让 Gemini Pro 模型智能地选择输出 JSON 对象，其中包含调用一个或多个已注册函数的参数。这让你可以将 LLM 功能与外部工具和 API 连接起来。VertexAI Gemini Pro 模型经过训练，可以检测何时应调用函数，并响应遵循函数签名的 JSON。 VertexAI Gemini API 不会直接调用该函数；相反，该模型会生成 JSON，你可以使用 JSON 在你的代码中调用函数，并将结果返回到该模型以完成对话。 Spring AI 提供灵活且用户友好的方法来注册和调用自定义函数。通常，自定义函数需要提供函数 name、description 和函数调用 signature（作为开放 API 架构）来让模型知道该函数期望哪些参数。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 极大地简化了你需要为支持函数调用而编写的代码。它为你代理了函数调用会话。你可以简单地提供你的函数定义，作为 @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

借助 VertexAiGeminiChatClient 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 模型挑选要调用的正确函数。

FunctionCallWithFunctionBeanIT.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();
	}
	...
}

它包装了第三方 MockWeatherService 函数，并将其作为 CurrentWeather 函数注册到 VertexAiGeminiChatClient 中。它还提供了描述 (2)，并将架构类型设置为开放 API 类型 (3)。

默认响应转换器对响应对象执行 JSON 序列化。

FunctionCallbackWrapper 内部将函数调用签名解析为基于 MockWeatherService.Request 类的函数调用签名，并内部生成函数调用的 Open API 模式。

Specifying functions in Chat Options

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

VertexAiGeminiChatClient 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),
		VertexAiGeminiChatOptions.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

FunctionCallWithFunctionWrapperIT.java 测试对此方法进行了演示。

Register/Call Functions with Prompt Options

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

VertexAiGeminiChatClient chatClient = ...

UserMessage userMessage = new UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?  Use Multi-turn function calling.");

var promptOptions = VertexAiGeminiChatOptions.builder()
	.withFunctionCallbacks(List.of(FunctionCallbackWrapper.builder(new MockWeatherService())
		.withName("CurrentWeather")
		.withSchemaType(SchemaType.OPEN_API) // IMPORTANT!!
		.withDescription("Get the weather in location")
		.build()))
	.build();

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

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

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

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