Azure OpenAI Function Calling :: Spring AI Reference

函数调用允许开发人员在他们的代码中创建一个函数描述，然后将该描述传递给语言模型进行请求。模型的响应包括与描述相匹配的函数名称以及调用它的参数。

您可以向AzureOpenAiChatClient注册自定义Java函数，并使模型智能地选择输出一个包含调用注册函数之一或多个的参数的JSON对象。这使您能够将LLM能力与外部工具和API连接起来。Azure模型经过训练，可以检测到何时应该调用函数，并用符合函数签名的JSON进行响应。

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

Spring AI提供了灵活且用户友好的方式来注册和调用自定义函数。通常，自定义函数需要提供函数name，description和函数调用signature（作为JSON schema），以让模型知道函数期望的参数。 description帮助模型理解何时调用函数。

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

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

在幕后，Spring将您的POJO（函数）与适当的适配器代码一起包装，以启用与AI模型的交互，使您免于编写繁琐的样板代码。基础架构的基础是FunctionCallback.java接

快速入门

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

当模型对提示的回应需要回答问题时，比如“波士顿的天气怎么样？”，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

通过AzureOpenAiChatClient自动配置，您有多种方式可以在Spring上下文中注册自定义函数。

我们首先介绍最符合POJO的选项。

普通Java函数

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

在内部，Spring AIChatClient将创建一个FunctionCallbackWrapper的实例，用于添加通过AI模型调用它时的逻辑。@Bean的名称作为ChatOption进行传递。

@Configuration
static class Config {

	@Bean
	@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名称作为函数名称。
		return new MockWeatherService();
	}
	...
}

@JsonClassDescription("获取位置的天气") // (2) 函数描述
public record Request(String location, Unit unit) {}

FunctionCallWithFunctionBeanIT.java演示了这种方法。

FunctionCallback包装器

FunctionCallbackWrapper包装器：

@Configuration
static class Config {

	@Bean
	public FunctionCallback weatherFunctionInfo() {

		return FunctionCallbackWrapper.builder(new MockWeatherService())
			.withName("CurrentWeather") // (1) 函数名称
			.withDescription("获取给定位置的当前天气") // (2) 函数描述
			.build();
	}
	...
}

MockWeatherService函数包装并注册为 CurrentWeather函数，同时提供描述（2）。

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

FunctionCallbackWrapper根据MockWeatherService.Request类的函数调用签名内部解析，同时为函数调用生成JSON模式。

在聊天选项中指定函数

CurrentWeather函数，您需要在提示请求中启用它：

AzureOpenAiChatClient chatClient = ...

UserMessage userMessage = new UserMessage("旧金山、东京和巴黎的天气如何？");

ChatResponse response = chatClient.call(new Prompt(List.of(userMessage),
		AzureOpenAiChatOptions.builder().withFunction("CurrentWeather").build())); // (1) 启用函数

logger.info("Response: {}", response);

CurrentWeather函数的调用（每个城市一次），最终的响应将类似于：

以下是所请求城市的当前天气：
- 美国旧金山：30.0°C
- 日本东京：10.0°C
- 法国巴黎：15.0°C

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

注册/调用具有提示选项的函数

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

AzureOpenAiChatClient chatClient = ...

UserMessage userMessage = new UserMessage("旧金山，东京和巴黎的天气如何？ 使用多轮函数调用。");

var promptOptions = AzureOpenAiChatOptions.builder()
	.withFunctionCallbacks(List.of(FunctionCallbackWrapper.builder(new MockWeatherService())
		.withName("CurrentWeather")
		.withDescription("获取位置的天气")
		.build()))
	.build();

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

提示注册的函数在此请求的持续时间内默认为启用状态。

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

FunctionCallWithPromptFunctionIT.java 集成测试提供了如何注册函数与 AzureOpenAiChatClient 并在提示请求中使用它的完整示例。

Azure OpenAI函数调用