引言在构建复杂的 AI 应用时我们常常需要根据用户查询的主题或意图将请求分发到不同的处理模块。例如一个客服机器人可能需要将技术问题转给技术专家、将账单问题转给财务系统、将投诉转给投诉处理部门。传统做法是使用关键词匹配或规则分类但这些方法维护困难、泛化能力弱。语义路由Semantic Routing提供了一种更智能的方式它将每个可能的目标称为“路由”Route用一组代表性的参考语句references来刻画当用户查询到来时系统计算查询与所有参考语句的语义相似度并选择最匹配的一个或多个路由进行分发。RedisVL 的SemanticRouter类基于 Redis 的向量搜索能力实现了高效、可扩展的语义路由。它将每个参考语句转换为向量并存储在 Redis 中查询时通过 KNN 搜索找到最相似的参考再聚合到路由层面做出决策。本指南将带你从零开始掌握如何定义路由、初始化路由器、执行查询路由、动态管理路由引用以及序列化配置。前置条件已安装 RedisVLpip install redisvl一个运行中的 Redis 实例推荐 Redis 8 或 Redis Cloud概要定义包含参考语句和距离阈值的路由初始化和配置SemanticRouter将查询路由到单个或多个匹配路由序列化和恢复路由器配置JSON / YAML动态添加、获取和删除路由引用语义路由的工作原理语义路由的核心是向量相似度搜索。其流程如下定义路由每个路由有一个名称、一组参考语句例如典型问题或关键词以及一个距离阈值决定匹配的宽松程度。向量化所有参考语句通过嵌入模型如sentence-transformers/all-mpnet-base-v2转换为高维向量并存入 Redis 的向量索引中。查询当用户输入查询时同样将其向量化并在 Redis 中执行 KNN 搜索找出距离最近的若干参考语句。聚合与决策根据找到的参考语句所属的路由采用平均距离或最小距离等聚合方法计算每个候选路由的最终得分距离。只有那些距离小于各自路由阈值的路由才会被采纳。下图直观展示了这一流程是否用户查询将查询向量化在 Redis 中执行 KNN 搜索得到 N 个最近的参考语句及其距离按路由分组聚合距离平均/最小距离 路由阈值将该路由加入候选列表丢弃返回排序后的路由列表这种方式的优势在于语义理解不依赖关键词能处理同义表达。灵活阈值每个路由可单独控制匹配严格程度。多路由支持一个查询可以同时匹配多个路由例如“AI 在篮球中的应用”既匹配技术也匹配体育。定义路由每个路由由Route对象定义关键属性包括name路由的唯一标识。references字符串列表代表该路由的语义覆盖范围。可以是问题、关键词或短语。metadata可选字典用于存储额外信息如优先级、分类标签。distance_threshold余弦距离阈值范围 0~2越小越严格。只有查询与路由中某个参考的距离小于该阈值时才视为匹配。下面定义三个路由技术、体育、娱乐。fromredisvl.extensions.routerimportRoute technologyRoute(nametechnology,references[人工智能有哪些最新进展,给我讲讲最新的科技产品,科技领域有什么新趋势],metadata{category:tech,priority:1},distance_threshold0.71)sportsRoute(namesports,references[昨晚谁赢了比赛,告诉我即将到来的体育赛事,体育界最近有什么新闻,体育,篮球和足球],metadata{category:sports,priority:2},distance_threshold0.72)entertainmentRoute(nameentertainment,references[现在最火的电影是什么,谁获得了最佳男演员奖,娱乐圈有什么新鲜事],metadata{category:entertainment,priority:3},distance_threshold0.7)说明距离阈值需要根据实际应用调整。较高的阈值如 0.72会匹配更多查询但可能误召较低的阈值如 0.7更严格召回率降低。初始化 SemanticRouterSemanticRouter在初始化时会自动在 Redis 中创建索引如果不存在。你可以指定嵌入模型默认使用HFTextVectorizer模型为sentence-transformers/all-mpnet-base-v2。importosfromredisvl.extensions.routerimportSemanticRouterfromredisvl.utils.vectorizeimportHFTextVectorizer os.environ[TOKENIZERS_PARALLELISM]falserouterSemanticRouter(nametopic-router,# Redis 索引名称vectorizerHFTextVectorizer(),# 嵌入模型routes[technology,sports,entertainment],# 初始路由列表redis_urlredis://localhost:6379,overwriteTrue# 如存在同名索引则覆盖)初始化后可以查看索引信息rvl index info-itopic-router你会看到索引包含reference文本、vector向量、route_name标签等字段。num_docs等于所有参考语句的总数此处为 11 条。简单路由查询使用router(query)方法返回最佳匹配的路由RouteMatch对象包含名称和距离。若无匹配则返回nameNone。# 匹配技术路由route_matchrouter(你能告诉我人工智能的最新进展吗)print(route_match)# RouteMatch(nametechnology, distance0.419...)# 不匹配任何路由route_matchrouter(外星人真的存在吗)print(route_match)# RouteMatch(nameNone, distanceNone)如果需要返回多个候选路由按距离升序使用route_many方法# 返回最多 3 个候选路由matchesrouter.route_many(AI 如何在篮球中应用,max_k3)formatchinmatches:print(match.name,match.distance)# 可能输出: technology 0.556, sports 0.671聚合方法Aggregation Method当查询匹配到一个路由的多个参考时需要将这些距离聚合为一个最终距离。SemanticRouter支持两种聚合方式avg默认计算该路由所有匹配参考的平均距离。min只取最小的距离即最接近的参考。选择min会让路由更容易被匹配因为只要有一个参考足够接近即可而avg则更稳健能避免因个别噪音参考导致的误匹配。你可以通过更新路由配置来切换聚合方法fromredisvl.extensions.routerimportRoutingConfigfromredisvl.extensions.router.schemaimportDistanceAggregationMethod router.update_routing_config(RoutingConfig(aggregation_methodDistanceAggregationMethod.min,max_k3))matchesrouter.route_many(勒布朗·詹姆斯)print(matches)# 可能只匹配 sports序列化与恢复你可以将路由器配置导出为字典或 YAML 文件便于保存或跨环境迁移。# 导出为字典config_dictrouter.to_dict()print(config_dict.keys())# 包含 name, routes, vectorizer, routing_config# 从字典恢复router2SemanticRouter.from_dict(config_dict,redis_urlredis://localhost:6379)# 导出为 YAML 文件router.to_yaml(router.yaml,overwriteTrue)# 从 YAML 恢复router3SemanticRouter.from_yaml(router.yaml,redis_urlredis://localhost:6379)恢复时Redis 索引会自动重建如果不存在。动态管理路由引用在实际应用中你可能需要动态添加或删除某个路由的参考语句而不需要重建整个路由器。SemanticRouter提供了相关方法。添加参考added_idsrouter.add_route_references(route_nametechnology,references[最新 AI 趋势,新科技产品])print(added_ids)# 返回新增参考的 Redis key 列表获取参考你可以按路由名称或参考 ID 获取所有参考语句。# 按路由名称获取refsrouter.get_route_references(route_nametechnology)forrefinrefs:print(ref[reference])# 按参考 ID 获取示例取第一个first_idrefs[0][reference_id]single_refrouter.get_route_references(reference_ids[first_id])删除参考可以按路由名称删除该路由下的所有参考或按指定 ID 删除特定参考。# 删除整个 sports 路由的参考deleted_countrouter.delete_route_references(route_namesports)print(f删除了{deleted_count}条参考)# 删除特定参考deleted_countrouter.delete_route_references(reference_ids[first_id])print(f删除了{deleted_count}条参考)清理资源clear()清空索引中的所有参考数据但保留索引结构。delete()删除整个索引包括数据结构彻底移除。router.clear()# 清空数据router.delete()# 删除索引总结原理基于向量相似度搜索和聚合实现灵活的语义路由。定义路由通过参考语句和距离阈值刻画每个路由的语义范围。查询路由支持单匹配和多匹配可调节聚合方法平均/最小。动态管理可以随时增删改路由参考无需重建索引。可移植性配置可序列化为字典或 YAML方便版本控制和部署。语义路由是构建智能对话系统、RAG 应用、多任务分发系统的核心组件。RedisVL 提供的高性能向量检索能力让这一切变得简单而高效。
