LangChain4J中的工具鏈，你知道嗎？
作者：江南一點雨
大語言模型（LLM）除了生成文本，還可以通過工具調(diào)用觸發(fā)特定操作。該機制允許開發(fā)者為模型定義功能函數(shù)（如數(shù)學計算、API 調(diào)用等），當模型識別用戶需求需要外部工具輔助時，會在響應中表達調(diào)用意圖，開發(fā)者根據(jù)此意圖執(zhí)行工具并將結(jié)果返回給模型。
咱們繼續(xù)來聊 langchain4j。
最近松哥和大伙聊的基本上都是大模型應用開發(fā)的入門知識，松哥這邊后面會開始做集團的知識庫，到時候再和大家分享一些項目中的實踐經(jīng)驗。
一、Function Calling
大語言模型（LLM）除了生成文本，還可以通過工具調(diào)用觸發(fā)特定操作。該機制允許開發(fā)者為模型定義功能函數(shù)（如數(shù)學計算、API 調(diào)用等），當模型識別用戶需求需要外部工具輔助時，會在響應中表達調(diào)用意圖，開發(fā)者根據(jù)此意圖執(zhí)行工具并將結(jié)果返回給模型。
特別是在一些涉及到數(shù)學運算的場景，大家知道大模型并不擅長于此，如果能夠直接調(diào)用我們自己的 API，就會方便很多。或者是一些涉及到內(nèi)部 API 調(diào)用的場景，通過 Function Calling 就可以非常方便的實現(xiàn)。
1.1 三要素
- 名稱：明確的功能標識（如squareRoot）
- 描述：說明功能及適用場景（如"計算數(shù)的平方根"）
- 參數(shù)說明：每個參數(shù)的語義定義（如x表示待計算數(shù)值）
1.2 執(zhí)行流程
通過工具調(diào)用機制，大模型突破了自身在實時性、準確性和功能擴展性方面的限制。
開發(fā)者需要重點掌握工具定義規(guī)范、執(zhí)行流程編排和錯誤處理策略，結(jié)合 ReAct 等框架實現(xiàn)更智能的 AI 應用。最新技術(shù)如 LLMCompiler 的并行調(diào)用優(yōu)化，以及 OpenManus 的任務分解機制，正在推動該領(lǐng)域向更高階的自主智能演進。
二、兩種方案
LangChain4j 中對于工具的調(diào)用提供了兩種不同的抽象層次。
2.1 Low-Level
Low-Level 直接使用 ChatLanguageModel 和 ToolSpecification API 來實現(xiàn)。Low-Level 具有如下一些特點：
- 完全控制：開發(fā)者需手動定義工具規(guī)格（ToolSpecification），包括工具名稱、描述、參數(shù)結(jié)構(gòu)（JSON Schema）等。
- 靈活性強：適用于復雜場景，如第三方 API 集成或需要動態(tài)配置參數(shù)。
- 開發(fā)成本高：需編寫大量膠水代碼處理消息構(gòu)建、工具執(zhí)行及結(jié)果反饋。
適用場景：
- 需要精細控制工具邏輯（如參數(shù)校驗、錯誤處理）
- 集成非標準接口的外部服務
2.2 High-Level
High-Level 是通過 AI Services 和 @Tool 注解的 Java 方法High-Level 具有如下一些特點：
- 聲明式開發(fā)：使用 @Tool 注解自動生成工具規(guī)格，無需手動定義。
- 自動化流程：框架自動處理工具調(diào)用、結(jié)果注入和多輪對話管理。
- 代碼簡潔：隱藏底層復雜度，類似 Spring Data JPA 的 Repository 接口。
適用場景：
- 快速構(gòu)建標準化工具（如內(nèi)部業(yè)務 API）
- 需要與 Spring Boot 集成的項目
接下來我會逐一和大家介紹這兩種方案。
三、Low-Level
下面我們通過一個完整的天氣查詢案例，展示如何在 LangChain4j 中手動構(gòu)造ToolSpecification并實現(xiàn)工具調(diào)用流程。
3.1 定義工具規(guī)格
3.1.1 手動定義
// 步驟1：手動構(gòu)建天氣查詢工具規(guī)格
ToolSpecification weatherTool = ToolSpecification.builder()
.name("getWeather")
.description("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調(diào)用")
.parameters(JsonObjectSchema.builder()
.addStringProperty("city", "需要查詢的城市名稱，如北京、London")
.addEnumProperty("unit", List.of("CELSIUS", "FAHRENHEIT"), "溫度單位，默認使用CELSIUS")
.required("city") // 顯式聲明必填參數(shù)
.build())
.build();
List<ToolSpecification> toolSpecifications = List.of(weatherTool);關(guān)鍵設計原則：
- 命名規(guī)范：getWeather采用動詞+名詞結(jié)構(gòu)，明確功能定位
- 描述清晰：包含觸發(fā)條件（"當用戶詢問未來 24 小時天氣時調(diào)用"）
- 參數(shù)約束：
- 城市參數(shù)添加示例值增強可理解性
- 溫度單位使用枚舉類型約束取值范圍
- 通過 required() 顯式標記必填參數(shù)
3.1.2 注解定義
也可以利用注解工具自動定義這個規(guī)格，如下：
class WeatherTools {
@Tool("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調(diào)用")
String getWeather(@P("需要查詢的城市名稱，如北京、London") String city, String temperatureUnit) {
return "2025-03-16深圳天氣：多云轉(zhuǎn)晴，氣溫18-25°C，濕度65%";
}
}
List<ToolSpecification> toolSpecifications = ToolSpecifications.toolSpecificationsFrom(WeatherTools.class);3.2 完整交互
步驟1：初始請求構(gòu)建
// 步驟1：構(gòu)造初始聊天請求
ChatRequest request = ChatRequest.builder()
.messages(UserMessage.from("2025年3月16日深圳的天氣如何？"))
.toolSpecifications(toolSpecifications)
.build();
// 發(fā)送請求并獲取響應
ChatResponse response = model.chat(request);
AiMessage aiMessage = response.aiMessage();此時若模型判斷需要調(diào)用工具，aiMessage.toolExecutionRequests()將包含：
{
"name": "getWeather",
"arguments": {"city": "深圳", "unit": "CELSIUS"}
}步驟2：工具執(zhí)行與結(jié)果反饋
// 步驟2：執(zhí)行工具邏輯（模擬實現(xiàn)）
if (aiMessage.hasToolExecutionRequests()) {
ToolExecutionRequest request = aiMessage.toolExecutionRequests().get(0);
Map<String, Object> args = parseJson(request.arguments());
// 模擬工具執(zhí)行（實際應調(diào)用外部API）
String result = "2025-03-16深圳天氣：多云轉(zhuǎn)晴，氣溫18-25°C，濕度65%";
// 構(gòu)造結(jié)果消息
ToolExecutionResultMessage resultMsg = ToolExecutionResultMessage.from(request, result);
// 構(gòu)建二次請求
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日深圳將有多云轉(zhuǎn)晴天氣，溫度范圍18-25攝氏度"
}3.3 技術(shù)要點
3.3.1 參數(shù)結(jié)構(gòu)
JsonObjectSchema.builder()
.addStringProperty("city", "城市中文或英文名稱，如'New York'需轉(zhuǎn)換為'紐約'")
.addEnumProperty("unit", List.of("CELSIUS", "FAHRENHEIT"),
"單位轉(zhuǎn)換需求，如用戶特別說明華氏度時使用")
.build()- 類型校驗：通過addStringProperty/addEnumProperty確保參數(shù)合法性
- 語義增強：在描述中補充數(shù)據(jù)轉(zhuǎn)換規(guī)則（如英文城市名轉(zhuǎn)中文）
3.3.2 異常處理機制
try {
// 工具執(zhí)行邏輯
} catch (InvalidCityException e) {
return ToolExecutionResultMessage.error(request, "城市名稱無效: " + e.getMessage());
} catch (ApiTimeoutException e) {
return ToolExecutionResultMessage.error(request, "天氣接口響應超時");
}- 錯誤碼規(guī)范：定義業(yè)務異常類型輔助模型理解
- 錯誤信息結(jié)構(gòu)化：通過error()方法返回標準錯誤格式
3.3.3 多工具協(xié)作模式
// 添加多個工具規(guī)格
ToolSpecification airQualityTool = ToolSpecification.builder()
.name("getAirQuality")
.description("獲取城市空氣質(zhì)量指數(shù)，當用戶詢問 PM2.5 或空氣質(zhì)量時調(diào)用")
.parameters(/* 參數(shù)定義 */)
.build();
List<ToolSpecification> tools = List.of(weatherTool, airQualityTool);- 工具組合策略：天氣與空氣質(zhì)量工具形成互補
- 調(diào)用優(yōu)先級：通過描述中的觸發(fā)條件引導模型選擇
四、High-Level
4.1 核心機制
@Tool 注解驅(qū)動開發(fā)，主要是通過 Java 注解自動生成工具規(guī)格，無需手動定義 JSON Schema。
@Tool("計算兩個數(shù)之和")
public double add(@P("第一個數(shù)") int a,
@P(value = "第二個數(shù)", required = false) Integer b) {
return a + (b != null ? b : 0);
}自動生成效果：
{
"name": "add",
"description": "計算兩個數(shù)之和",
"parameters": {
"type": "object",
"properties": {
"a": {"type": "integer", "description": "第一個數(shù)"},
"b": {"type": "integer", "description": "第二個數(shù)"}
},
"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("計算兩個數(shù)的和")
int add(int a, int b) {
System.out.println("計算兩個數(shù)的和 a=" + a + ", b=" + b);
return a + b;
}
@Tool("計算一個數(shù)的平方根")
double sqrt(int x) {
System.out.println("計算一個數(shù)的平方根 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);
}
}來看下執(zhí)行結(jié)果：
圖片
上面代碼比較簡單，就不啰嗦解釋了。
注意，在 @Tool 注解中，包含觸發(fā)條件和數(shù)據(jù)來源。
4.4 注意事項
4.4.1 參數(shù)類型支持矩陣
參數(shù)類型 | 支持情況 | 示例 |
基本類型 | 完全支持（int, double） |
|
集合類型 | List/Set/Map |
|
嵌套POJO | 支持遞歸結(jié)構(gòu) |
|
枚舉 | 自動識別取值范圍 |
|
復雜參數(shù)處理：
@Description("用戶查詢條件")
class Query {
@Description("篩選狀態(tài)：ACTIVE/INACTIVE")
Status status;
@Description("返回結(jié)果數(shù)量限制")
@P(required = false)
Integer limit;
}
@Tool("查找用戶")
List<User> findUsers(Query query) { ... }4.4.2 動態(tài)工具配置
根據(jù)上下文動態(tài)加載工具。舉個例子。
下面是一個使用 ToolProvider 實現(xiàn)動態(tài)工具加載的完整示例，該示例模擬酒店預訂場景，根據(jù)用戶消息內(nèi)容動態(tài)選擇工具：
場景描述
- 當用戶消息包含 "預定" 關(guān)鍵詞時，動態(tài)加載 預定查詢工具
- 當用戶消息包含 "天氣" 關(guān)鍵詞時，動態(tài)加載 天氣查詢工具
- 其他情況不加載任何工具
工具定義
// 預定查詢工具（靜態(tài)定義）
publicclass BookingTools {
@Tool("根據(jù)預定號查詢預定詳情，預定號格式為B-后接5位數(shù)字")
public String getBookingDetails(
@P("預定號，例如B-12345") String bookingNumber) {
// 模擬數(shù)據(jù)庫查詢
return"預定號: " + bookingNumber + ", 狀態(tài): 已確認, 房型: 豪華套房";
}
}
publicclass WeatherTools {
@Tool("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調(diào)用")
String getWeather(@P("需要查詢的城市名稱，如北京、London") String city, String temperatureUnit) {
return"2025-03-16深圳天氣：多云轉(zhuǎn)晴，氣溫18-25°C，濕度65%";
}
public static ToolExecutor getWeatherExecutor() {
return (request, memoryId) -> {
return"2023-10-15 天氣: 晴, 溫度20-25°C ";
};
}
}動態(tài)工具提供者
public class DynamicToolProvider implements ToolProvider {
@Override
public ToolProviderResult provideTools(ToolProviderRequest request) {
String userMessage = request.userMessage().singleText().toLowerCase();
Map<ToolSpecification, ToolExecutor> tools = new HashMap<>();
// 預定相關(guān)工具
if (userMessage.contains("預定")) {
// 通過反射獲取@Tool注解的方法規(guī)格
ToolSpecification bookingSpec = null;
try {
bookingSpec = ToolSpecifications.toolSpecificationFrom(
BookingTools.class.getDeclaredMethod("getBookingDetails", String.class)
);
} catch (NoSuchMethodException e) {
thrownew RuntimeException(e);
}
// 方法引用執(zhí)行器
ToolExecutor bookingExecutor = (req, memId) -> {
return"bookingExecutor";
};
tools.put(bookingSpec, bookingExecutor);
}
// 天氣相關(guān)工具
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()) // 創(chuàng)建模型實例
.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的狀態(tài)是什么？");
// 案例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("調(diào)用工具: " + exec.request().name() + ", 參數(shù): " + exec.request().arguments())
);
System.out.println("-------------------");
}
}執(zhí)行結(jié)果輸出
用戶問題: 我的預定號B-12345的狀態(tài)是什么？
最終回答: 根據(jù)查詢結(jié)果，您的預定號B-12345的狀態(tài)是bookingExecutor。如果您需要更詳細的預定詳情，請?zhí)峁└嘈畔?，我將盡力幫助您。
調(diào)用工具: getBookingDetails, 參數(shù): {"arg0":"B-12345"}
-------------------
用戶問題: 今天巴黎的天氣如何？
最終回答: 根據(jù)我獲取的信息，巴黎今天的天氣是晴天，溫度在20-25°C之間。
調(diào)用工具: getWeather, 參數(shù): {"arg0":"Paris","arg1":"today"}
-------------------
用戶問題: 酒店的早餐時間是幾點？
最終回答: 酒店的早餐時間通常根據(jù)酒店的規(guī)定而有所不同，但一般而言，大多數(shù)酒店的早餐時間可能在以下范圍內(nèi)：
- 早上6:00至上午10:00
- 早上7:00至上午11:00
有些酒店可能提供更早或更晚的早餐服務，以適應不同客人的需求。如果您正在計劃前往某家酒店并想了解具體的早餐時間，建議您直接聯(lián)系酒店的前臺或查看官方網(wǎng)站上的信息，以獲取最準確的時間安排。
-------------------4.4.3 執(zhí)行結(jié)果追蹤
獲取工具執(zhí)行記錄：
Result<String> result = assistant.chat("查看訂單123狀態(tài)");
List<ToolExecution> executions = result.toolExecutions();
executions.forEach(exec -> {
System.out.println("調(diào)用工具: " + exec.request().name());
System.out.println("參數(shù): " + exec.request().arguments());
System.out.println("結(jié)果: " + exec.result());
});4.4.4 異常處理
結(jié)構(gòu)化錯誤反饋：
@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 性能優(yōu)化
緩存機制：
@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
維度 | 傳統(tǒng)REST API | LangChain4j工具API |
接口定義 | Swagger/OpenAPI | Java注解自動生成 |
參數(shù)校驗 | 手動實現(xiàn) | 自動類型轉(zhuǎn)換+JSON Schema |
調(diào)用方式 | 顯式HTTP調(diào)用 | LLM動態(tài)決策調(diào)用 |
錯誤處理 | HTTP狀態(tài)碼 | 結(jié)構(gòu)化異常消息反饋 |
協(xié)議耦合 | 強依賴HTTP | 與協(xié)議解耦 |
通過高階API，開發(fā)者可以快速將現(xiàn)有業(yè)務能力轉(zhuǎn)化為大語言模型可用的工具，顯著提升開發(fā)效率。結(jié)合動態(tài)工具配置和結(jié)果追蹤功能，能夠構(gòu)建出高度智能化的對話系統(tǒng)。最新實踐顯示，采用該模式可使工具集成開發(fā)時間縮短約 60%。
五、方案對比
維度 | 低階API | 高階API |
靈活性 | 高（完全自定義） | 中（依賴框架自動生成邏輯） |
開發(fā)效率 | 低（需手動處理所有細節(jié)） | 高（注解驅(qū)動，減少重復代碼） |
適用階段 | 探索性開發(fā)、復雜集成 | 成熟業(yè)務場景、標準化工具 |
學習成本 | 高（需掌握 JSON Schema 等細節(jié)） | 低（通過注解簡化） |
六、最佳實踐
- 優(yōu)先使用高階API快速驗證功能
- 需深度定制時切換至低階API
責任編輯：武曉燕
來源：
江南一點雨
