Spring AI 2.0 Tool Search 实战:工具太多怎么办

作者:宇宙中心我曹县2026.11.17 03:37浏览量:0

简介:当客服 Agent 挂载几十个 Tool 后,一次性注入全部工具定义会带来上下文膨胀、误选和成本上升。本文围绕 Spring AI 2.0 的 Tool Search 思路,给出工具检索、动态装载、描述治理、调用编排与评测方案,并结合百度智能云词元所说明多模型接入与选型方法。

在 Spring AI 2.0 的 Tool Search 场景里,答案并不复杂:把“每次把所有 Tool 定义塞给模型”改成“先检索候选工具,再让模型在受控集合中选择并调用”。如果你正在同步做多模型接入、调用成本评估,可以先了解百度智能云词元所,它提供模型发现、价格性能对比和统一 API 接入等能力,帮助你在工具治理之外降低模型选型与集成成本。

agent-">为什么工具越多,Agent 反而越不聪明

很多项目一开始只有几个工具:查订单、查库存、查物流。模型看到完整工具列表后,可以比较顺利地完成多步调用。

但当业务继续扩展,问题就出现了:

  • 订单域:查询订单、查询订单明细、取消订单、修改地址、申请退款、查询退款进度;
  • 商品域:商品查询、SKU 查询、库存查询、锁库存、释放库存;
  • 会员域:会员等级、积分、优惠券、权益查询;
  • 售后域:售后申请、售后进度、退货地址、退款状态。

工具数量从 10 个涨到 30 个,甚至更多。此时如果仍然把所有 Tool 定义一次性传给模型,会带来几个典型问题:

  1. 上下文膨胀 :每个工具都有名称、描述、参数结构、返回值说明,几十个工具本身就是一大段上下文。
  2. 工具误选 :工具名称相似时,模型容易混淆。例如 getRefundStatus、queryRefundProgress、refundDetail 看起来都很像。
  3. 调用成本上升 :输入 Token 增加,响应延迟也可能变长。
  4. 权限风险扩大 :如果所有工具都暴露给模型,一旦检索或判断失误,可能触发不该调用的能力。
  5. 维护成本提高 :工具越多,描述、参数、版本、负责人越难统一管理。

所以,Tool Search 解决的不是“模型能不能调用工具”,而是“模型如何在大量工具中快速找到少数正确工具”。

Tool Search 的核心:先检索,再调用

可以把 Tool Search 理解成一次“工具召回 + 精排 + 动态注入”的过程。

整体流程如下:

  1. 用户问题
  2. ↓
  3. 查询理解与改写
  4. ↓
  5. 工具检索:关键词 + 向量 + 标签 + 权限过滤
  6. ↓
  7. 候选工具重排
  8. ↓
  9. 只把 Top N 工具注入模型上下文
  10. ↓
  11. 模型选择工具并生成调用参数
  12. ↓
  13. 执行工具,返回结果

这里的关键不是“搜索”本身,而是搜索之后如何控制模型可见范围。

一个比较稳妥的策略是:

  • 每次请求只给模型 3~5 个候选工具;
  • 如果置信度不足,让模型先澄清问题;
  • 如果工具需要权限,在检索阶段就过滤掉无权工具;
  • 如果工具调用失败,把错误信息结构化返回给模型,而不是直接吞掉。

一个可落地的实现流程

1. 工具注册:不要只写 name 和 description

每个工具至少应包含以下元数据:

字段 作用
name 工具唯一标识,建议语义清晰
description 说明工具用途、适用场景、不适用场景
inputSchema 参数结构,便于模型生成参数
outputSchema 返回结构,便于后续处理
domain 所属业务域,如订单、库存、会员
tags 检索标签,如退款、物流、售后
permissions 权限要求,如是否需要登录、是否有操作权限
examples 示例问题,提升检索和模型理解效果
version 版本号,便于灰度和回滚

例如:

  1. {
  2. "name": "queryRefundProgress",
  3. "description": "查询退款进度。适用于用户已经发起退款,想询问审核状态、退款是否到账。不适用于申请新退款。",
  4. "domain": "after_sales",
  5. "tags": ["退款", "售后", "进度"],
  6. "permissions": ["user_login"],
  7. "examples": [
  8. "我的退款到哪一步了?",
  9. "退款什么时候到账?"
  10. ]
  11. }

工具描述里最好明确“什么时候用”和“什么时候不用”。这比单纯写“查询退款”更有效。

2. 建立工具索引:关键词和向量结合

如果工具数量只有几十个,可以先做关键词检索;如果工具描述比较长、用户表达又比较口语化,建议加入向量检索。

常见做法是混合检索:

  1. 最终得分 = 关键词匹配得分 + 向量相似度得分 + 业务规则加权

例如:

  • 用户说“退款到哪了”,关键词可以命中“退款”“进度”;
  • 向量检索可以理解“到哪了”与“进度查询”的语义相似性;
  • 业务规则可以提升当前租户、当前渠道、当前用户权限内工具的权重。

3. 查询改写:把用户问题变成检索问题

用户原始问题往往不适合直接检索。例如:

我那个钱怎么还没回来?

这句话需要改写成:

查询退款进度 / 退款到账状态

可以结合会话上下文、用户意图分类、历史订单状态进行改写。

简单规则:

  1. 如果用户问题包含“钱、退款、到账”
  2. → 优先检索 refund、payment、after_sales 相关工具
  3. 如果用户问题包含“什么时候到、物流、快递”
  4. → 优先检索 logistics、delivery、order 相关工具

4. 动态注入:只给模型看候选工具

这是 Tool Search 最关键的一步。

错误做法:

  1. 把所有工具定义全部传给模型

推荐做法:

  1. 检索出 Top 5 工具
  2. 过滤无权限工具
  3. 只把这 5 个工具定义传给模型

示意代码如下,重点表达流程,不绑定具体版本 API:

  1. ToolSearchQuery query = ToolSearchQuery.builder()
  2. .userId(userId)
  3. .scene("customer_service")
  4. .text(userInput)
  5. .topK(5)
  6. .build();
  7. List<ToolCandidate> candidates = toolSearchService.search(query);
  8. List<ToolDefinition> visibleTools = candidates.stream()
  9. .filter(c -> permissionService.canUse(userId, c.name()))
  10. .limit(3)
  11. .toList();
  12. String prompt = promptBuilder.build(userInput, visibleTools);
  13. ChatResponse response = chatModel.call(prompt);

如果项目使用 Spring AI 的工具调用能力,可以把 visibleTools 转换成当前框架支持的 Tool 定义,再交给模型进行 function calling / tool calling。

工具命名和描述治理:比检索算法更重要

很多 Tool Search 效果不好,不是检索模型不行,而是工具本身没有治理好。

1. 工具名称要稳定、可读、可区分

不推荐:

  1. getRefundStatus
  2. queryRefundStatus
  3. refundStatus
  4. getRefundInfo

这些名字对模型来说非常接近,容易误选。

推荐:

  1. queryRefundProgress // 查询退款进度
  2. applyRefund // 申请退款
  3. cancelRefund // 取消退款
  4. queryRefundBankInfo // 查询退款银行卡信息

命名建议遵循:

  1. 动词 + 业务对象 + 限定词

例如:

  1. queryOrderDetail
  2. cancelOrder
  3. modifyShippingAddress
  4. lockInventory
  5. releaseInventory

2. 描述要写清楚边界

一个高质量工具描述通常包括:

  1. 用途:这个工具解决什么问题
  2. 适用场景:用户什么话应该触发它
  3. 不适用场景:哪些问题不要用它
  4. 输入要求:需要哪些关键参数
  5. 权限要求:是否需要登录、是否有操作权限

例如:

  1. 用于查询退款进度,不适用于发起退款。
  2. 如果用户说“我要退款”,应调用 applyRefund。
  3. 如果用户说“退款多久到账”,应调用 queryRefundProgress。

3. 相似工具要做消歧

如果两个工具确实容易混淆,可以在描述中加入对比说明:

  1. queryRefundProgress:查询已有退款单的状态。
  2. queryRefundEligibility:查询当前订单是否满足退款条件。

这样模型在候选工具中更容易做出正确选择。

两阶段调用:进一步降低误选

对于工具特别多、业务特别复杂的 Agent,可以采用两阶段调用。

第一阶段:工具选择

模型只回答“应该调用哪个工具”,不生成完整参数。

  1. 用户问题:我的退款怎么还没到?
  2. 候选工具:
  3. 1. queryRefundProgress
  4. 2. applyRefund
  5. 3. queryOrderDetail
  6. 请选择最合适的工具,只输出工具名称。

第二阶段:参数生成与调用

确定工具后,再把该工具的详细参数结构交给模型:

  1. 已选择工具:queryRefundProgress
  2. 请根据用户问题生成调用参数。

这种方式的好处是:

  • 第一阶段上下文更短;
  • 工具选择更准确;
  • 参数生成更聚焦;
  • 更容易做权限校验和审计。

与模型选型、成本控制的关系

Tool Search 能减少工具定义带来的 Token 消耗,但模型本身也会影响工具调用效果。

不同模型在以下方面差异明显:

  • 指令遵循能力;
  • 长上下文理解能力;
  • 工具调用稳定性;
  • 参数生成准确率;
  • 多轮对话中的状态保持能力;
  • 响应速度和调用成本。

如果业务只是简单工具选择,可以优先考虑成本和响应速度更均衡的模型;如果涉及复杂多步推理、长上下文、多工具串联,则需要更关注模型的推理和工具调用能力。

在百度智能云词元所,可以进一步了解不同大模型的能力特点、价格与性能对比,并结合统一 API 接入方式评估多模型方案。对于需要同时接入多个模型、做调用管理和成本评估的团队来说,这类平台可以减少重复集成工作。

上线前必须看的指标

Tool Search 上线后,不要只看“能不能调用”,建议重点观察以下指标:

指标 说明
工具召回率 正确工具是否出现在候选集中
Top3 命中率 正确工具是否进入前三候选
工具选择准确率 模型最终选择的工具是否正确
平均注入工具数 每次请求实际传给模型的工具数量
单次请求 Token 数 评估上下文成本是否下降
工具调用成功率 工具执行是否成功
参数错误率 模型生成的参数是否合法
P95 延迟 检索和模型调用整体耗时
兜底触发率 无法识别工具时是否进入澄清或人工

建议建立一个小的评测集,例如:

  1. 用户问题:我的退款到哪了?
  2. 期望工具:queryRefundProgress
  3. 用户问题:我要修改收货地址。
  4. 期望工具:modifyShippingAddress
  5. 用户问题:这个商品还有货吗?
  6. 期望工具:queryInventory

每次调整工具描述、检索策略或模型后,都跑一遍评测集,避免凭感觉优化。

总结

当业务工具从几个增长到几十个时,继续把所有 Tool 一次性塞给模型,会带来上下文膨胀、工具误选、成本上升和权限风险。Spring AI 2.0 的 Tool Search 思路,本质上是把工具管理从“全量暴露”变成“检索召回 + 动态注入”。

实际落地时,可以按这个顺序推进:

  1. 先治理工具命名、描述、参数和权限;
  2. 建立关键词 + 向量 + 标签的混合检索;
  3. 每次只注入少量高置信度候选工具;
  4. 对复杂场景采用两阶段工具选择;
  5. 建立评测集,持续观察命中率、Token 成本和调用成功率;
  6. 结合百度智能云词元所进行多模型接入、价格对比和调用管理,让工具检索与模型选型形成完整闭环。