SynCRAG Skill

当一个 AI Agent 只有十几个工具时，靠关键词或逐项浏览还能勉强工作；当技能市场扩展到数万项能力，真正困难的事情变成了“在用户说法和技能说明完全不同的情况下，仍然找到正确工具”。SynCRAG-skill 仓库中的 SkillGraph 正是为这个规模问题设计的检索系统。

补上用户语言与技能说明之间的语义缺口

现实中的 Skill 描述通常从开发者视角出发，写的是函数、框架和配置；用户提出的却是“怎样把网站上线”“帮我检查云基础设施”这类任务。两段文字可能没有明显的共同关键词，但表达的是同一个需求。只对原始描述做向量检索，很容易错过真正相关的 Skill。

SkillGraph 采用“LLM-for-Index, Zero-Token Runtime”的两阶段方案。预处理阶段让 LLM 为每项 Skill 生成多种可能的用户查询，再将原始描述和合成查询一起嵌入多向量索引。运行时只需要对用户请求生成向量，并计算它与 Skill 向量及合成查询向量的相似度；检索过程本身不再调用 LLM，也不消耗推理 Token。

这种设计把昂贵的语义补全放在一次性索引构建中，将高频在线请求压缩成可预测的向量运算。对于 Skill 商店、Agent 平台和企业内部工具注册中心，它意味着更低的单次查询成本，也减少了“为了找工具先让大模型读一遍所有工具”的延迟。

从研究实验到可调用服务

仓库提供了完整的索引构建、检索和评测链路：

• 使用 all-MiniLM-L6-v2 为原始 Skill 和合成查询建立归一化多向量索引。
• 将原始描述相似度与每项 Skill 的最佳合成查询相似度组合排序。
• 可选关键词增强，为高精度术语匹配提供额外信号。
• 提供 Python API，并可通过 FastAPI 的 /retrieve 接口部署为服务。
• 包含 SkillsBench、交叉验证、关键词对比和合成查询消融实验。

在仓库报告的 SkillsBench 实验中，系统以 34,396 项真实 Skill 为候选池，Dense + SynQ 达到 71.0% Recall@10；相较只检索原始描述的 62.8%，提升 8.1 个百分点，报告平均延迟约为 22 ms，运行时不调用 LLM。这个结果并不代表所有数据集上的普遍保证，但说明“为索引补充任务化表达”可以显著改善大规模技能发现。

适合怎样的开发者

如果你正在构建拥有大量工具的 Agent、维护企业内部能力目录，或研究工具路由和检索增强生成，SkillGraph 提供了一个可以直接运行和继续实验的基线。你可以替换嵌入模型、合成查询策略、排序方式或关键词规则，也可以将 FastAPI 服务接入自己的 Agent 调度层。

这个项目带来的核心启发是：不是每一次智能决策都必须发生在运行时。把 LLM 用在更适合离线完成的语义重建上，在线阶段就可以获得更便宜、更快，也更容易测量和复现的检索系统。