LangChain4J中的工具鏈，你知道嗎？

作者：江南一點雨 2025-05-07 02:22:00

人工智能

大語言模型（LLM）除了生成文本，還可以通過工具調用觸發特定操作。該機制允許開發者為模型定義功能函數（如數學計算、API 調用等），當模型識別用戶需求需要外部工具輔助時，會在響應中表達調用意圖，開發者根據此意圖執行工具并將結果返回給模型。

咱們繼續來聊 langchain4j。

最近松哥和大伙聊的基本上都是大模型應用開發的入門知識，松哥這邊后面會開始做集團的知識庫，到時候再和大家分享一些項目中的實踐經驗。

一、Function Calling

特別是在一些涉及到數學運算的場景，大家知道大模型并不擅長于此，如果能夠直接調用我們自己的 API，就會方便很多。或者是一些涉及到內部 API 調用的場景，通過 Function Calling 就可以非常方便的實現。

1.1 三要素

名稱：明確的功能標識（如squareRoot）
描述：說明功能及適用場景（如"計算數的平方根"）
參數說明：每個參數的語義定義（如x表示待計算數值）

1.2 執行流程

通過工具調用機制，大模型突破了自身在實時性、準確性和功能擴展性方面的限制。

開發者需要重點掌握工具定義規范、執行流程編排和錯誤處理策略，結合 ReAct 等框架實現更智能的 AI 應用。最新技術如 LLMCompiler 的并行調用優化，以及 OpenManus 的任務分解機制，正在推動該領域向更高階的自主智能演進。

二、兩種方案

LangChain4j 中對于工具的調用提供了兩種不同的抽象層次。

2.1 Low-Level

Low-Level 直接使用 ChatLanguageModel 和 ToolSpecification API 來實現。Low-Level 具有如下一些特點：

完全控制：開發者需手動定義工具規格（ToolSpecification），包括工具名稱、描述、參數結構（JSON Schema）等。
靈活性強：適用于復雜場景，如第三方 API 集成或需要動態配置參數。
開發成本高：需編寫大量膠水代碼處理消息構建、工具執行及結果反饋。

適用場景：

需要精細控制工具邏輯（如參數校驗、錯誤處理）
集成非標準接口的外部服務

2.2 High-Level

High-Level 是通過 AI Services 和 @Tool 注解的 Java 方法High-Level 具有如下一些特點：

聲明式開發：使用 @Tool 注解自動生成工具規格，無需手動定義。
自動化流程：框架自動處理工具調用、結果注入和多輪對話管理。
代碼簡潔：隱藏底層復雜度，類似 Spring Data JPA 的 Repository 接口。

適用場景：

快速構建標準化工具（如內部業務 API）
需要與 Spring Boot 集成的項目

接下來我會逐一和大家介紹這兩種方案。

三、Low-Level

下面我們通過一個完整的天氣查詢案例，展示如何在 LangChain4j 中手動構造ToolSpecification并實現工具調用流程。

3.1 定義工具規格

3.1.1 手動定義

// 步驟1：手動構建天氣查詢工具規格
ToolSpecification weatherTool = ToolSpecification.builder()
    .name("getWeather")
    .description("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調用")
    .parameters(JsonObjectSchema.builder()
        .addStringProperty("city", "需要查詢的城市名稱，如北京、London")
        .addEnumProperty("unit", List.of("CELSIUS", "FAHRENHEIT"), "溫度單位，默認使用CELSIUS")
        .required("city")  // 顯式聲明必填參數
        .build())
    .build();

List<ToolSpecification> toolSpecifications = List.of(weatherTool);

關鍵設計原則：

命名規范：getWeather采用動詞+名詞結構，明確功能定位
描述清晰：包含觸發條件（"當用戶詢問未來 24 小時天氣時調用"）
參數約束：

城市參數添加示例值增強可理解性
溫度單位使用枚舉類型約束取值范圍
通過 required() 顯式標記必填參數

3.1.2 注解定義

也可以利用注解工具自動定義這個規格，如下：

class WeatherTools {

    @Tool("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調用")
    String getWeather(@P("需要查詢的城市名稱，如北京、London") String city, String temperatureUnit) {
        return "2025-03-16深圳天氣：多云轉晴，氣溫18-25°C，濕度65%";
    }
}
List<ToolSpecification> toolSpecifications = ToolSpecifications.toolSpecificationsFrom(WeatherTools.class);

3.2 完整交互

步驟1：初始請求構建

// 步驟1：構造初始聊天請求
ChatRequest request = ChatRequest.builder()
    .messages(UserMessage.from("2025年3月16日深圳的天氣如何？"))
    .toolSpecifications(toolSpecifications)
    .build();

// 發送請求并獲取響應
ChatResponse response = model.chat(request);
AiMessage aiMessage = response.aiMessage();

此時若模型判斷需要調用工具，aiMessage.toolExecutionRequests()將包含：

{
  "name": "getWeather",
  "arguments": {"city": "深圳", "unit": "CELSIUS"}
}

步驟2：工具執行與結果反饋

// 步驟2：執行工具邏輯（模擬實現）
if (aiMessage.hasToolExecutionRequests()) {
    ToolExecutionRequest request = aiMessage.toolExecutionRequests().get(0);
    Map<String, Object> args = parseJson(request.arguments());
    
    // 模擬工具執行（實際應調用外部API）
    String result = "2025-03-16深圳天氣：多云轉晴，氣溫18-25°C，濕度65%";
    
    // 構造結果消息
    ToolExecutionResultMessage resultMsg = ToolExecutionResultMessage.from(request, result);
    
    // 構建二次請求
    ChatRequest followupRequest = ChatRequest.builder()
        .messages(List.of(
            UserMessage.from("2025年3月16日深圳的天氣如何？"),
            aiMessage,
            resultMsg
        ))
        .toolSpecifications(toolSpecifications)
        .build();
    
    // 獲取最終響應
    ChatResponse finalResponse = model.chat(followupRequest);
    System.out.println(finalResponse.aiMessage().text()); 
    // 輸出："2025年3月16日深圳將有多云轉晴天氣，溫度范圍18-25攝氏度"
}

3.3 技術要點

3.3.1 參數結構

JsonObjectSchema.builder()
    .addStringProperty("city", "城市中文或英文名稱，如'New York'需轉換為'紐約'")
    .addEnumProperty("unit", List.of("CELSIUS", "FAHRENHEIT"), 
        "單位轉換需求，如用戶特別說明華氏度時使用")
    .build()

類型校驗：通過addStringProperty/addEnumProperty確保參數合法性
語義增強：在描述中補充數據轉換規則（如英文城市名轉中文）

3.3.2 異常處理機制

try {
    // 工具執行邏輯
} catch (InvalidCityException e) {
    return ToolExecutionResultMessage.error(request, "城市名稱無效: " + e.getMessage());
} catch (ApiTimeoutException e) {
    return ToolExecutionResultMessage.error(request, "天氣接口響應超時");
}

錯誤碼規范：定義業務異常類型輔助模型理解
錯誤信息結構化：通過error()方法返回標準錯誤格式

3.3.3 多工具協作模式

// 添加多個工具規格
ToolSpecification airQualityTool = ToolSpecification.builder()
    .name("getAirQuality")
    .description("獲取城市空氣質量指數，當用戶詢問 PM2.5 或空氣質量時調用")
    .parameters(/* 參數定義 */)
    .build();

List<ToolSpecification> tools = List.of(weatherTool, airQualityTool);

工具組合策略：天氣與空氣質量工具形成互補
調用優先級：通過描述中的觸發條件引導模型選擇

四、High-Level

4.1 核心機制

@Tool 注解驅動開發，主要是通過 Java 注解自動生成工具規格，無需手動定義 JSON Schema。

@Tool("計算兩個數之和")
public double add(@P("第一個數") int a, 
                  @P(value = "第二個數", required = false) Integer b) {
    return a + (b != null ? b : 0);
}

自動生成效果：

{
  "name": "add",
  "description": "計算兩個數之和",
  "parameters": {
    "type": "object",
    "properties": {
      "a": {"type": "integer", "description": "第一個數"},
      "b": {"type": "integer", "description": "第二個數"}
    },
    "required": ["a"]
  }
}

4.2 交互時序

4.3 代碼實踐

來看個具體的代碼案例吧，也是官方給的案例：

public class CalculatorDemo01 {
    staticclass Calculator {

        @Tool("計算字符串的長度")
        int stringLength(String s) {
            System.out.println("計算字符串的長度 s='" + s + "'");
            return s.length();
        }

        @Tool("計算兩個數的和")
        int add(int a, int b) {
            System.out.println("計算兩個數的和 a=" + a + ", b=" + b);
            return a + b;
        }

        @Tool("計算一個數的平方根")
        double sqrt(int x) {
            System.out.println("計算一個數的平方根 x=" + x);
            return Math.sqrt(x);
        }
    }

    public static void main(String[] args) {

        ChatLanguageModel model = ZhipuAiChatModel.builder()
                .apiKey(API_KEY)
                .model("glm-4")
                .temperature(0.6)
                .maxToken(1024)
                .maxRetries(1)
                .callTimeout(Duration.ofSeconds(60))
                .connectTimeout(Duration.ofSeconds(60))
                .writeTimeout(Duration.ofSeconds(60))
                .readTimeout(Duration.ofSeconds(60))
                .build();

        Assistant assistant = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .tools(new Calculator())
                .chatMemory(MessageWindowChatMemory.withMaxMessages(10))
                .build();

        String question = "字符串 \"hello\" 和 \"world\" 長度總和的平方根是多少?";

        String answer = assistant.chat(question);

        System.out.println(answer);
    }
}

來看下執行結果：

圖片

上面代碼比較簡單，就不啰嗦解釋了。

注意，在 @Tool 注解中，包含觸發條件和數據來源。

4.4 注意事項

4.4.1 參數類型支持矩陣

參數類型	支持情況	示例
基本類型	完全支持（int, double）	`void log(String message)`
集合類型	List/Set/Map	`List<User> findUsers(Query)`
嵌套POJO	支持遞歸結構	`Order create(OrderRequest)`
枚舉	自動識別取值范圍	`Status update(Status status)`

復雜參數處理：

@Description("用戶查詢條件")
class Query {
    @Description("篩選狀態：ACTIVE/INACTIVE")
    Status status;
    
    @Description("返回結果數量限制")
    @P(required = false) 
    Integer limit;
}

@Tool("查找用戶")
List<User> findUsers(Query query) { ... }

4.4.2 動態工具配置

根據上下文動態加載工具。舉個例子。

下面是一個使用 ToolProvider 實現動態工具加載的完整示例，該示例模擬酒店預訂場景，根據用戶消息內容動態選擇工具：

場景描述

當用戶消息包含 "預定" 關鍵詞時，動態加載預定查詢工具
當用戶消息包含 "天氣" 關鍵詞時，動態加載天氣查詢工具
其他情況不加載任何工具

工具定義

// 預定查詢工具（靜態定義）
publicclass BookingTools {

    @Tool("根據預定號查詢預定詳情，預定號格式為B-后接5位數字")
    public String getBookingDetails(
            @P("預定號，例如B-12345") String bookingNumber) {
        // 模擬數據庫查詢
        return"預定號: " + bookingNumber + ", 狀態: 已確認, 房型: 豪華套房";
    }
}
publicclass WeatherTools {

    @Tool("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調用")
    String getWeather(@P("需要查詢的城市名稱，如北京、London") String city, String temperatureUnit) {
        return"2025-03-16深圳天氣：多云轉晴，氣溫18-25°C，濕度65%";
    }

    public static ToolExecutor getWeatherExecutor() {
        return (request, memoryId) -> {
            return"2023-10-15  天氣: 晴, 溫度20-25°C ";
        };
    }
}

動態工具提供者

public class DynamicToolProvider implements ToolProvider {

    @Override
    public ToolProviderResult provideTools(ToolProviderRequest request) {
        String userMessage = request.userMessage().singleText().toLowerCase();

        Map<ToolSpecification, ToolExecutor> tools = new HashMap<>();

        // 預定相關工具
        if (userMessage.contains("預定")) {
            // 通過反射獲取@Tool注解的方法規格
            ToolSpecification bookingSpec = null;
            try {
                bookingSpec = ToolSpecifications.toolSpecificationFrom(
                        BookingTools.class.getDeclaredMethod("getBookingDetails", String.class)
                );
            } catch (NoSuchMethodException e) {
                thrownew RuntimeException(e);
            }

            // 方法引用執行器
            ToolExecutor bookingExecutor = (req, memId) -> {
                return"bookingExecutor";
            };

            tools.put(bookingSpec, bookingExecutor);
        }

        // 天氣相關工具
        if (userMessage.contains("天氣")) {
            tools.put(
                    ToolSpecifications.toolSpecificationsFrom(WeatherTools.class).get(0),
                    WeatherTools.getWeatherExecutor()
            );
        }

        return ToolProviderResult.builder()
                .addAll(tools)
                .build();
    }
}

AI 服務配置與使用

public class Demo01 {
    // 1. 定義AI服務接口
    interface TravelAssistant {
        Result<String> handleRequest(String userMessage);
    }

    // 2. 配置AI服務
    TravelAssistant assistant = AiServices.builder(TravelAssistant.class)
            .chatLanguageModel(createOpenAiModel()) // 創建模型實例
            .toolProvider(new DynamicToolProvider())
            .build();

    private ChatLanguageModel createOpenAiModel() {
        ChatLanguageModel chatModel = ZhipuAiChatModel.builder()
                .apiKey(API_KEY)
                .model("glm-4")
                .temperature(0.6)
                .maxToken(1024)
                .maxRetries(1)
                .callTimeout(Duration.ofSeconds(60))
                .connectTimeout(Duration.ofSeconds(60))
                .writeTimeout(Duration.ofSeconds(60))
                .readTimeout(Duration.ofSeconds(60))
                .build();
        return chatModel;
    }

    // 3. 測試不同場景
    public static void main(String[] args) {
        Demo01 demo01 = new Demo01();
        // 案例1: 預定查詢
        demo01.testRequest("我的預定號B-12345的狀態是什么？");

        // 案例2: 天氣查詢
        demo01.testRequest("今天巴黎的天氣如何？");

        // 案例3: 普通咨詢
        demo01.testRequest("酒店的早餐時間是幾點？");
    }

    private void testRequest(String message) {
        Result<String> result = assistant.handleRequest(message);
        System.out.println("用戶問題: " + message);
        System.out.println("最終回答: " + result.content());
        result.toolExecutions().forEach(exec ->
                System.out.println("調用工具: " + exec.request().name() + ", 參數: " + exec.request().arguments())
        );
        System.out.println("-------------------");
    }
}

執行結果輸出

用戶問題: 我的預定號B-12345的狀態是什么？
最終回答: 根據查詢結果，您的預定號B-12345的狀態是bookingExecutor。如果您需要更詳細的預定詳情，請提供更多信息，我將盡力幫助您。
調用工具: getBookingDetails, 參數: {"arg0":"B-12345"}
-------------------
用戶問題: 今天巴黎的天氣如何？
最終回答: 根據我獲取的信息，巴黎今天的天氣是晴天，溫度在20-25°C之間。
調用工具: getWeather, 參數: {"arg0":"Paris","arg1":"today"}
-------------------
用戶問題: 酒店的早餐時間是幾點？
最終回答: 酒店的早餐時間通常根據酒店的規定而有所不同，但一般而言，大多數酒店的早餐時間可能在以下范圍內：

- 早上6:00至上午10:00
- 早上7:00至上午11:00

有些酒店可能提供更早或更晚的早餐服務，以適應不同客人的需求。如果您正在計劃前往某家酒店并想了解具體的早餐時間，建議您直接聯系酒店的前臺或查看官方網站上的信息，以獲取最準確的時間安排。
-------------------

4.4.3 執行結果追蹤

獲取工具執行記錄：

Result<String> result = assistant.chat("查看訂單123狀態");
List<ToolExecution> executions = result.toolExecutions();

executions.forEach(exec -> {
    System.out.println("調用工具: " + exec.request().name());
    System.out.println("參數: " + exec.request().arguments());
    System.out.println("結果: " + exec.result());
});

4.4.4 異常處理

結構化錯誤反饋：

@Tool
String getStockPrice(String symbol) {
    try {
        return apiClient.fetchPrice(symbol);
    } catch (InvalidSymbolException e) {
        throw new ToolExecutionException("STOCK_SYMBOL_INVALID", e.getMessage());
    }
}

錯誤類型定義：

class ToolExecutionException extends RuntimeException {
    private String errorCode;
    
    public ToolExecutionException(String code, String message) {
        super(message);
        this.errorCode = code;
    }
    
    // Getters
}

4.4.5 性能優化

緩存機制：

@Tool("查詢城市信息")
@Cacheable(value = "cityCache", key = "#cityName")
public CityInfo getCityInfo(String cityName) { ... }

批量處理：

@Tool("批量查詢溫度")
public Map<String, Double> batchGetTemperatures(List<String> cities) { ... }

4.5 VS REST API

維度	傳統REST API	LangChain4j工具API
接口定義	Swagger/OpenAPI	Java注解自動生成
參數校驗	手動實現	自動類型轉換+JSON Schema
調用方式	顯式HTTP調用	LLM動態決策調用
錯誤處理	HTTP狀態碼	結構化異常消息反饋
協議耦合	強依賴HTTP	與協議解耦

通過高階API，開發者可以快速將現有業務能力轉化為大語言模型可用的工具，顯著提升開發效率。結合動態工具配置和結果追蹤功能，能夠構建出高度智能化的對話系統。最新實踐顯示，采用該模式可使工具集成開發時間縮短約 60%。

五、方案對比

維度	低階API	高階API
靈活性	高（完全自定義）	中（依賴框架自動生成邏輯）
開發效率	低（需手動處理所有細節）	高（注解驅動，減少重復代碼）
適用階段	探索性開發、復雜集成	成熟業務場景、標準化工具
學習成本	高（需掌握 JSON Schema 等細節）	低（通過注解簡化）

六、最佳實踐

優先使用高階API快速驗證功能
需深度定制時切換至低階API

責任編輯：武曉燕來源：江南一點雨

LLM 語言模型工具