全部文章

LangChain4j 工具检索:30 个工具也不选错

会编程的吕洞宾约 23 分钟

一个电商客服 Agent,工具从 6 个加到 32 个之后开始犯病:用户问“退款什么时候到账”,它去查发票;用户说“地址写错了”,它去取消订单。参数填得还有模有样,工具就是选错。工具越加越多,错误率不是慢慢涨,是成片地涨。这篇文章拆开讲两件事:为什么工具一多模型就开始乱点,以及怎么让它先查“工具目录”再动手,把一道 32 选 1 的题压成 6 选 1。

一、工具一多就选错,到底坏在哪

先给结论:工具选择错误的根因不是模型笨,是你把一道“32 选 1”的题丢给它,还指望它一遍做对。

线上能看到的症状就三类,很好认:

  • 调错工具。问退款到账时间,它调 queryOrderStatus,因为两者描述里都有“订单”。
  • 参数串门。调对了工具,把订单号填进了发票号字段。工具一多,参数 Schema 也一多,模型在几套相似字段之间串了。
  • 该调不调。工具表太长,模型懒得挑,直接凭上下文编一个答案,还编得挺像真的。

很多人第一反应是“把描述写长一点”。描述确实重要,但它解决的是“看不懂”,不是“分不清”。当六个工具的描述里都出现“订单”“查询”,在模型眼里就是六道长得一模一样的菜。

拆开看,是三个问题叠在一起:

  1. 候选空间变大。工具从 6 个到 32 个,每次请求模型都要在 32 套 JSON Schema 里挑一套。候选越多,相似项之间的打分差距越小,选错的概率不是线性上升。
  2. 描述是按代码结构写的,不是按用户语言写的。你的工具按 Service 方法切分,用户按“我的钱呢”提问,两套语言对不上。
  3. 上下文被工具定义吃掉。每个工具定义都要塞进 prompt,32 个工具轻松占掉几千 token。真正有用的对话被挤到后面,而模型对长上下文中间部分的注意力最差。

再算一笔组合账。8 个工具,两两之间要区分 28 对;32 个工具,是 496 对。工具是线性加的,需要模型分辨的“这两者有什么不同”是平方涨的。你每加一个工具,其实是在给前面所有工具增加干扰项。

所以别怪模型。业务催得紧,加个 @Tool 是最快的动作——半小时能上线,比改架构便宜太多。工具就是这样一个个攒起来的,攒到某天早上,客诉里开始出现“客服机器人答非所问”。

给一条经验线:工具 10 个以内,全量塞进去就行,别折腾;15 个以上,该考虑检索;30 个以上还全量塞,等于在线上埋雷。

二、模型“调用工具”这件事,底层怎么发生的

再给一个结论:模型从头到尾都没有执行权。它只输出一段 JSON,说“我想调哪个工具、参数是什么”,真正干活的是你的 JVM。

这个链路必须掰清楚,否则后面“检索工具”的意义讲不通。一次带工具的调用是这样的:

  1. 你把 @Tool 方法转成工具描述(名字、一句话说明、参数的 JSON Schema),和 messages 一起发给模型。
  2. 模型返回 tool_calls,里面是工具名和参数。
  3. 框架反射调用你的 Java 方法,把返回值当成一条 tool 消息塞回对话。
  4. 再请求一次模型,它基于工具结果继续回答。可能还要再调一次工具,循环到它不再要工具为止。

第 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,模型只能靠描述猜,猜错很正常。

工具检索换了个思路:先查目录,再点菜

关键转变:不要把整本菜单塞给模型,给它一个索引。

具体到一次请求,时序是这样:

  1. 你给 AiServices 配一个 ToolSearchStrategy。
  2. 框架不再把全部工具发出去,只发一个“检索工具”,外加标了常驻(ALWAYS_VISIBLE)的那几个。
  3. 模型把用户那句话改写成查询词,先调检索工具。
  4. 框架拿查询词跟工具描述做匹配:向量策略算 embedding 余弦相似度,关键词策略做词面打分。
  5. 命中的工具名和一句说明回到模型手里。
  6. 这批工具并入本次调用后续轮次的可用工具表,模型下一轮就能真的调它们。

为什么用向量而不是字符串匹配?用户说“钱什么时候退回来”,工具描述写的是“查询退款进度”。字面上一个共同词都没有,字面匹配直接挂;向量算的是意思,能对上。

向量的直觉很简单:每段文字变成一串数字(比如 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 打开。剩下的场景,把工具描述写成“什么时候用、什么时候别用”,八成问题就没了。

上线前按这个顺序过一遍:

  1. 把工具清单打印出来数一遍,超过 15 个才继续往下看。
  2. 抽查五个最容易混的工具,看描述里有没有“什么时候别用”。
  3. 拿二十条真实用户提问跑一遍,记下每次调用的工具名,人工对一遍。
  4. 对不上的再看是检索没命中,还是命中了他不调——这两种问题的修法完全不同。
  5. 最后才决定要不要上向量检索,别一上来就加组件。

工具检索不是银弹。它治的是“候选太多”,治不了“工具本身设计得烂”。一个 doEverything 的万能工具,检索救不回来。

参考资料

文 / 会编程的吕洞宾