1.1 工具调用简介

工具调用（也称为函数调用）是 AI 应用中的常见模式，它允许模型与一组 API 或工具进行交互，从而增强其功能。

工具主要用于：

• 信息检索:
  • 此类工具可用于从外部来源（例如数据库、Web 服务、文件系统或网络搜索引擎）检索信息。
  • 其目标是增强模型的知识，使其能够回答原本无法回答的问题。
  • 因此，它们可用于检索增强生成 (RAG) 场景。
  • 例如，可以使用此类工具检索给定位置的当前天气、检索最新新闻文章或查询数据库中的特定记录。
• 执行操作:
  • 此类工具可用于在软件系统中执行操作，例如发送电子邮件、在数据库中创建新记录、提交表单或触发工作流。
  • 其目标是自动化那些原本需要人工干预或显式编程的任务。
  • 例如，该工具可用于为与聊天机器人交互的客户预订航班、填写网页上的表单，或在代码生成场景中基于自动化测试（TDD）实现Java 类。

尽管我们通常将工具调用视为模型的一项功能，但实际上，工具调用逻辑是由客户端应用程序提供的。模型只能请求工具调用并提供输入参数，而应用程序则负责根据输入参数执行工具调用并返回结果。 模型永远无法访问任何作为工具提供的 API，这是一个至关重要的安全考量。

Spring AI 提供便捷的 API 来定义工具、解析模型发出的工具调用请求并执行工具调用。

以下各节概述了 Spring AI 中的工具调用功能。

• 查看聊天模型对比，了解哪些 AI 模型支持工具调用。
• 按照指南从已弃用的FunctionCallback API 迁移到 ToolCallback API。

1.2 快速入门

让我们来看看如何在 Spring AI 中使用工具调用。

我们将实现两个简单的工具：一个用于信息检索，一个用于执行操作。

1. 信息检索工具将用于获取用户所在时区的当前日期和时间。

2. 操作工具将用于设置指定时间的闹钟。

1.2.1 信息检索

人工智能模型无法获取实时信息。任何需要模型感知信息（例如当前日期或天气预报）的问题，模型都无法回答。但是，我们可以提供一个工具来获取这些信息，并在模型需要实时信息时调用该工具。

让我们在一个类中实现一个工具，用于获取用户所在时区的当前日期和时间DateTimeTools。该工具不接受任何参数。SpringLocaleContextHolder框架可以提供用户的时区信息。该工具将被定义为一个带有 @TimeZone 注解的方法@Tool。为了帮助模型理解何时调用此工具，我们将提供该工具功能的详细描述。

import java.time.LocalDateTime;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {

    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

}

接下来，让我们将工具提供给模型。

在这个例子中，我们将使用 ChatClientgetTardTime() 方法与模型进行交互。我们将通过传递 getTardTime() 方法的实例来为模型提供该工具DateTimeTools。tools()当模型需要知道当前日期和时间时，它会请求调用该工具。在内部，getTardTime() 方法ChatClient会调用该工具并将结果返回给模型，然后模型将使用工具调用结果来生成对原始问题的最终响应。

ChatModel chatModel = ...

String response = ChatClient.create(chatModel)
        .prompt("What day is tomorrow?")
        .tools(new DateTimeTools())
        .call()
        .content();

System.out.println(response);

输出结果类似于：

Tomorrow is 2015-10-21.

您可以再次尝试提出相同的问题。这次，请不要向模型提供工具。

输出结果将类似于：

I am an AI and do not have access to real-time information. Please provide the current date so I can accurately determine what day tomorrow will be.

翻译成中文就是：

我是一个人工智能，无法获取实时信息。请提供当前日期，以便我准确确定明天是哪一天。

如果没有该工具，模型就不知道如何回答这个问题，因为它无法确定当前的日期和时间。

1.2.2 采取行动

人工智能模型可以用来生成实现特定目标的计划。例如，模型可以生成预订丹麦之旅的计划。然而，模型本身并不具备执行该计划的能力。这时就需要工具来帮忙：它们可以用来执行模型生成的计划。

在上一个例子中，我们使用了一个工具来确定当前日期和时间。在这个例子中，我们将定义第二个工具，用于在特定时间设置闹钟。目标是设置一个 10 分钟后的闹钟，因此我们需要将这两个工具都提供给模型来完成这项任务。

我们将把新工具添加到DateTimeTools与之前相同的类中。新工具将接收一个参数，即 ISO-8601 格式的时间。该工具随后会在控制台打印一条消息，表明已为指定时间设置了闹钟。与之前一样，该工具被定义为一个带有注解的方法@Tool，我们还使用该注解提供详细描述，以帮助模型理解何时以及如何使用该工具。

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {

    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

    @Tool(description = "Set a user alarm for the given time, provided in ISO-8601 format")
    void setAlarm(String time) {
        LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("Alarm set for " + alarmTime);
    }

}

接下来，我们将这两个工具提供给模型使用。

我们将使用它们ChatClient与模型进行交互。我们将通过传递一个实例，并DateTimeTools经由相应的tools()方法将工具提供给模型。当我们请求设置一个 10 分钟后的闹钟时，模型首先需要知道当前的日期和时间。然后，它将使用当前的日期和时间来计算闹钟时间。最后，它将使用闹钟工具来设置闹钟。在内部，该工具ChatClient将处理来自模型的任何工具调用请求，并将任何工具调用的执行结果返回给模型，以便模型可以生成最终响应。

ChatModel chatModel = ...

String response = ChatClient.create(chatModel)
        .prompt("Can you set an alarm 10 minutes from now?")
        .tools(new DateTimeTools())
        .call()
        .content();

System.out.println(response);

在应用程序日志中，您可以检查闹钟是否已在正确的时间设置。