LangChain4j 工具检索:30 个工具也不选错
一个电商客服 Agent,工具从 6 个加到 32 个之后开始犯病:用户问“退款什么时候到账”,它去查发票;用户说“地址写错了”,它去取消订单。参数填得还有模有样,工具就是选错。工具越加越多,错误率不是慢慢涨,是成片地涨。这篇文章拆开讲两件事:为什么工具一多模型就开始乱点,以及怎么让它先查“工具目录”再动手,把一道 32 选 1 的题压成 6 选 1。
一、工具一多就选错,到底坏在哪
先给结论:工具选择错误的根因不是模型笨,是你把一道“32 选 1”的题丢给它,还指望它一遍做对。
线上能看到的症状就三类,很好认:
- 调错工具。问退款到账时间,它调
queryOrderStatus,因为两者描述里都有“订单”。 - 参数串门。调对了工具,把订单号填进了发票号字段。工具一多,参数 Schema 也一多,模型在几套相似字段之间串了。
- 该调不调。工具表太长,模型懒得挑,直接凭上下文编一个答案,还编得挺像真的。
很多人第一反应是“把描述写长一点”。描述确实重要,但它解决的是“看不懂”,不是“分不清”。当六个工具的描述里都出现“订单”“查询”,在模型眼里就是六道长得一模一样的菜。
拆开看,是三个问题叠在一起:
- 候选空间变大。工具从 6 个到 32 个,每次请求模型都要在 32 套 JSON Schema 里挑一套。候选越多,相似项之间的打分差距越小,选错的概率不是线性上升。
- 描述是按代码结构写的,不是按用户语言写的。你的工具按 Service 方法切分,用户按“我的钱呢”提问,两套语言对不上。
- 上下文被工具定义吃掉。每个工具定义都要塞进 prompt,32 个工具轻松占掉几千 token。真正有用的对话被挤到后面,而模型对长上下文中间部分的注意力最差。
再算一笔组合账。8 个工具,两两之间要区分 28 对;32 个工具,是 496 对。工具是线性加的,需要模型分辨的“这两者有什么不同”是平方涨的。你每加一个工具,其实是在给前面所有工具增加干扰项。
所以别怪模型。业务催得紧,加个 @Tool 是最快的动作——半小时能上线,比改架构便宜太多。工具就是这样一个个攒起来的,攒到某天早上,客诉里开始出现“客服机器人答非所问”。
给一条经验线:工具 10 个以内,全量塞进去就行,别折腾;15 个以上,该考虑检索;30 个以上还全量塞,等于在线上埋雷。
二、模型“调用工具”这件事,底层怎么发生的
再给一个结论:模型从头到尾都没有执行权。它只输出一段 JSON,说“我想调哪个工具、参数是什么”,真正干活的是你的 JVM。
这个链路必须掰清楚,否则后面“检索工具”的意义讲不通。一次带工具的调用是这样的:
- 你把
@Tool方法转成工具描述(名字、一句话说明、参数的 JSON Schema),和 messages 一起发给模型。 - 模型返回
tool_calls,里面是工具名和参数。 - 框架反射调用你的 Java 方法,把返回值当成一条
tool消息塞回对话。 - 再请求一次模型,它基于工具结果继续回答。可能还要再调一次工具,循环到它不再要工具为止。
第 1 步里那份“工具描述”,实际是这么一小段 JSON,模型看到的就是它:
{
"name": "queryRefundStatus",
"description": "查询退款进度,返回退款单号、当前环节、预计到账时间",
"parameters": {
"type": "object",
"properties": { "orderNo": { "type": "string" } },
"required": ["orderNo"]
}
}
一个工具就是一段这样的 schema,三十个工具就是三十段。模型不是在“理解你的系统”,它是在三十段长得差不多的 schema 里做一个分类。你给它的区分线索,只有名字和 description 这两行字。
看明白第 1 步就知道问题在哪了:工具的“可选择性”完全由你塞进去的那份清单决定。塞 32 个,它就是 32 选 1。
菜单越长,点菜越容易错
餐厅点菜是最好的类比。服务员只报三个菜,你三秒决定;给你一本 200 页的菜单,你会开始问“你们招牌是什么”。
模型也一样,翻车集中在两个地方:
- 描述相似度太高。
queryOrderStatus和queryRefundStatus都是“查询订单相关状态”,字面和语义都近。 - 名字不可读。很多团队的工具有内部缩写,
qryInv2024、doRefundV2,模型只能靠描述猜,猜错很正常。
工具检索换了个思路:先查目录,再点菜
关键转变:不要把整本菜单塞给模型,给它一个索引。
具体到一次请求,时序是这样:
- 你给
AiServices配一个ToolSearchStrategy。 - 框架不再把全部工具发出去,只发一个“检索工具”,外加标了常驻(
ALWAYS_VISIBLE)的那几个。 - 模型把用户那句话改写成查询词,先调检索工具。
- 框架拿查询词跟工具描述做匹配:向量策略算 embedding 余弦相似度,关键词策略做词面打分。
- 命中的工具名和一句说明回到模型手里。
- 这批工具并入本次调用后续轮次的可用工具表,模型下一轮就能真的调它们。
为什么用向量而不是字符串匹配?用户说“钱什么时候退回来”,工具描述写的是“查询退款进度”。字面上一个共同词都没有,字面匹配直接挂;向量算的是意思,能对上。
向量的直觉很简单:每段文字变成一串数字(比如 1536 个小数),意思越近的两段话,这两串数字在空间里的方向越接近。判断方向接近用余弦相似度,取值 -1 到 1,越接近 1 越像。“退款到账”和“退款进度”大概 0.85,“退款到账”和“开具发票”可能只有 0.4。检索就是按这个分数排个序,取前 N 个。
代价也要说清楚:检索让一次请求多了一轮模型往返(模型先调检索工具,再调真工具),端到端延迟通常多几百毫秒。工具少的时候这笔买卖不划算,工具多的时候是唯一解。
那为什么不干脆让模型自己先想一遍该用哪个工具(DecisionModelToolSearchStrategy 就是干这个的)?因为多一次大模型往返,钱和时间都翻倍。只有当工具描述全是业务黑话、embedding 也匹配不准时,这个策略才值得上。
这里必须提醒一句:这套工具检索 API 目前标着 @Experimental。能用,也确实解决了问题,但要锁版本,升级依赖时优先回归工具选择这块。
三、实战:从复现到修好
先看依赖。这是一个普通 Maven 工程,不需要 Spring Boot:
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>tool-search-demo</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j</artifactId>
<version>1.23.0</version>
</dependency>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai</artifactId>
<version>1.23.0</version>
</dependency>
</dependencies>
</project>
langchain4j-open-ai 走的是 OpenAI 兼容协议,换成 DeepSeek、通义、本地 vLLM 都只要改 baseUrl 和 modelName。
示例一:先把问题复现出来
十一个工具,覆盖订单、退款、发票、物流、优惠券。注意看它们的描述,这就是线上真实的样子——按代码结构切出来的。
package com.example.toolsearch;
import dev.langchain4j.agent.tool.Tool;
public class ShopTools {
@Tool("查询订单状态,返回已下单、已发货、已签收等状态")
public String queryOrderStatus(String orderNo) {
System.out.println("[tool] queryOrderStatus(orderNo=" + orderNo + ")");
return "订单 " + orderNo + " 状态:已签收";
}
@Tool("查询订单里的商品明细,包括型号、数量、单价")
public String queryOrderItems(String orderNo) {
System.out.println("[tool] queryOrderItems(orderNo=" + orderNo + ")");
return "订单 " + orderNo + " 商品:无线耳机 x1,单价 499 元";
}
@Tool("查询物流轨迹,返回承运商和最新节点")
public String queryLogistics(String orderNo) {
System.out.println("[tool] queryLogistics(orderNo=" + orderNo + ")");
return "订单 " + orderNo + " 承运商:顺丰,最新节点:已签收";
}
@Tool("查询退款进度,返回退款单号、当前环节、预计到账时间")
public String queryRefundStatus(String orderNo) {
System.out.println("[tool] queryRefundStatus(orderNo=" + orderNo + ")");
return "订单 " + orderNo + " 退款已审核通过,预计 1 个工作日内到账";
}
@Tool("创建退款申请,参数为订单号和退款原因")
public String createRefund(String orderNo, String reason) {
System.out.println("[tool] createRefund(orderNo=" + orderNo + ", reason=" + reason + ")");
return "退款申请已创建,退款单号 R" + orderNo;
}
@Tool("取消未发货订单")
public String cancelOrder(String orderNo) {
System.out.println("[tool] cancelOrder(orderNo=" + orderNo + ")");
return "订单 " + orderNo + " 已取消";
}
@Tool("修改收货地址,仅未发货订单可用")
public String updateAddress(String orderNo, String address) {
System.out.println("[tool] updateAddress(orderNo=" + orderNo + ", address=" + address + ")");
return "订单 " + orderNo + " 收货地址已更新为:" + address;
}
@Tool("开具电子发票,返回下载链接")
public String issueInvoice(String orderNo, String title) {
System.out.println("[tool] issueInvoice(orderNo=" + orderNo + ", title=" + title + ")");
return "发票已开具,下载链接:https://example.com/invoice/" + orderNo;
}
@Tool("查询发票开具状态")
public String queryInvoice(String orderNo) {
System.out.println("[tool] queryInvoice(orderNo=" + orderNo + ")");
return "订单 " + orderNo + " 发票状态:已开具";
}
@Tool("查询商品库存,参数为商品编码")
public String queryStock(String sku) {
System.out.println("[tool] queryStock(sku=" + sku + ")");
return "商品 " + sku + " 库存:128 件";
}
@Tool("查询优惠券使用规则")
public String queryCoupon(String couponCode) {
System.out.println("[tool] queryCoupon(couponCode=" + couponCode + ")");
return "优惠券 " + couponCode + " 满 300 减 50,有效期 30 天";
}
}
助手接口就一个方法:
package com.example.toolsearch;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
public interface ShopAssistant {
@SystemMessage("你是电商客服助手。需要查数据或改状态时必须调用工具,不要凭记忆回答。")
String chat(@UserMessage String message);
}
十一个工具全量塞进去,跑一句真实的用户提问:
package com.example.toolsearch;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
public class Demo1 {
public static void main(String[] args) {
String apiKey = System.getenv("OPENAI_API_KEY");
ChatModel model = OpenAiChatModel.builder()
.apiKey(apiKey)
.baseUrl("https://api.openai.com/v1")
.modelName("gpt-4o-mini")
.temperature(0.0)
.build();
ShopAssistant assistant = AiServices.builder(ShopAssistant.class)
.chatModel(model)
.tools(new ShopTools())
.build();
String answer = assistant.chat("我上周买的耳机,退款什么时候能到账?");
System.out.println("回答:" + answer);
}
}
跑完去看 [tool] 开头的日志。如果出现的是 queryOrderStatus 或者 queryInvoice,而不是 queryRefundStatus,问题就复现了——模型不是不会推理,是它在十一条相似描述里挑花了眼。
示例二:加一层向量工具检索
改三处:多一个 EmbeddingModel,多一个检索策略,AiServices 里挂上去。工具类一行都不用动。
package com.example.toolsearch;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.openai.OpenAiEmbeddingModel;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.service.tool.search.vector.VectorToolSearchStrategy;
public class Demo2 {
public static void main(String[] args) {
String apiKey = System.getenv("OPENAI_API_KEY");
ChatModel chatModel = OpenAiChatModel.builder()
.apiKey(apiKey)
.baseUrl("https://api.openai.com/v1")
.modelName("gpt-4o-mini")
.temperature(0.0)
.build();
EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder()
.apiKey(apiKey)
.baseUrl("https://api.openai.com/v1")
.modelName("text-embedding-3-small")
.build();
ShopAssistant assistant = AiServices.builder(ShopAssistant.class)
.chatModel(chatModel)
.tools(new ShopTools())
.toolSearchStrategy(VectorToolSearchStrategy.builder()
.embeddingModel(embeddingModel)
.maxResults(6)
.cacheEmbeddings(true)
.build())
.build();
String answer = assistant.chat("我上周买的耳机,退款什么时候能到账?");
System.out.println("回答:" + answer);
}
}
关键就三个参数:
embeddingModel:算工具描述和用户查询的向量。工具描述的向量只算一次。maxResults(6):一次最多放出 6 个候选工具。这是“32 选 1”变成“6 选 1”的地方,也是这篇文章的核心。cacheEmbeddings(true):工具描述基本不变,向量缓存起来,每次请求只需要算用户那句话,一次 embedding 调用几十毫秒。
同一句提问再跑一遍,日志里应该只剩 queryRefundStatus。模型看到的不再是整本菜单,而是“退款”这一页。
示例三:不想付 embedding 的钱,用关键词版
如果工具描述写得足够有区分度,或者你的场景对延迟极其敏感,可以用关键词检索策略。它在本地打分,零额外网络调用。
顺便把“必须随时可见”的工具标出来——转人工这种,不该等模型搜。
package com.example.toolsearch;
import dev.langchain4j.agent.tool.SearchBehavior;
import dev.langchain4j.agent.tool.Tool;
public class TicketTools {
@Tool(value = "转人工客服,创建工单。用户明确要求转人工、或问题涉及投诉和纠纷时使用",
searchBehavior = SearchBehavior.ALWAYS_VISIBLE)
public String transferToHuman(String reason) {
System.out.println("[tool] transferToHuman(reason=" + reason + ")");
return "已创建人工工单,客服将在 5 分钟内接入";
}
@Tool("查询当前客服是否在线")
public String agentOnline() {
System.out.println("[tool] agentOnline()");
return "当前有 12 位客服在线";
}
}
package com.example.toolsearch;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.service.tool.search.simple.SimpleToolSearchStrategy;
public class Demo3 {
public static void main(String[] args) {
String apiKey = System.getenv("OPENAI_API_KEY");
ChatModel model = OpenAiChatModel.builder()
.apiKey(apiKey)
.baseUrl("https://api.openai.com/v1")
.modelName("gpt-4o-mini")
.temperature(0.0)
.build();
ShopAssistant assistant = AiServices.builder(ShopAssistant.class)
.chatModel(model)
.tools(new ShopTools(), new TicketTools())
.toolSearchStrategy(SimpleToolSearchStrategy.builder()
.maxResults(6)
.build())
.maxSequentialToolsInvocations(4)
.build();
String answer = assistant.chat("退款还没到,直接给我转人工");
System.out.println("回答:" + answer);
}
}
maxSequentialToolsInvocations(4) 是个保险丝:模型最多连续调 4 轮工具,超过就强制收尾。工具检索 + 长流程很容易把模型带进“再查一次”的循环,这个参数比事后加提示词管用。
四、踩过的坑,以及绕过去的方法
坑一:工具描述写成函数注释。 最常见的死法。描述里写“查询退款信息”,模型匹配不到“钱什么时候退回来”。
写法要按“什么时候用 + 什么时候别用 + 参数是什么”来:
@Tool("查询退款进度。用户问退款到账时间、退款失败原因、退款卡在哪一步时用;" +
"只是查订单物流时不要用。参数 orderNo 是订单号(不是退款单号)")
public String queryRefundStatus(String orderNo) {
return "退款已审核通过,预计 1 个工作日内到账";
}
那句“只是查订单物流时不要用”比前面二十个字都值钱,它在帮模型做排除。
坑二:工具名用内部缩写。 qryInv、doRefundV2 这种,模型只能靠描述硬猜。工具名就该是动词加名词,queryInvoiceStatus、createRefundRequest。名字本身是强信号,别浪费。
坑三:ALWAYS_VISIBLE 贴太多。 贴了五六个之后你会发现又回到了全量塞,检索白做。常驻只留两类:跨场景的兜底动作(转人工)、身份相关的必须动作(查当前用户)。三个以内。
坑四:检索结果为空。 有的实现会把空结果当“没找到”直接告诉模型,模型就开始编。兜底逻辑要自己写:空结果时返回最相近的三个工具,并附一句“下面是可能相关的工具,请判断是否适用”。
坑五:拿检索当权限过滤。 这是安全问题,不是效果问题。检索只做相关性排序,它不知道这个用户能不能退款。租户隔离和权限裁剪必须在工具可选集上做——先按身份把不可用的工具剔掉,再做检索。顺序反了,就是把别人的工具名报给了模型。
坑六:没有观测。 至少要记三样东西:每次检索的查询词、命中的工具名、最终真正调用的工具名。三者对不上,就是检索准但模型没听话,该调描述;检索本身没命中,该调描述或换策略。不记日志,线上只能靠猜。
五、全量、关键词、向量、小模型决策,怎么选
| 方案 | 每次请求的工具 token | 额外延迟 | 适合的工具规模 | 主要风险 |
|---|---|---|---|---|
| 全量塞入 | 最高,随工具数线性涨 | 无 | 10 个以内 | 相似工具互相干扰 |
| 关键词检索 | 低 | 几乎为零(本地打分) | 10~30 个,描述区分度高 | 同义词、口语化提问匹配不上 |
| 向量检索 | 低 | 一次 embedding,几十毫秒 | 20 个以上,描述是业务语言 | 需要额外的 embedding 服务 |
| 小模型决策 | 低 | 多一次 LLM 往返,几百毫秒起 | 工具极多且描述高度专业 | 成本和延迟翻倍 |
成本账可以粗算一下。一个带中文描述和参数 Schema 的工具定义,大约 80~200 token,中文被切得更碎,取中间值 120。12 个工具就是 1400 token 左右,32 个就是 3800 往上,这还是每轮都要发。检索之后每次只放 6 个,工具部分的 token 能压掉八成以上。
但有个反方向的账要算清楚:工具定义是固定前缀,很多推理服务对固定前缀有缓存折扣,全量塞反而便宜;检索让每轮的工具集都在变,前缀缓存命中不了。所以别只看 token 数,看账单。
我的建议很直接:10 个以内别上检索,30 个以上必须上,中间那段先改工具描述,改完还错再上关键词检索。 向量检索留给描述天然是业务语言、同义词多的场景,比如客服和运营后台。
六、总结
工具选择错误,本质是候选空间问题,不是模型能力问题。你把 32 个几乎同名的工具摆在它面前,它选错是必然的。
工具检索把这道题拆成两步:先用一句话找到相关的那几个工具,再在这几个里精确选择。检索这一步可以是向量、可以是关键词、也可以是小模型,代价不同,思路一样。
落地顺序记住三句话:先改工具描述,再考虑检索,最后才考虑换模型。改描述不要钱,换模型要钱,顺序别搞反。
真要我选,客服、运营这类工具多、问法口语化的场景,直接上向量检索,maxResults 给 5~8,cacheEmbeddings 打开。剩下的场景,把工具描述写成“什么时候用、什么时候别用”,八成问题就没了。
上线前按这个顺序过一遍:
- 把工具清单打印出来数一遍,超过 15 个才继续往下看。
- 抽查五个最容易混的工具,看描述里有没有“什么时候别用”。
- 拿二十条真实用户提问跑一遍,记下每次调用的工具名,人工对一遍。
- 对不上的再看是检索没命中,还是命中了他不调——这两种问题的修法完全不同。
- 最后才决定要不要上向量检索,别一上来就加组件。
工具检索不是银弹。它治的是“候选太多”,治不了“工具本身设计得烂”。一个 doEverything 的万能工具,检索救不回来。
参考资料
文 / 会编程的吕洞宾