從 FunctionCallback 遷移到 ToolCallback API

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

變更概覽

這些變更是 Spring AI 中改進和擴充套件工具呼叫能力的廣泛工作的一部分。在新 API 中，我們將術語從“functions”改為“tools”，以便更好地與行業慣例保持一致。這涉及多項 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. 基本 Function Callback

之前

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

之後

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

2. ChatClient 用法

之前

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

之後

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. 基於方法（Method-Based）的 Function Callbacks

之前

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

之後

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 來註冊基於方法的 Tool Callbacks

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. 選項配置

之前

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

之後

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

5. ChatClient Builder 中的預設 Functions

之前

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

之後

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

6. Spring Bean 配置

之前

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

之後

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

破壞性變更

Function callbacks 中的 method() 配置已被替換為使用 ToolDefinition 和 MethodToolCallback 的更顯式的方法工具配置。
使用基於方法的回撥時，您現在需要使用 ReflectionUtils 顯式查詢方法並將其提供給 Builder。或者，您可以使用帶有 @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 更好地分離了工具定義和實現。
工具定義可以在不同的實現中重用。
對於常見用例，Builder 模式已得到簡化。
更好地支援基於方法的工具，並改進了錯誤處理。

時間線

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