Azure OpenAI Function Calling (已弃用)

本页描述的是 Function Calling API 的旧版本，该版本已被弃用，并计划在下一版本中移除。当前版本可在工具调用中获取。有关更多信息，请参阅迁移指南。

函数调用 (Function calling) 允许开发者在其代码中创建函数描述，然后将该描述作为请求的一部分传递给语言模型。模型响应包含与描述匹配的函数名称及其调用时所需的参数。

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

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

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

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

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

在底层，Spring 使用适当的适配器代码包装您的 POJO（即函数），使其能够与 AI 模型进行交互，从而节省您编写繁琐的样板代码。底层基础设施的基础是 ToolCallback.java 接口以及配套的 Builder 工具类，用于简化 Java 回调函数的实现和注册。

工作原理

假设我们希望 AI 模型能够回应它本身不具备的信息，例如给定位置的当前温度。

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

例如，如果在处理 prompt 的过程中，AI 模型确定需要有关给定位置温度的附加信息，它将发起一个由服务器端生成的请求/响应交互。AI 模型会调用客户端函数。AI 模型以 JSON 格式提供方法调用详细信息，客户端负责执行该函数并返回响应。

Spring AI 大大简化了支持函数调用所需的代码编写工作。它为您代理函数调用交互过程。您只需将函数定义提供为 @Bean，然后在 prompt 选项中提供该函数的 bean 名称即可。您还可以在 prompt 中引用多个函数 bean 名称。

快速入门

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

当模型响应 prompt 需要回答诸如“波士顿天气如何？”这样的问题时，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

使用 AzureOpenAiChatModelAuto-Configuration，您可以通过多种方式将自定义函数注册为 Spring 上下文中的 bean。

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

普通 Java 函数

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

在内部，Spring AI ChatModel 将创建一个 ToolCallback 实例，该实例添加了通过 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 schema 尽可能具有描述性，从而帮助 AI 模型选择正确的函数进行调用。

FunctionCallWithFunctionBeanIT.java 演示了这种方法。

ToolCallback 包装器

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

@Configuration
static class Config {

	@Bean
	public FunctionToolCallback weatherFunctionInfo() {

		return FunctionToolCallback.builder("CurrentWeather", new MockWeatherService()) // (1) function name
			.description("Get the current weather in a given location") // (2) function description
			.inputType(MockWeatherService.Request.class) // (3) function input type
			.build();
	}
	...
}

它包装了第三方 MockWeatherService 函数，并将其注册为 AzureAiChatModel 的 CurrentWeather 函数，并提供了描述 (2)。

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

FunctionToolCallback 内部基于 MockWeatherService.Request 类解析函数调用签名，并在内部为函数调用生成 JSON schema。

在聊天选项中指定函数

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

AzureOpenAiChatModel 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),
		AzureOpenAiChatOptions.builder().tools("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 测试演示了这种方法。

使用 Prompt 选项注册/调用函数

除了自动配置之外，您还可以通过 prompt 请求动态地注册回调函数

AzureOpenAiChatModel chatModel = ...

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

var promptOptions = AzureOpenAiChatOptions.builder()
	.toolCallbacks(List.of(FunctionToolCallback.builder("CurrentWeather", new MockWeatherService()) // (1) function name and instance
			.description("Get the current weather in a given location") // (2) function description
			.inputType(MockWeatherService.Request.class) // (3) function input type
			.build()))
	.build();

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

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

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

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