函数调用

DeepSeek V3 中英对照 OpenAI Function Calling (Deprecated) Function Calling

注意

本页面描述了旧版本的 Function Calling API，该版本已被弃用，并计划在下一个版本中移除。当前版本可在 Tool Calling 查看。更多信息请参阅 迁移指南。

你可以通过 OpenAiChatModel 注册自定义的 Java 函数，并让 OpenAI 模型智能地选择输出一个包含参数的 JSON 对象，以调用一个或多个已注册的函数。这使得你可以将大语言模型（LLM）的能力与外部工具和 API 连接起来。OpenAI 模型经过训练，能够检测何时应该调用函数，并以符合函数签名的 JSON 格式进行响应。

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

Spring AI 提供了灵活且用户友好的方式来注册和调用自定义函数。通常，自定义函数需要提供一个函数 名称、描述 以及函数调用 签名（以 JSON schema 形式），以便让模型知道函数期望的参数。描述 帮助模型理解何时调用该函数。

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

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

在底层，Spring 将你的 POJO（即函数）包裹在适当的适配器代码中，使其能够与 AI 模型进行交互，从而避免了编写繁琐的样板代码。其基础架构的核心是 FunctionCallback.java 接口以及配套的 Builder 工具类，它们简化了 Java 回调函数的实现和注册过程。

工作原理

假设我们希望 AI 模型能够响应它没有的信息，例如某个地点的当前温度。

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

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

模型与客户端的交互在 Spring AI 函数调用流程 图中进行了说明。

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);
	}
}

java

将函数注册为 Beans

通过 OpenAiChatModel 自动配置，你有多种方式将自定义函数注册为 Spring 上下文中的 bean。

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

纯 Java 函数

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

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

}

java

@Description 注解是可选的，它提供了一个函数描述，帮助模型理解何时调用该函数。设置这一属性非常重要，因为它有助于 AI 模型确定调用哪个客户端函数。

另一种提供函数描述的方法是使用 @JsonClassDescription 注解在 MockWeatherService.Request 上：

@Configuration
static class Config {

	@Bean
	public Function<Request, Response> currentWeather() { // bean name as function name
		return new MockWeatherService();
	}

}

@JsonClassDescription("Get the weather in location") // // function description
public record Request(String location, Unit unit) {}

java

最佳实践是为请求对象添加注释信息，以便生成的函数 JSON 模式尽可能具有描述性，从而帮助 AI 模型选择正确的函数进行调用。

FunctionCallbackWithPlainFunctionBeanIT.java 展示了这种方法。

FunctionCallback 包装器

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

@Configuration
static class Config {

	@Bean
	public FunctionCallback weatherFunctionInfo() {

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

}

java

它封装了第三方 MockWeatherService 函数，并将其注册为 OpenAiChatModel 的 CurrentWeather 函数。它还提供了描述（2）和输入类型（3），用于生成函数调用的 JSON 模式。

:::注意
默认情况下，响应转换器会对 Response 对象执行 JSON 序列化。
:::

备注

FunctionCallback 内部基于 MockWeatherService.Request 类解析函数调用签名。

在聊天选项中指定函数

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

OpenAiChatModel chatModel = ...

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

ChatResponse response = this.chatModel.call(new Prompt(this.userMessage,
		OpenAiChatOptions.builder().function("CurrentWeather").build())); // Enable the function

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

java

上述用户问题将触发对 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

OpenAiFunctionCallbackIT.java 测试示例展示了这种方法。

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

除了自动配置之外，你还可以动态地为你的 Prompt 请求注册回调函数：

OpenAiChatModel chatModel = ...

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

var promptOptions = OpenAiChatOptions.builder()
	.functionCallbacks(List.of(FunctionCallback.builder()
        .function("CurrentWeather", new MockWeatherService()) // (1) function name and instance
        .description("Get the weather in location") // (2) function description
        .inputType(MockWeatherService.Request.class) // (3) function input type
        .build())) // function code
	.build();

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

java

备注

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

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

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

工具上下文支持

Spring AI 现在支持通过工具上下文将额外的上下文信息传递给函数回调。此功能允许您在函数执行期间提供可用的额外数据，从而增强了函数调用的灵活性和功能。

作为 java.util.BiFunction 的第二个参数传入的上下文信息。ToolContext 包含一个不可变的 Map<String,Object>，允许你访问键值对。

如何使用工具上下文

你可以在构建聊天选项时设置工具上下文，并使用 BiFunction 作为回调函数：

BiFunction<MockWeatherService.Request, ToolContext, MockWeatherService.Response> weatherFunction =
    (request, toolContext) -> {
        String sessionId = (String) toolContext.getContext().get("sessionId");
        String userId = (String) toolContext.getContext().get("userId");

        // Use sessionId and userId in your function logic
        double temperature = 0;
        if (request.location().contains("Paris")) {
            temperature = 15;
        }
        else if (request.location().contains("Tokyo")) {
            temperature = 10;
        }
        else if (request.location().contains("San Francisco")) {
            temperature = 30;
        }

        return new MockWeatherService.Response(temperature, 15, 20, 2, 53, 45, MockWeatherService.Unit.C);
    };

OpenAiChatOptions options = OpenAiChatOptions.builder()
    .model(OpenAiApi.ChatModel.GPT_4_O.getValue())
    .functionCallbacks(List.of(FunctionCallback.builder()
        .function("getCurrentWeather", this.weatherFunction)
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build()))
    .toolContext(Map.of("sessionId", "123", "userId", "user456"))
    .build();

java

在这个示例中，weatherFunction 被定义为一个 BiFunction，它接受请求和工具上下文作为参数。这使得你可以在函数逻辑中直接访问上下文。

然后，你可以在调用聊天模型时使用这些选项：

UserMessage userMessage = new UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?");
ChatResponse response = chatModel.call(new Prompt(List.of(this.userMessage), options));

java

这种方法允许你将特定会话或特定用户的信息传递给函数，从而实现更具上下文性和个性化的响应。

附录:

Spring AI 函数调用流程

下图展示了 OpenAiChatModel 函数调用的流程：

OpenAI API 函数调用流程

下图展示了 OpenAI API Function Calling 的流程：

函数调用指南

OpenAiApiToolFunctionCallIT.java 提供了一个完整的示例，展示了如何使用 OpenAI API 的函数调用功能。该示例基于 OpenAI 函数调用教程。