semantic-router 基于嵌入的路由（Embedding Based Routing）实战指南：用语义相似度替代关键词匹配

后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载本篇技术指南讲解 semantic-router 项目中的基于嵌入的路由Embedding Based Routing利用嵌入模型Qwen3、Gemma 等计算用户查询与预定义类别候选的语义相似度据此将请求路由到不同决策与模型。文中给出完整可运行的config.yaml配置示例、聚合方法与模型选择策略并结合仓库源码说明底层打分与校验逻辑。读完本文你将能够在自己的场景中配置嵌入信号embedding signal、定义引用这些信号的决策并正确校准阈值以处理多样化措辞与快速演变的类别。基于嵌入的路由是什么基于嵌入的路由Embedding Based Routing是一种按语义而非关键词匹配请求的路由方式系统先把用户查询与预定义类别例如技术支持产品咨询账号管理的代表性候选短语分别编码为向量再计算查询向量与候选向量的余弦相似度当相似度达到预设阈值时请求就被路由到对应的决策与模型池。它位于 semantic-router 的信号signal→ 决策decision链路中嵌入信号embedding signal负责从请求中提取语义证据决策decision再根据证据选择模型并挂载插件。该能力依赖global.model_catalog.embeddings中配置的嵌入模型运行时具体说明见 运行时嵌入指南。关键优势可扩展Scalable无需重新训练模型即可处理无限数量的类别快速Fast使用高效的嵌入模型Qwen3、Gemma实现 10-50ms 的推理灵活Flexible通过更新关键词列表即可添加/删除类别无需重新训练模型语义化Semantic捕捉超出精确关键词匹配的含义。它解决了什么问题当用户以不同措辞表达同一问题时纯关键词匹配会失效。基于嵌入的路由主要解决释义处理Paraphrase handling如何安装即使与候选短语没有完全相同的单词也能匹配到安装指南意图检测Intent detection根据语义而非表面模式进行路由模糊匹配Fuzzy matching处理拼写错误、缩写和非正式语言动态类别Dynamic categories无需重新训练分类模型即可添加新类别多语言支持Multilingual support嵌入向量可以捕捉跨语言的语义。从仓库源码结构看嵌入信号与其他信号类型关键词、复杂度、语言、上下文等并列定义在Signals结构中见 signal_config.go其定位正是作为从词法信号向完整分类器过渡的一级台阶。何时使用具有多样化查询措辞的客户支持场景用户以多种不同方式询问同一事物的产品咨询场景需要对错误描述进行语义理解的技术支持场景需要频繁添加/更新类别的快速演变类别场景适度的延迟容忍度为了更好的语义准确性10-50ms 是可接受的。配置在 config.yaml 中添加嵌入信号与决策在config.yaml中添加嵌入规则。下面是教程中的完整参考配置它由两大部分组成signals.embeddings定义嵌入信号名称、阈值、候选短语、聚合方法decisions定义引用这些信号的决策优先级、规则条件、模型引用、插件# 定义嵌入信号 signals: embeddings: - name: technical_support threshold: 0.75 candidates: - 如何配置系统 - 安装指南 - 故障排除步骤 - 错误信息解释 aggregation_method: max - name: product_inquiry threshold: 0.70 candidates: - 产品特性和规格 - 定价信息 - 库存和供货情况 aggregation_method: avg - name: account_management threshold: 0.72 candidates: - 重置密码 - 账号设置 - 订阅管理 aggregation_method: max # 使用嵌入信号定义决策 decisions: - name: technical_support description: 路由技术支持查询 priority: 100 rules: operator: OR conditions: - type: embedding name: technical_support modelRefs: - model: openai/gpt-oss-120b use_reasoning: true plugins: - type: system_prompt configuration: system_prompt: 你是一位技术支持专家在系统配置和故障排除方面拥有深厚的知识。 - name: product_inquiry description: 路由产品咨询查询 priority: 100 rules: operator: OR conditions: - type: embedding name: product_inquiry modelRefs: - model: openai/gpt-oss-120b use_reasoning: false plugins: - type: system_prompt configuration: system_prompt: 你是一位产品专家对产品特性、定价和供货情况有全面的了解。 - type: semantic-cache configuration: enabled: true similarity_threshold: 0.85 - name: account_management description: 路由账号管理查询 priority: 100 rules: operator: OR conditions: - type: embedding name: account_management modelRefs: - model: openai/gpt-oss-120b use_reasoning: false plugins: - type: system_prompt configuration: system_prompt: 你是一位账号管理专家。请谨慎且安全地处理用户账号查询。信号字段逐个拆解附源码依据EmbeddingRule结构体定义了嵌入信号的全部字段见 signal_config.go字段类型说明namestring信号唯一名称供决策conditions中type: embedding引用thresholdfloat32匹配阈值。无负候选时取余弦单位[-1, 1]存在负候选时取边界单位[-2, 2]candidatesstring[]正向候选短语构成正向候选库image_candidatesstring[]正向图片候选可选需多模态嵌入模型negative_candidatesstring[]负向候选对比示例存在时最终分数为正向得分减去负向得分negative_image_candidatesstring[]负向图片候选可选aggregation_methodstring聚合方式max、mean或anyquery_modalitystring查询模态text默认、image、audioprototype_scoringobject按规则覆盖候选库的原型压缩与打分策略可选几点需要特别说明aggregation_method的实际枚举是max/mean/any。教程示例中的avg对应源码中的mean常量AggregationMethodMean配置校验器明确要求取值只能是max, mean, any见 validator_embedding.go。正向候选至少需要一条只有负候选或空候选的规则无法匹配会在配置加载期被校验器拒绝见 validator_embedding.go。query_modality: image/audio与图片候选都要求model_type: multimodal否则配置加载即报错见 validator_embedding.go。教程配置写在顶层signals:下而当前仓库实际布局将其包裹在routing:下即routing.signals.embeddings。仓库内的真实示例见 support.yaml其中technical_supportthreshold 0.75、max与account_managementthreshold 0.72、max与教程配置一致。当前仓库主配置中的嵌入信号config/config.yaml 中给出了更贴近实际使用的写法包括完整的prototype_scoring覆盖、aggregation_method: any的用法以及带query_modality: text和空负候选占位的clinical_query_intent规则embeddings: - name: technical_support threshold: 0.75 aggregation_method: max # A complete rule override; omission inherits the family configuration. prototype_scoring: enabled: true cluster_similarity_threshold: 0.9 max_prototypes: 8 best_weight: 0.75 top_m: 2 margin_threshold: 0.0 candidates: - how to configure the system - installation guide - troubleshooting steps - error message explanation - name: account_management threshold: 0.72 aggregation_method: any candidates: - password reset - account settings - billing information - subscription management - name: clinical_query_intent query_modality: text image_candidates: [] negative_candidates: [] negative_image_candidates: [] threshold: 0.72 aggregation_method: max candidates: - patient symptoms or clinical question - medication interaction or dosage question - test result interpretation request嵌入模型qwen3高质量1024 维32K 上下文gemma均衡768 维8K 上下文支持 Matryoshka 降维128/256/512/768auto根据质量/延迟优先级自动选择。这些模型名会出现在嵌入请求的model_used响应字段中qwen3、gemma 或 unknown见 apiserver/config.go。在模型运行时层面嵌入模型在global.model_catalog.embeddings.semantic.embedding_config.model_type中声明mmbertVela Embedding 槽位、qwen3Qwen3-Embedding-0.6B1024 维或multimodalVela Omni支持图片/音频查询详见 运行时嵌入指南。也可以配置 OpenAI 兼容的外部嵌入端点backend: openai_compatible、model_type: remote替换本地模型用于文本场景。聚合方法Aggregation Methodsmax使用最高的相似度分数mean教程中写作 avg使用所有候选的平均相似度any如果任何一个候选超过阈值则匹配。从源码实现看打分发生在 embedding_classifier_scoring.gomean聚合会关闭最佳权重与Top-M 支撑BestWeight: 0, TopM: 0直接对候选库取平均max等默认策略则走原型打分选项defaultPrototypeScoreOptions。每个规则逐条打分scoreRulesSlice当存在负候选库时最终得分是正向聚合分减去负向聚合分见 embedding_classifier_scoring.go基础相似度计算使用归一化向量内积余弦相似度见 embedding_classifier_scoring.go。匹配判定方面findAllMatchedRules先收集所有score threshold的硬匹配按分数降序、同名规则按名称排序没有硬匹配且开启了软匹配enable_soft_matching时才考虑分数达到min_score_threshold的候选top_k可限制最终输出的匹配数量见 embedding_classifier_scoring.go。请求示例配置完成后向路由器发送 OpenAI 风格的对话补全请求即可触发嵌入路由示例中model: MoM表示请求经由模型路由决策层处理# 技术支持查询 curl -X POST http://localhost:8801/v1/chat/completions \ -H Content-Type: application/json \ -d { model: MoM, messages: [{role: user, content: 如何排除连接错误}] } # 产品咨询 curl -X POST http://localhost:8801/v1/chat/completions \ -H Content-Type: application/json \ -d { model: MoM, messages: [{role: user, content: 有哪些定价方案}] }上例中如何排除连接错误虽未包含故障排除的字样但由于与technical_support的候选短语在嵌入空间中高度相似会被路由到技术支持决策有哪些定价方案同理被路由到产品咨询决策。若需直接调试嵌入与相似度接口也可使用分类 API 服务器上的/v1/embeddings与相似度计算端点其实现与参数校验见 route_embeddings.go。真实世界用例1. 客户支持可扩展类别问题需要每周添加新的支持类别而无需重新训练模型解决方案通过更新关键词列表来添加新类别嵌入模型负责语义匹配影响部署新类别只需几分钟而重新训练模型需要数周。2. 电子商务支持快速语义匹配问题我的订单在哪里、追踪包裹、物流状态都表达同一个意思解决方案Gemma 嵌入10-20ms将所有变体路由到订单追踪类别影响95% 的准确率10-20ms 的延迟可处理 5K 次查询/秒以上数据来自教程文档陈述实际数值需结合自身数据集验证。3. SaaS 产品咨询灵活路由问题用户以 100 多种不同的方式询问定价解决方案语义相似度将所有变体匹配到定价信息关键词影响单个类别即可处理所有定价查询无需显式规则。4. 创业公司迭代快速更新类别问题产品快速演变需要每天调整类别解决方案在配置中更新嵌入关键词无需重新训练模型影响更新类别只需几秒钟而微调模型需要数天。5. 多语言平台语义理解问题英语、西班牙语、中文的相同问题需要相同的路由解决方案嵌入模型自动捕捉跨语言语义影响单个类别定义即可跨语言工作。模型选择策略自动模式推荐model: auto quality_priority: 0.7 # 倾向于准确度 latency_priority: 0.3 # 接受一定延迟根据优先级自动选择 Qwen3高质量或 Gemma快速为每个请求平衡准确度与速度。从源码看quality_priority与latency_priority取值必须在[0.0, 1.0]内两者都未设置时默认各取 0.5见 route_embeddings.go 与 apiserver/config.go越界值会被返回INVALID_PARAMETER错误。Qwen3高质量model: qwen3 dimension: 1024最适合复杂查询、细微区别、高价值交互延迟每个查询约 30-50ms用例账号管理、金融查询。Gemma快速model: gemma dimension: 768 # 或使用 512, 256, 128 实现 Matryoshka最适合高吞吐量、简单分类、成本敏感延迟每个查询约 10-20ms用例产品咨询、一般支持。性能特征以下为教程文档给出的参考特征实际表现取决于硬件、模型版本与部署形态模型维度延迟准确度内存Qwen3102430-50ms最高~2.4GBGemma76810-20ms高~1.2GBGemma5128-15ms中~1.2GBGemma2565-10ms较低~1.2GB另外可参考 运行时嵌入指南默认的 Vela 1.0 Embedding 支持 32,768 token 输入并可从早期层3、6、11、22 层输出 64/128/256/512/768 维向量以换取速度。最佳实践候选集设计与阈值校准把候选集当成一个小型语义分类器描述你想识别的那类输入用意图的多变体而非同一句话的多个版本从多个角度覆盖类别近似重复的候选对召回提升有限还可能让规则看起来比实际校准得更好max倾向最强示例mean用于需要候选集整体共识的场景默认原型打分还会考虑其他原型对最佳相似度的支撑best_weight/top_m图片/音频规则默认保留全部候选并取原始最大值阈值必须按已部署模型重新校准相似度分数与阈值在模型、维度、模态之间不可移植更换任一要素后需用带标签的正负流量重新评估可选的软匹配当没有规则达到阈值时可开启enable_soft_matching: true并配合top_k、min_score_threshold做排名式意图选择若某规则的阈值必须是硬边界如风险、隐私条件请保持关闭。完整的软匹配与原型打分配置见 learned/embedding.md多模态扩展嵌入规则支持query_modality: image/audio、image_candidates与正负候选库得分公式为max(cosine(query, positive)) - max(cosine(query, negative))阈值单位相应变为[-2, 2]。仓库内的图片路由示例含身份证件图、代码/终端截图、办公环境图三类规则及阈值校准记录见 image-routing.yaml。参考配置仓库内嵌的真实文本嵌入信号示例support.yamltechnical_support、account_management两条规则主配置文件中的嵌入信号与决策编排config/config.yaml嵌入信号权威教程软匹配、原型打分、多模态查询、正负候选库learned/embedding.md配置 JSON Schema 中对嵌入规则各字段的约束router-config-v0.3.schema.json。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router Embedding Signal 完整指南基于语义相似度的向量路由信号配置与多模态实战semantic router Embedding Signal 完整指南基于语义相似度的向量路由信号配置与多模态实战 本文是 semantic router后端API网关模型推理服务AI Agentsemantic-router 语义工具选择Semantic Tool Selection实战指南基于相似度的上下文感知工具路由semantic router 语义工具选择Semantic Tool Selection实战指南基于相似度的上下文感知工具路由 在 AI Agent 接后端API网关模型推理服务AI AgentSemantic Router 的 Router DC 选择算法基于双对比学习的语义相似度模型路由实战指南Semantic Router 的 Router DC 选择算法基于双对比学习的语义相似度模型路由实战指南 导读 router_dc 是 Semantic R后端API网关模型推理服务AI Agent上一篇深入理解spotify-adblock-linux的核心代码getaddrinfo与URL拦截实现下一篇res-downloader视频解密下载完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考