函数调用允许开发者在代码中创建一个函数的描述，然后将这个描述传递给请求中的一个语言模型。该模型的响应包括与描述相匹配的函数名称以及调用它的参数。
您可以使用 VertexAiGeminiChatClient 注册自定义的Java函数，并且让Gemini Pro模型智能地选择输出一个包含调用一个或多个注册函数参数的JSON对象。这样您就可以将LLM的功能与外部工具和API连接起来。VertexAI Gemini Pro模型经过训练，能够检测何时应该调用函数，并以符合函数签名的JSON格式响应。
VertexAI Gemini API不会直接调用函数；相反，模型会生成您可以在代码中用来调用函数的JSON，并将结果返回给模型以完成对话。
Spring AI提供了灵活且用户友好的方式来注册和调用自定义函数。通常，自定义函数需要提供函数`name`（名称）、description（描述）和函数调用`signature`（作为开放API架构）来让模型知道函数期望什么参数。description（描述）帮助模型理解何时调用该函数。
作为一名开发者，你需要实现一个函数，这个函数接收来自AI模型发送的函数调用参数，并将结果返回给模型。你的函数可以依次调用其他第三方服务来提供结果。
Spring AI 使这变得很简单，只需定义一个返回 java.util.Function 的 @Bean 声明，并在调用 ChatClient 时提供 bean 名称作为一个选项即可。
在底层，Spring通过合适的适配器代码包装你的POJO（函数），使其能够与AI模型交互，免去了你编写繁琐的样板代码的麻烦。底层基础设施的基础是[FunctionCallback.java](FunctionCallbackWrapper.java(https://github.com/spring-projects/spring-ai/blob/main/spring-ai-core/src/main/java/org/springframework/ai/model/function/FunctionCallbackWrapper.java)实用类，以简化Java回调函数的实现和注册。
它是如何工作的
假设我们希望AI模型能够回应它没有的信息，例如给定位置的当前温度。
我们可以提供关于我们自己函数的元数据给AI模型，使其在处理你的提示时能够检索到这些信息。
例如，如果在处理某个提示过程中，AI模型确定它需要关于给定位置的温度的额外信息，它将启动一个服务器端生成的请求/响应交互。AI模型调用客户端函数。AI模型以JSON形式提供方法调用的详细信息，客户端有责任执行该函数并返回响应。
Spring AI大大简化了您需要编写以支持函数调用的代码。它为您代理了函数调用会话。您只需提供您的函数定义作为`@Bean`，然后在您的提示选项中提供函数的bean名称。您也可以在您的提示中引用多个函数bean的名称。
快速开始
让我们创建一个通过调用我们自己的函数来回答问题的聊天机器人。为了支持聊天机器人的回答，我们将注册我们自己的函数，该函数接受一个位置并返回该位置的当前天气。
当模型需要回答像`"What’s the weather like in Boston?"`这样的问题时，人工智能模型将调用客户端，将位置值作为参数传递给函数。这种类似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);
}
}将函数注册为Beans
通过链接:../vertexai-gemini-chat.html#_auto_configuration[VertexAiGeminiChatClient自动配置]，您可以通过多种方式将自定义函数注册为Spring上下文中的bean。
我们从描述最对POJO友好的选项开始。
纯Java函数
在这种方法中，你可以在应用程序上下文中定义`@Beans`，就像定义任何其他Spring管理的对象一样。
在内部，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模型选择正确的函数进行调用。
链接：https://github.com/spring-projects/spring-ai/blob/main/spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/gemini/tool/FunctionCallWithFunctionBeanIT.java[FunctionCallWithFunctionBeanIT.java] 演示了这种方法。
函数回调包装器
注册函数的另一种方式是创建一个像这样的`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）。
|
Note
|
默认的响应转换器对Response对象进行JSON序列化。 |
|
Note
|
FunctionCallbackWrapper` 内部根据 MockWeatherService.Request 类解析函数调用签名，并内部为函数调用生成一个 Open API 模式。
|
在聊天选项中指定函数
要让模型知道并调用你的`CurrentWeather`函数，你需要在你的提示请求中启用它：
VertexAiGeminiChatClient chatClient = ...
UserMessage userMessage = new UserMessage("旧金山、东京和巴黎的天气怎么样？");
ChatResponse response = chatClient.call(new Prompt(List.of(userMessage),
VertexAiGeminiChatOptions.builder().withFunction("CurrentWeather").build())); // (1) Enable the function
logger.info("Response: {}", response);上述用户问题将触发对`CurrentWeather`函数的3次调用（每个城市一次），最终的响应将类似于此：
以下是所请求城市的当前天气状况： - 旧金山，加州：30.0°C - 东京，日本：10.0°C - 巴黎，法国：15.0°C
链接：https://github.com/spring-projects/spring-ai/blob/main/spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/gemini/tool/FunctionCallWithFunctionWrapperIT.java[FunctionCallWithFunctionWrapperIT.java] 测试演示了这种方法。
注册/调用带有提示选项的函数
除了自动配置之外，你还可以动态地为你的Prompt请求注册回调函数：
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));|
Note
|
在提示中注册的函数默认在此请求期间启用。 |
这种方法允许根据用户输入动态选择调用不同的函数。
'''The FunctionCallWithPromptFunctionIT.java integration test provides a complete example of how to register a function with the VertexAiGeminiChatClient and use it in a prompt request.'''集成测试提供了一个如何在`VertexAiGeminiChatClient`中注册函数并在提示请求中使用它的完整示例。