Agent 中的 Tool Retrieval：工具城里的金牌导购

可视化演示

动态演示Agent中的Tool Re的核心机制，通过全局/局部/动态/静态四种模式展示关键概念与交互流程。

检索必要性

小林推门走进“万物工具城”，向导购老周求助：“我想把全家福挂上墙，但我租的房子不能打孔。”老周没有喊人把五万种工具全搬来，而是问了两句就带着小林走向“墙面固定”区。为什么导购绝不把整座城搬来？因为顾客要的不是“拥有所有工具”，而是“快速选对工具”。搬来全城，既费脚力，又让顾客在五千种锤子和三百种钉子里彻底看花眼。

Agent 也一样。一个真正落地的 Agent 系统往往注册了数百上千个 API：查天气、订酒店、算汇率、发邮件、查数据库……大模型的上下文窗口再大也是有限的，假设每个工具说明折算 50 个 token，一千个工具就是五万 token，窗口先被吃掉一大半，费用也直线上升。

更麻烦的是注意力稀释：无关工具的说明挤占大量位置，模型对真正相关工具的注意力权重被摊薄，选错率反而上升。所以“先检索、后决策”成了标配——先用轻量手段把战场缩小，再让大模型在少数候选里做精细抉择。

老周深谙此道：他带着小林直奔“墙面固定”区，而不是让小林在五万种工具里迷路。检索，就是 Agent 的“直奔主题”——用最小的成本，把模型的注意力聚焦在最该看的地方。

意图解析

老周没有急着拿货，而是先竖起耳朵听完：“租的房子不敢打孔”“照片挺重的”“不想用胶带留痕迹”。他在心里把这一堆口语总结成三个词：免打孔、轻量、可移除。这个“听诉求、抓重点”的过程，就是 Agent 工具检索的第一步——意图解析。

用户的原话往往口语化、带省略：“照片挂不上墙怎么办？”如果直接拿这句话去匹配“无痕钉挂钩”的工具描述，很可能因为措辞完全不同而匹配失败。于是有了查询改写：让大模型把口语展开成多个检索友好的表达，比如把“照片挂不上墙”改写成“免打孔挂画 轻量墙面固定 可移除挂钩”。

改写之后还要做意图分类和关键词抽取：判断这是“固定/安装”类需求，提炼出“挂墙、免打孔、轻量”等关键词。最后，把整理好的文本送给同一个编码器，变成查询向量 q，供后续检索使用。一句话总结：查询向量质量，决定了检索的天花板。

老周掏出小本子写下的三行要点，就是 Agent 里的“改写后查询”。别小看这一步——导购听得懂潜台词，才能在货架之间找得准；Agent 的检索也是如此。

工具向量化

老周为什么能秒懂“免打孔挂墙”对应无痕钉？因为他脑子里有一张货架地图，每件工具旁边都贴着“用途标签”：冲击钻→打孔、无痕钉→免打孔挂墙、重物挂钩→承重安装。Agent 的“脑内地图”就是工具向量化。

做法分三步：首先为每个工具写一段富描述，不能只写名字，要覆盖功能、参数、典型使用场景，比如“无痕钉：免打孔安装，适配 5kg 以内挂画，适合租房墙面”；然后让同一个编码器把这段描述变成 d 维向量 t_i；最后把所有向量建成索引（如 FAISS、HNSW），供检索时快速查找。

向量化的精妙之处在于：语义接近的文本会落在向量空间相近的位置。“免打孔挂钩”和“无痕钉”的向量会很近，而“扳手”的向量离得很远。这样即使查询和描述措辞完全不同，也能靠语义位置匹配上。

标签贴得好，导购才能扫货架；描述写得好，检索才能找得准。这也是为什么资深团队会花大力气做“描述工程”——工具向量化的质量，几乎决定了整个检索系统的上限。

语义检索

老周拿着整理好的需求小纸条，在货架间快速走动：看到“免打孔”就停下来多看一眼，看到“扳手”“电锯”就掠过去。这个“按语义扫货架”的动作，就是 Agent 工具栏里的语义检索。

技术实现上，检索系统计算查询向量 q 与每个工具向量 t_i 的余弦相似度，取值越接近 1 说明方向越一致、语义越接近。计算完所有工具后，按相似度从高到低排序，取前 K 个作为候选。为了防召回不全，工程上还常用混合检索：让关键词检索（如 BM25，负责字面匹配）与向量检索（负责语义匹配）并行跑，把两路结果合并去重，互相补漏。

别忽略阈值控制：相似度太低的候选不要硬凑，比如 0.1 分的“扳手”明显和“挂画”无关，直接丢弃，避免噪声工具混进候选集污染后续决策。

老周回来时只带了 5 件工具而不是 30 件，因为扫货原则是“宁缺毋滥”。检索召回同样讲究质量与数量的平衡：召回太少怕漏，召回太多怕噪声，Top-K 与阈值就是这两个方向的调节旋钮。

候选重排序

回到柜台，老周把 5 件候选一字排开，逐一细看：冲击钻？要打孔，排除。超重挂钩？承重够了但会留大痕迹，排除。最后锁定“无痕钉 + 小锤子”的组合。这个“再细细比对”的动作，在 Agent 里叫重排序。

为什么要重排？因为向量检索（业内称双塔编码器）为了快，查询和工具是分开各自编码的，彼此看不到对方的具体细节，难免粗放。重排序阶段改用交叉编码器，把查询文本和工具描述拼接在一起，投入同一个模型“仔细看一遍”，判断两者是否真正匹配——看得细，判得准，但速度慢，所以只对已经筛出来的 Top-K 小集合做。

实战中还常做多信号融合：把向量相似度、关键词命中数、工具历史调用成功率等打分加权求和，得到最终排序分，再截断到更小的 K'（通常 2~3 个），只把最有把握的候选交给大模型做最后决策。粗筛求快，精排求准，两者缺一不可。

导购的“再想想”就是 Agent 的“精排”——第一轮靠跑得快圈定候选人，第二轮靠看得细挑出最优解。这两轮配合，才是工具检索准确率的关键保障。

反馈迭代

小林满意地带着无痕钉走了。老周却默默在柜台的小本子上记了一笔：“租客挂照片 → 无痕钉 + 小锤子，命中。”他决定下次遇到类似需求，直接优先推荐。这个“记笔记”的习惯，就是工具检索系统的反馈迭代。

离线侧，团队会构建一个标注评测集：收集一批真实用户请求，标注“这条请求到底该用哪些工具”。然后用 Recall@K 这样的指标度量检索质量，每次改动描述或排序逻辑都要回归测试，防止“改好了 A 类请求、砸了 B 类请求”。

在线侧，系统记录每次检索的命中与失败日志。检索失败时执行回退策略：改写查询再试一次、放宽相似度阈值、或直接回退到通用兜底工具；同时把失败案例定期回流，用来修正工具描述、调优排序权重。日子久了，导购越来越懂顾客，检索系统也越来越懂用户。

导购的“小本子”越记越厚，服务就越老练；Agent 的检索系统也一样——数据喂得越多、回退练得越勤，它就越懂得在关键时刻递出那把最趁手的工具。

AI 应用场景

Python 演示

"""极简 Tool Retrieval 演示：词袋向量 + 余弦相似度，实现工具语义召回与粗排"""import mathfrom collections import Counter  def tokenize(text):    tokens = []    for word in text.strip().lower().split():        if any('\u4e00' <= ch <= '\u9fff' for ch in word):            if len(word) == 1:                continue            tokens.extend(word[i:i + 2] for i in range(len(word) - 1))        elif len(word) >= 2:            tokens.append(word)    return tokens  def build_vocab(docs):    vocab = []    for doc in docs:        for w in tokenize(doc):            if w not in vocab:                vocab.append(w)    return vocab  def to_vector(text, vocab):    counts = Counter(tokenize(text))    v = [counts.get(w, 0) for w in vocab]    norm = math.sqrt(sum(x * x for x in v))    return [x / norm for x in v] if norm else v  def cosine(a, b):    return sum(x * y for x, y in zip(a, b))  class ToolRetriever:    def __init__(self, tools):        self.tools = tools        self.vocab = build_vocab([t["desc"] for t in tools])        self.tool_vecs = [to_vector(t["desc"], self.vocab) for t in tools]     def retrieve(self, query, top_k=3, threshold=0.05):        qv = to_vector(query, self.vocab)        scored = []        for i, tv in enumerate(self.tool_vecs):            s = cosine(qv, tv)            if s >= threshold:                scored.append((s, i))        scored.sort(reverse=True)        return [(self.tools[i]["name"], round(s, 3)) for s, i in scored[:top_k]]  def main():    tools = [        {"name": "calculator",  "desc": "数学 计算 表达式 加减乘除 calculate math"},        {"name": "weather",     "desc": "查询 天气 预报 城市 weather forecast"},        {"name": "search_wiki", "desc": "搜索 百科 知识 文章 wiki search"},        {"name": "send_email",  "desc": "发送 邮件 给 收件人 email send"},        {"name": "translate",   "desc": "翻译 文本 语言 互译 translate text"},        {"name": "currency",    "desc": "货币 汇率 兑换 转换 currency exchange"},    ]    retriever = ToolRetriever(tools)    queries = ["帮我算一下这个数学表达式", "今天天气怎么样", "把这段话翻译成英文"]    for q in queries:        print("Query:", q)        print(" ->", retriever.retrieve(q))  if __name__ == "__main__":    main()

1. tokens.extend(word[i:i + 2] for i in range(len(word) - 1))中文没有空格分词，按“相邻双字”切出语义单位，模拟 token 化的效果。
2. norm = math.sqrt(sum(x * x for x in v))计算向量模长并归一化，让余弦相似度只关心语义方向，而非词频高低。
3. self.tool_vecs = [to_vector(t["desc"], self.vocab) for t in tools]预先把所有工具描述编码成向量并缓存，相当于“向量索引”，检索时不再重算。
4. for i, tv in enumerate(self.tool_vecs):逐个工具与查询向量比对，等价于导购沿货架一张张看标签。
5. scored.sort(reverse=True)按相似度从高到低排序，等价于“货架扫描后按匹配度排队”。
6. if __name__ == "__main__":程序入口，保证被 import 时不会自动执行演示逻辑。

常见误区

面试题