Agent 技能匹配不准,先别急着上向量库:问题可能出在描述上

大家好,我是 WeiWill。

最近我在用 Spring AI Alibaba 做一个审图工具。复杂施工图会先通过 Python 提取数据,再封装成一组可调用的 Skill。项目推进过程中,我们遇到一个很典型的问题:

声明里明明有这个 Skill,Agent 为什么就是选不中?

用户需求并不含糊,系统里也确实有对应能力,但 Agent 要么没有选择它,要么在几个相似 Skill 之间摇摆。

这类问题很容易把团队带到一个结论上:

技能多了,大模型找不准,应该加一个向量库。

这个思路听起来合理。把 Skill 描述转成向量,把用户请求也转成向量,再按相似度召回候选能力,最后交给模型判断。

但我把用户请求、候选 Skill 和 description 放在一起看了一遍后,发现真正的问题没有那么复杂。

不是模型理解不了,而是我们没有把 Skill 描述清楚。

所以我先做了一件更简单的事:不增加向量检索,不增加中间层,只重写 description,让它明确说明“什么情况下应该调用我”。调整后,原来匹配不稳定的场景,很快就能被模型正确识别。

这件事提醒我:Agent 的技能发现,不一定一开始就是向量检索问题。

Agent 技能发现导图

技能发现和知识检索不是一回事

向量检索最适合解决“召回”问题。

比如从几万篇文档中找相关段落,从历史工单中找相似案例,从产品手册中召回可能包含答案的章节。这类任务有一个共同点:系统不知道答案在哪里,只能先从大量非结构化内容中找出候选。

但 Skill 发现不完全一样。

Skill 通常是一项边界相对明确的可执行能力,例如查询订单状态、生成销售报表、提取发票字段、创建项目任务、检查服务器状态。

这里的核心不是“哪段文本和用户问题更相似”,而是:

用户当前意图,是否满足某个能力的调用条件?

这更接近语义路由和能力选择,而不是传统知识检索。

如果系统里只有几十个,或者一两百个 Skill,并且每个描述都比较短,大模型完全可以一次读取这些描述,再结合用户意图做判断。这个阶段直接上向量库,未必能解决根因,反而可能把描述问题藏起来。

一个 Skill 为什么会匹配不上

假设系统里有一个销售报表 Skill,它的描述是:

用于处理销售相关数据。

这句话从人的角度看没错,但对 Agent 来说几乎没有决策价值。

“销售相关数据”到底包括什么?查询单个订单算不算?查看客户欠款算不算?分析销售趋势算不算?导出月度报表算不算?修改订单金额算不算?

如果系统里同时存在订单查询、客户管理、财务统计和报表生成等多个 Skill,模型很难只凭这一句话划清边界。

当用户说:

帮我看看华东区 6 月份的回款异常,按客户汇总。

Agent 需要判断这到底属于销售查询、财务分析,还是报表生成。

如果几个 Skill 都写成“处理销售数据”“查询业务信息”“生成业务报表”,无论使用大模型还是向量库,匹配结果都可能不稳定。向量检索甚至会让问题更隐蔽,因为“回款”“客户”“销售”“报表”在语义上都很接近。

真正该改的,是 Skill 对自身能力边界的表达。

可以把描述改成这样:

当用户需要按区域、客户、时间范围汇总销售额、回款额、欠款额或异常记录时,使用此 Skill 生成只读统计结果。它不负责修改订单、不负责发起收款,也不用于查询单个订单的物流状态。

这段描述提供了四类关键信息:

  • 什么意图会触发它;
  • 它依赖哪些维度;
  • 它会输出什么结果;
  • 它明确不做什么。

这些信息比几个抽象关键词更有价值。

Description 是一份能力契约

很多团队写 Skill 描述时,会把它当成名称旁边的补充说明。

于是常见写法是:查询数据、处理文件、生成报告、管理用户、执行任务。

这些描述适合放在功能菜单里,却不适合让 Agent 做决策。Agent 不只需要知道“这个 Skill 是什么”,还需要知道:

什么时候应该选它,什么时候不应该选它?

所以我更愿意把 description 理解成一份面向模型的能力契约。它至少要说清四件事。

触发场景

说明用户通常会提出什么需求。

不要只写“生成报表”,而要写:

当用户需要按时间、部门、区域或客户维度汇总业务数据,并输出表格或摘要时使用。

必要输入

说明执行前需要哪些信息。

例如:

需要明确统计时间范围;区域、部门和客户为可选筛选条件。

这能帮助 Agent 判断信息是否充足。信息不足时,应该先追问,而不是直接调用。

输出结果

说明调用后会得到什么。

例如:

返回只读统计结果,包括汇总指标、异常明细和可选 CSV 文件。

模型知道输出类型后,才能判断这个 Skill 是否真的满足当前任务。

排除边界

说明哪些相似需求不应该调用它。

例如:

不负责修改业务数据,不用于查询单个订单状态,不执行预测分析。

这一点很重要。很多 Skill 冲突,不是因为正向描述太少,而是因为没有写清“不做什么”。

在 Agent 系统里,排除边界和能力范围同样重要。

为什么先改描述,通常更有效

如果问题来自描述不清,先改 description 有三个优势。

第一,反馈链路短。

模型选错 Skill 后,我们可以直接检查用户怎么表达、模型看到了哪些候选、正确 Skill 缺少什么触发信息、错误 Skill 为什么产生误导。改完后,用同一批请求重测,很快就能看到效果。

如果先引入向量库,排查链路会变长:文本怎么切分、向量有没有更新、阈值怎么设、Top-K 取多少、召回结果是否完整、最终排序为什么仍然错。每增加一层,系统就多一份配置、成本和故障点。

第二,语义边界可以被直接表达。

比如用户说:

查询服务器日志,并分析最近一次发布失败的原因。

“查询日志”和“执行服务器命令”在语义上很接近,但权限风险完全不同。

一个只读日志 Skill 可以被调用,不代表 Agent 就应该获得远程执行命令的能力。这类差异很难只靠向量距离表达,却可以在 description 中写清楚:

仅允许读取指定服务日志,不执行命令,不修改文件,不重启服务。

当然,描述不能替代权限控制,但它能减少错误路由。

第三,系统更容易保持简单。

Agent 工程里有个常见倾向:效果不稳定,就继续加组件。匹配不准,加向量库;排序不准,加重排模型;选择不准,再加规划 Agent。

复杂架构不是不能用,但它应该由明确指标推动,而不是由直觉推动。

如果几十个 Skill 通过一次模型判断就能稳定匹配,我不会为了架构看起来完整,再额外维护一套检索系统。

什么时候应该引入向量检索

“优先改描述”不等于“永远不用向量库”。

当 Skill 数量和复杂度继续增长,直接把所有描述交给模型也会遇到边界。

第一,候选能力太多。

如果系统里有几千甚至上万个 Skill,每次都把完整列表放进上下文,会带来明显的 Token、延迟和成本问题。这时向量检索适合做第一阶段候选召回:先找出几十个可能相关的 Skill,再交给模型做最终选择。

第二,技能来源分散。

如果 Skill 来自多个团队、插件市场或业务系统,能力列表持续变化,统一索引会更方便管理。但前提仍然是每个能力有相对规范的描述。否则向量库只是把低质量描述更快地召回出来。

第三,对延迟和成本非常敏感。

高并发场景下,每次都用较大模型读取完整能力列表,成本可能不可接受。此时可以用规则、分类器或向量召回先缩小范围,再用模型完成路由。

但这类优化应该基于真实调用量和延迟数据,而不是在系统刚开始开发时提前设计。

向量召回、模型判断和规则校验要分层

在复杂系统里,更合理的结构不是二选一,而是分层。

向量检索负责从大规模能力列表中快速找候选,解决上下文过大和召回效率问题。

大模型负责理解当前对话、判断真实意图、区分相似 Skill 边界、检查输入是否完整,并决定调用、追问还是拒绝。

确定性规则负责校验权限、限制高风险操作、检查参数、控制生产环境访问,阻止未授权执行。

这三层解决的问题不同。

最危险的设计,是把它们混在一起,认为“相似度最高”就等于“允许调用”。

技能发现只是在回答“可能应该使用哪个能力”,它不能替代鉴权,更不能替代执行前的风险检查。

我会怎么迭代 Skill 发现机制

如果一个 Agent 项目出现技能匹配不准,我建议先按下面的顺序验证。

第一,整理真实请求。

先准备 30 到 50 条典型请求,既包括应该命中的,也包括不应该命中的。里面要故意放入简称、不同表达、信息缺失、同时涉及多个 Skill、高风险操作和系统没有对应能力的请求。

第二,重写 Skill 描述。

每个描述都检查四件事:什么时候使用、需要什么输入、返回什么结果、明确不处理什么。两个 Skill 经常混淆,就把它们并排比较,补充彼此的排除边界。

第三,先做直接匹配测试。

让模型读取用户请求和候选描述,输出选择的 Skill、是否需要追问、缺少哪些参数、为什么排除其他相似能力。如果没有合适能力,就明确返回不匹配。

第四,记录失败案例。

不要只记录最终选了什么,还要保留用户请求、当时可见的候选能力、模型选择结果、实际正确结果、失败原因和修改后的描述版本。

第五,用指标决定是否增加向量库。

如果问题主要来自候选数量太大、上下文成本过高或响应延迟明显,再引入向量召回。如果问题仍然集中在几个相似 Skill 之间,继续调整描述和边界通常更有效。

最后的工程判断

现在 Agent 正在从“能调用工具”走向“能在真实工作流中长期运行”。到了这个阶段,Skill 数量会越来越多,技能发现也会逐渐成为基础问题。

在能力规模还可控时,优先让大模型直接理解 Skill 描述;匹配不准时,先检查描述质量,而不是第一时间增加向量库。

因为 Skill 描述不是装饰文案,而是 Agent 理解能力、区分边界和做出选择的接口。

向量库当然有价值,但它更适合解决大规模候选召回、上下文成本和检索效率问题。它不能自动修复模糊的能力定义,也不能替代权限校验和执行安全。

先把简单链路跑准,再决定是否增加复杂组件。

很多时候,Agent 不是缺少更高级的检索系统,而是缺少一份真正让模型看得懂的能力说明。

我是 WeiWill,深耕软件工程一线,专注 AI 应用落地与 Agent 开发。