從 FunctionCallback 遷移到 ToolCallback API

本指南幫助您將 Spring AI 中已廢棄的 FunctionCallback API 遷移到新的 ToolCallback API。有關新 API 的更多資訊，請檢視工具呼叫文件。

變更概述

這些變更旨在改進和擴充套件 Spring AI 中的工具呼叫功能。此外，新 API 將術語從“函式”改為“工具”，以更好地與行業慣例保持一致。這涉及多項 API 變更，同時透過已廢棄的方法保持向後相容性。

主要變更

FunctionCallback → ToolCallback
FunctionCallback.builder().function() → FunctionToolCallback.builder()
FunctionCallback.builder().method() → MethodToolCallback.builder()
FunctionCallingOptions → ToolCallingChatOptions
ChatClient.builder().defaultFunctions() → ChatClient.builder().defaultTools()
ChatClient.functions() → ChatClient.tools()
FunctionCallingOptions.builder().functions() → ToolCallingChatOptions.builder().toolNames()
FunctionCallingOptions.builder().functionCallbacks() → ToolCallingChatOptions.builder().toolCallbacks()

遷移示例

1. 基本函式回撥

Before

FunctionCallback.builder()
    .function("getCurrentWeather", new MockWeatherService())
    .description("Get the weather in location")
    .inputType(MockWeatherService.Request.class)
    .build()

After

FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
    .description("Get the weather in location")
    .inputType(MockWeatherService.Request.class)
    .build()

2. ChatClient 用法

Before

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .functions(FunctionCallback.builder()
        .function("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .call()
    .content();

After

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .tools(FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .call()
    .content();

3. 基於方法的回撥函式

Before

FunctionCallback.builder()
    .method("getWeatherInLocation", String.class, Unit.class)
    .description("Get the weather in location")
    .targetClass(TestFunctionClass.class)
    .build()

After

var toolMethod = ReflectionUtils.findMethod(TestFunctionClass.class, "getWeatherInLocation");

MethodToolCallback.builder()
    .toolDefinition(ToolDefinition.builder(toolMethod)
        .description("Get the weather in location")
        .build())
    .toolMethod(toolMethod)
    .build()

或者使用宣告式方法

class WeatherTools {

    @Tool(description = "Get the weather in location")
    public void getWeatherInLocation(String location, Unit unit) {
        // ...
    }

}

您可以使用相同的 ChatClient#tools() API 註冊基於方法的工具回撥

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .tools(MethodToolCallback.builder()
        .toolDefinition(ToolDefinition.builder(toolMethod)
            .description("Get the weather in location")
            .build())
        .toolMethod(toolMethod)
        .build())
    .call()
    .content();

或者使用宣告式方法

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .tools(new WeatherTools())
    .call()
    .content();

4. 選項配置

Before

FunctionCallingOptions.builder()
    .model(modelName)
    .function("weatherFunction")
    .build()

After

ToolCallingChatOptions.builder()
    .model(modelName)
    .toolNames("weatherFunction")
    .build()

5. ChatClient 構建器中的預設函式

Before

ChatClient.builder(chatModel)
    .defaultFunctions(FunctionCallback.builder()
        .function("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .build()

After

ChatClient.builder(chatModel)
    .defaultTools(FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .build()

6. Spring Bean 配置

Before

@Bean
public FunctionCallback weatherFunctionInfo() {
    return FunctionCallback.builder()
        .function("WeatherInfo", new MockWeatherService())
        .description("Get the current weather")
        .inputType(MockWeatherService.Request.class)
        .build();
}

After

@Bean
public ToolCallback weatherFunctionInfo() {
    return FunctionToolCallback.builder("WeatherInfo", new MockWeatherService())
        .description("Get the current weather")
        .inputType(MockWeatherService.Request.class)
        .build();
}

破壞性變更

函式回撥中的 method() 配置已替換為使用 ToolDefinition 和 MethodToolCallback 更明確的方法工具配置。
當使用基於方法的回撥時，您現在需要使用 ReflectionUtils 顯式查詢方法並將其提供給構建器。或者，您可以使用帶有 @Tool 註解的宣告式方法。
對於非靜態方法，您現在必須同時提供方法和目標物件

MethodToolCallback.builder()
    .toolDefinition(ToolDefinition.builder(toolMethod)
        .description("Description")
        .build())
    .toolMethod(toolMethod)
    .toolObject(targetObject)
    .build()

已廢棄的方法

以下方法已廢棄，並將在未來版本中移除

ChatClient.Builder.defaultFunctions(String…)
ChatClient.Builder.defaultFunctions(FunctionCallback…)
ChatClient.RequestSpec.functions()

請改用它們的 tools 對應項。

使用 @Tool 的宣告式規範

現在您可以使用方法級註解 (@Tool) 向 Spring AI 註冊工具

class Home {

    @Tool(description = "Turn light On or Off in a room.")
    void turnLight(String roomName, boolean on) {
        // ...
        logger.info("Turn light in room: {} to: {}", roomName, on);
    }
}

String response = ChatClient.create(this.chatModel).prompt()
        .user("Turn the light in the living room On.")
        .tools(new Home())
        .call()
        .content();

附加說明

新 API 提供了工具定義和實現之間更好的分離。
工具定義可以在不同的實現中重用。
構建器模式已針對常見用例進行了簡化。
透過改進的錯誤處理，更好地支援基於方法的工具。

時間線

已廢棄的方法將在當前里程碑版本中保持向後相容性，但將在下一個里程碑版本中移除。建議儘快遷移到新 API。