Gemini 函数调用

警告：Gemini Pro 似乎无法正确处理函数名称。并行函数调用也不再可用。

函数调用允许开发者在代码中创建函数描述，然后在请求中将该描述传递给语言模型。模型的响应包括与描述匹配的函数名称以及用于调用的参数。

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

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

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

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

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

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

工作原理

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

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

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

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

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

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

纯 Java 函数

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

在内部，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> weatherFunction1() {
		return new MockWeatherService();
	}
	...
}

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

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

@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 包装器

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

@Configuration
static class Config {

	@Bean
	public FunctionCallback weatherFunctionInfo() {

		return FunctionCallback.builder()
			.description("Get the current weather in a given location") // (2) function description
			.schemaType(SchemaType.OPEN_API_SCHEMA) // (3) schema type. Compulsory for Gemini function calling.
			.function("CurrentWeather", new MockWeatherService()) // (1) function name and instance
			.inputType(MockWeatherService.Request.class) // (4) input type
			.build();
	}
	...
}

它包装了第三方 MockWeatherService 函数，并将其作为 CurrentWeather 函数注册到 VertexAiGeminiChatModel 中。它还提供描述 (2)、OpenAPI 类型到 Schema 类型的映射 (3) 和用于生成函数调用 OpenAPI Schema 的输入类型 (4)。

默认的响应转换器会对 Response 对象进行 JSON 序列化。

FunctionCallback 在内部根据 MockWeatherService.Request 类解析函数调用签名，并在内部为函数调用生成 OpenAPI Schema。

在聊天选项中指定函数

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

VertexAiGeminiChatModel chatModel = ...

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

ChatResponse response = this.chatModel.call(new Prompt(List.of(this.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 测试演示了这种方法。

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

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

VertexAiGeminiChatModel chatModel = ...

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(FunctionCallback.builder()
		.schemaType(SchemaType.OPEN_API_SCHEMA) // IMPORTANT!!
		.description("Get the weather in location")
		.function("CurrentWeather", new MockWeatherService())
		.inputType(MockWeatherService.Request.class)
		.build()))
	.build();

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

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

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

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