一、为什么需要语义路由？
1.1 传统路由的局限性
在构建 AI 应用时，我们经常需要将用户请求分发到不同的处理单元。传统做法是基于关键词或规则匹配：
# ❌ 传统关键词路由 --- 脆弱、僵化
def route_request(query: str) -> str:
if "退款" in query or "退货" in query:
return "after_sales_agent"
if "价格" in query or "多少钱" in query:
return "price_agent"
if "你好" in query or "帮助" in query:
return "greeting_agent"
return "fallback_agent"这种方案的致命缺陷在于：
- 语义鸿沟：用户说"我想把东西退掉"和"申请退款"意思相同，但关键词不匹配
- 组合爆炸：同一意图的表达方式有成百上千种
- 维护成本：每新增一个路由规则都需要手动编写和维护关键词列表
- 僵化死板：无法处理模糊查询、反问、隐含意图等复杂场景
1.2 语义路由的优势
语义路由（Semantic Router）使用自然语言理解（NLU）技术，将用户请求映射到语义空间中进行匹配：
# ✅ 语义路由 --- 智能、灵活、可扩展
router = SemanticRouter()
route = router.route("我想把这个玩意儿退掉") # → "after_sales_agent"相比传统路由，语义路由具有以下核心优势：
| 对比维度 | 传统关键词路由 | 语义路由 |
|---|---|---|
| 表达能力 | 只能精确匹配关键词 | 理解语义相似度 |
| 维护成本 | 每新增场景需加大量规则 | 每个意图只需少量样本 |
| 容错能力 | 拼写错误、同义词全部失效 | 自然容忍变体表达 |
| 扩展性 | 规则数量指数级增长 | 线性的样本扩展 |
| 模糊处理 | 不支持 | 支持置信度阈值判断 |
1.3 典型应用场景
- 智能客服分流：将用户咨询分发到对应的业务处理 Agent
- 多模型网关：基于查询类型选择最合适的 LLM（编程问题→Code Agent，创意写作→Creative Agent）
- 工具选择器：在 Function Calling 中决定调用哪个 API
- 知识库导航：将问题导向最相关知识库区域
- 权限路由：基于查询敏感度决定是否需要高权限模型
二、架构设计
2.1 整体架构
我们设计的语义路由系统包含以下核心组件：
┌─────────────────────────────────────────────┐
│ 用户请求 (Query) │
└─────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 预处理器 (Preprocessor) │
│ • 文本清洗 • 标准化 • 长度检查 │
└─────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 编码器 (Encoder) │
│ • 文本 → 向量 (Text Embedding) │
└──────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 路由引擎 (Router Engine) │
│ • 相似度计算 • Top-K 排序 │
│ • 置信度阈值 • 路由决策 │
└──────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 路由后的分发 (Dispatch) │
│ → Agent A │ → Agent B │ → Fallback │
└─────────────────────────────────────────────┘2.2 核心数据结构
from dataclasses import dataclass, field
from typing import List, Optional, Dict, Any
import numpy as np
@dataclass
class RouteConfig:
"""单条路由配置"""
name: str # 路由名称（唯一标识）
description: str # 路由描述
samples: List[str] = field(default_factory=list) # 样本语句（用于构建向量）
embedding: Optional[np.ndarray] = None # 语义向量（由样本计算得到）
threshold: float = 0.65 # 路由匹配阈值（低于此值不匹配）
metadata: Dict[str, Any] = field(default_factory=dict) # 额外元数据
@dataclass
class RouteResult:
"""路由决策结果"""
route_name: str # 匹配到的路由名称
confidence: float # 置信度（0.0 ~ 1.0）
config: RouteConfig # 路由配置引用
method: str = "semantic" # 匹配方式：semantic / keyword / fallback
@dataclass
class RoutingDecision:
"""完整路由决策"""
query: str # 原始查询
query_vector: np.ndarray # 查询向量
results: List[RouteResult] # 所有匹配结果（按置信度排序）
best: Optional[RouteResult] # 最佳匹配
threshold: float # 使用的全局阈值
elapsed_ms: float = 0.0 # 路由耗时（毫秒）三、从零实现语义路由器
3.1 嵌入引擎（Embedding Engine）
嵌入引擎是整个系统的基石，负责将文本转化为语义向量。
import requests
import numpy as np
from typing import List, Optional
import json
class EmbeddingEngine:
"""
文本嵌入引擎
支持多种嵌入服务，通过策略模式切换
"""
def __init__(self,
provider: str = "openai",
model: str = "text-embedding-3-small",
api_key: Optional[str] = None,
api_base: Optional[str] = None,
dimensions: int = 384):
self.provider = provider
self.model = model
self.api_key = api_key
self.api_base = api_base
self.dimensions = dimensions
self._local_model = None
if provider == "local":
self._load_local_model()
def _load_local_model(self):
"""加载本地嵌入模型（仅 provider='local' 时）"""
try:
from sentence_transformers import SentenceTransformer
self._local_model = SentenceTransformer(self.model)
self.dimensions = self._local_model.get_sentence_embedding_dimension()
except ImportError:
raise ImportError(
"请安装 sentence-transformers: pip install sentence-transformers"
)
def encode(self, texts: List[str]) -> np.ndarray:
"""将文本列表编码为向量矩阵"""
if not texts:
return np.array([])
if self.provider == "local":
return self._encode_local(texts)
elif self.provider in ("openai", "siliconflow", "dashscope"):
return self._encode_api(texts)
else:
raise ValueError(f"不支持的嵌入服务: {self.provider}")
def _encode_local(self, texts: List[str]) -> np.ndarray:
"""使用本地模型编码"""
return self._local_model.encode(texts, normalize_embeddings=True)
def _encode_api(self, texts: List[str]) -> np.ndarray:
"""调用外部 API 编码"""
embeddings = []
for text in texts:
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {self.api_key}"
}
payload = {
"model": self.model,
"input": text,
"encoding_format": "float"
}
try:
resp = requests.post(
f"{self.api_base.rstrip('/')}/embeddings",
headers=headers,
json=payload,
timeout=30
)
resp.raise_for_status()
data = resp.json()
emb = data["data"][0]["embedding"]
# L2 归一化（余弦相似度用）
emb = np.array(emb, dtype=np.float32)
emb = emb / (np.linalg.norm(emb) + 1e-10)
embeddings.append(emb)
except Exception as e:
print(f"编码失败 [{text[:30]}...]: {e}")
# 失败时使用零向量
embeddings.append(np.zeros(self.dimensions, dtype=np.float32))
return np.array(embeddings)
def encode_query(self, text: str) -> np.ndarray:
"""编码单条查询"""
result = self.encode([text])
return result[0] if len(result) > 0 else np.zeros(self.dimensions)核心要点 ：
-
支持本地和云端两种嵌入模式
-
输出 L2 归一化向量，适配余弦相似度计算
-
编码失败时返回零向量（保证系统不崩溃）
-
维度一致性校验在外部进行
3.2 相似度计算引擎
from enum import Enum
import numpy as np
class SimilarityMethod(Enum):
"""相似度计算方法"""
COSINE = "cosine" # 余弦相似度
DOT_PRODUCT = "dot_product" # 点积（归一化后等价于余弦）
EUCLIDEAN = "euclidean" # 负欧氏距离
MANHATTAN = "manhattan" # 负曼哈顿距离
class SimilarityEngine:
"""相似度计算引擎"""
@staticmethod
def compute(query_vec: np.ndarray,
candidate_vecs: np.ndarray,
method: SimilarityMethod = SimilarityMethod.COSINE) -> np.ndarray:
"""
计算查询向量与候选向量集合的相似度
Args:
query_vec: 查询向量 (dim,) 或 (1, dim)
candidate_vecs: 候选向量矩阵 (n, dim)
method: 相似度计算方法
Returns:
相似度分数数组 (n,)
"""
query_vec = query_vec.reshape(1, -1)
if method == SimilarityMethod.COSINE:
return SimilarityEngine._cosine_similarity(query_vec, candidate_vecs)
elif method == SimilarityMethod.DOT_PRODUCT:
return SimilarityEngine._dot_product(query_vec, candidate_vecs)
elif method == SimilarityMethod.EUCLIDEAN:
return SimilarityEngine._euclidean_similarity(query_vec, candidate_vecs)
elif method == SimilarityMethod.MANHATTAN:
return SimilarityEngine._manhattan_similarity(query_vec, candidate_vecs)
else:
raise ValueError(f"不支持的相似度方法: {method}")
@staticmethod
def _cosine_similarity(a: np.ndarray, b: np.ndarray) -> np.ndarray:
"""余弦相似度：cos(θ) = (A·B) / (||A||·||B||)"""
a_norm = a / (np.linalg.norm(a, axis=1, keepdims=True) + 1e-10)
b_norm = b / (np.linalg.norm(b, axis=1, keepdims=True) + 1e-10)
return (a_norm @ b_norm.T).flatten()
@staticmethod
def _dot_product(a: np.ndarray, b: np.ndarray) -> np.ndarray:
"""点积相似度"""
return (a @ b.T).flatten()
@staticmethod
def _euclidean_similarity(a: np.ndarray, b: np.ndarray) -> np.ndarray:
"""负欧氏距离相似度（值越大越相似）"""
distances = np.sqrt(np.sum((b - a) ** 2, axis=1))
return 1.0 / (1.0 + distances) # 归一化到 (0, 1]
@staticmethod
def _manhattan_similarity(a: np.ndarray, b: np.ndarray) -> np.ndarray:
"""负曼哈顿距离相似度"""
distances = np.sum(np.abs(b - a), axis=1)
return 1.0 / (1.0 + distances)为什么选择余弦相似度？
在我们的实现中，编码器输出 L2 归一化向量，此时余弦相似度等价于点积。但为了通用性，我们保留多种方法：
-
余弦相似度 ：最常用，对向量长度不敏感，适合语义匹配
-
点积 ：当向量已归一化时与余弦等价，计算略快
-
欧氏距离：对向量尺度敏感，适合某些特定场景
3.3 关键词兜底层
在语义匹配失败时，关键词匹配可以作为兜底策略：
import re
from typing import List, Dict, Optional
class KeywordMatcher:
"""关键词匹配器（作为语义路由的兜底层）"""
def __init__(self):
self._patterns: Dict[str, List[re.Pattern]] = {}
def add_route(self, route_name: str, keywords: List[str]):
"""
为路由添加关键词模式
Args:
route_name: 路由名称
keywords: 关键词列表（支持正则通配符 *）
"""
patterns = []
for keyword in keywords:
if '*' in keyword:
# 将通配符转换为正则
pattern_str = re.escape(keyword).replace(r'\*', '.*')
pattern = re.compile(pattern_str, re.IGNORECASE)
else:
pattern = re.compile(re.escape(keyword), re.IGNORECASE)
patterns.append(pattern)
self._patterns[route_name] = patterns
def match(self, query: str) -> Optional[str]:
"""
匹配查询
Returns:
匹配到的路由名称，未匹配则返回 None
"""
for route_name, patterns in self._patterns.items():
for pattern in patterns:
if pattern.search(query):
return route_name
return None
def match_with_score(self, query: str) -> Dict[str, float]:
"""
匹配并返回所有匹配的路由及分数
Returns:
{route_name: score} 分数为匹配到的关键词数量
"""
scores = {}
for route_name, patterns in self._patterns.items():
count = sum(1 for p in patterns if p.search(query))
if count > 0:
scores[route_name] = count
return scores3.4 多意图路由
在实际场景中，一个查询可能涉及多个意图。例如 "如何申请退款并查询订单状态" 应同时路由到售后服务 Agent 和订单查询 Agent：
class MultiIntentRouter:
"""多意图路由器"""
def __init__(self,
max_intents: int = 3,
min_confidence: float = 0.5):
self.max_intents = max_intents
self.min_confidence = min_confidence
def route(self,
query_vec: np.ndarray,
routes: Dict[str, RouteConfig],
method: SimilarityMethod = SimilarityMethod.COSINE) -> List[RouteResult]:
"""
多意图路由：返回所有超过阈值且满足 Top-K 的路由
Args:
query_vec: 查询向量
routes: 路由配置字典 {name: config}
method: 相似度方法
Returns:
排序后的路由结果列表
"""
results = []
engine = SimilarityEngine()
for name, config in routes.items():
if config.embedding is None:
continue
# 计算该路由的样本与查询的相似度
scores = engine.compute(query_vec, config.embedding, method)
# 取最高分
best_score = float(np.max(scores))
if best_score >= self.min_confidence:
results.append(RouteResult(
route_name=name,
confidence=best_score,
config=config,
method="semantic"
))
# 按置信度降序排列，取 Top-K
results.sort(key=lambda r: r.confidence, reverse=True)
return results[:self.max_intents]3.5 完整的 SemanticRouter
现在我们将以上组件整合成一个完整的语义路由器：
import time
from typing import List, Optional, Dict, Any
class SemanticRouter:
"""
语义路由器：综合嵌入、相似度计算、多意图匹配和关键词兜底
"""
def __init__(self,
embedding_engine: Optional[EmbeddingEngine] = None,
similarity_method: SimilarityMethod = SimilarityMethod.COSINE,
global_threshold: float = 0.65,
enable_multi_intent: bool = False,
max_intents: int = 3,
enable_keyword_fallback: bool = True):
"""
初始化语义路由器
Args:
embedding_engine: 嵌入引擎（None 则使用默认）
similarity_method: 相似度计算方法
global_threshold: 全局路由阈值
enable_multi_intent: 是否启用多意图路由
max_intents: 最大意图数量
enable_keyword_fallback: 是否启用关键词兜底
"""
self.embedding_engine = embedding_engine or EmbeddingEngine()
self.similarity_method = similarity_method
self.global_threshold = global_threshold
self.enable_multi_intent = enable_multi_intent
self.max_intents = max_intents
self.enable_keyword_fallback = enable_keyword_fallback
self._routes: Dict[str, RouteConfig] = {}
self._keyword_matcher = KeywordMatcher() if enable_keyword_fallback else None
self._multi_intent_router = (
MultiIntentRouter(max_intents=max_intents)
if enable_multi_intent else None
)
def add_route(self,
name: str,
samples: List[str],
description: str = "",
threshold: Optional[float] = None,
keywords: Optional[List[str]] = None,
metadata: Optional[Dict[str, Any]] = None):
"""
添加路由
Args:
name: 路由名称（唯一）
samples: 样本语句（至少 2-3 条，覆盖不同表达方式）
description: 路由描述
threshold: 该路由特有阈值（覆盖全局阈值）
keywords: 关键词列表（用于兜底匹配）
metadata: 额外元数据
"""
if name in self._routes:
raise ValueError(f"路由 '{name}' 已存在")
if len(samples) < 1:
raise ValueError(f"路由 '{name}' 至少需要 1 条样本")
# 编码样本为向量
embeddings = self.embedding_engine.encode(samples)
# 取所有样本向量的均值作为路由的语义中心
route_embedding = np.mean(embeddings, axis=0)
config = RouteConfig(
name=name,
description=description,
samples=samples,
embedding=route_embedding,
threshold=threshold or self.global_threshold,
metadata=metadata or {}
)
self._routes[name] = config
# 添加关键词兜底
if keywords and self._keyword_matcher:
self._keyword_matcher.add_route(name, keywords)
def route(self, query: str) -> RoutingDecision:
"""
执行路由决策
Args:
query: 用户查询
Returns:
RoutingDecision 包含完整的路由决策信息
"""
start_time = time.time()
# Step 1: 预处理
cleaned_query = self._preprocess(query)
# Step 2: 编码查询
query_vector = self.embedding_engine.encode_query(cleaned_query)
# Step 3: 计算相似度
engine = SimilarityEngine()
raw_results = []
for name, config in self._routes.items():
if config.embedding is None:
continue
score = float(engine.compute(
query_vector,
config.embedding.reshape(1, -1),
self.similarity_method
)[0])
threshold = config.threshold
method = "semantic"
if score >= threshold:
raw_results.append(RouteResult(
route_name=name,
confidence=score,
config=config,
method="semantic"
))
# Step 4: 排序
raw_results.sort(key=lambda r: r.confidence, reverse=True)
# Step 5: 多意图截断
if self.enable_multi_intent and self._multi_intent_router:
# 重新使用多意图路由器的阈值
filtered = [
r for r in raw_results
if r.confidence >= self._multi_intent_router.min_confidence
]
raw_results = filtered[:self.max_intents]
elif raw_results:
# 单意图模式只保留最佳
raw_results = [raw_results[0]]
# Step 6: 关键词兜底（如果语义匹配未满足阈值）
if not raw_results and self._keyword_matcher:
keyword_result = self._keyword_matcher.match(cleaned_query)
if keyword_result:
config = self._routes.get(keyword_result)
if config:
raw_results.append(RouteResult(
route_name=keyword_result,
confidence=0.5, # 关键词匹配固定置信度
config=config,
method="keyword"
))
# Step 7: 最终决策
best = raw_results[0] if raw_results else None
elapsed = (time.time() - start_time) * 1000
return RoutingDecision(
query=query,
query_vector=query_vector,
results=raw_results,
best=best,
threshold=self.global_threshold,
elapsed_ms=round(elapsed, 2)
)
def _preprocess(self, text: str) -> str:
"""预处理：清洗、标准化"""
text = text.strip()
# 合并多余空白
text = re.sub(r'\s+', ' ', text)
return text
def get_route(self, name: str) -> Optional[RouteConfig]:
"""获取路由配置"""
return self._routes.get(name)
def list_routes(self) -> List[str]:
"""列出所有路由名称"""
return list(self._routes.keys())
def remove_route(self, name: str):
"""删除路由"""
self._routes.pop(name, None)四、实战：构建智能客服路由系统
4.1 完整示例
# 初始化嵌入引擎（使用本地模型，零依赖外部 API）
embedder = EmbeddingEngine(
provider="local",
model="all-MiniLM-L6-v2" # 轻量级 384 维嵌入模型
)
# 初始化语义路由器
router = SemanticRouter(
embedding_engine=embedder,
similarity_method=SimilarityMethod.COSINE,
global_threshold=0.60,
enable_multi_intent=True,
max_intents=3,
enable_keyword_fallback=True
)
# 注册路由 --- 每种意图提供 3-5 条样本覆盖不同表达
router.add_route(
name="order_query",
description="查询订单状态、物流信息",
samples=[
"我的订单到哪里了",
"查一下快递物流状态",
"订单号 12345 现在什么进度",
"我买的商品发货了吗",
"帮我查一下配送进度"
],
keywords=["订单", "物流", "快递", "配送", "发货", "运单"],
threshold=0.65
)
router.add_route(
name="after_sales",
description="售后问题，退款退货",
samples=[
"我想申请退款",
"这个商品有问题要退货",
"怎么办理售后",
"我要投诉产品质量",
"收到的商品有瑕疵"
],
keywords=["退款", "退货", "售后", "投诉", "赔偿", "换货"],
threshold=0.60
)
router.add_route(
name="price_inquiry",
description="价格咨询、优惠活动",
samples=[
"这个多少钱",
"有优惠券吗",
"现在有什么打折活动",
"价格还能便宜吗",
"满减活动怎么参加"
],
keywords=["价格", "多少钱", "优惠", "折扣", "满减", "优惠券"],
threshold=0.65
)
router.add_route(
name="technical_support",
description="技术问题、故障报修",
samples=[
"我登录不上账号",
"网站打不开怎么办",
"系统提示错误代码 500",
"APP 闪退了",
"我的账户被锁定了解锁"
],
keywords=["故障", "报错", "错误", "打不开", "闪退", "登录不上"],
threshold=0.55 # 技术问题表达多样，降低阈值
)4.2 路由测试
# 测试各种查询
test_queries = [
"我的包裹什么时候到",
"这东西我要退掉，质量太差了",
"有没有优惠券可以领",
"手机 APP 一直闪退怎么办",
"你好",
"查订单 物流 还有优惠",
"退款流程怎么走？我要把昨天买的退掉",
]
for query in test_queries:
decision = router.route(query)
print(f"\n📝 查询: {query}")
if decision.best:
print(f" ✅ 路由到: {decision.best.route_name}")
print(f" 📊 置信度: {decision.best.confidence:.4f}")
print(f" 🔍 匹配方式: {decision.best.method}")
if decision.enable_multi_intent and len(decision.results) > 1:
print(f" 📌 备选路由:")
for r in decision.results[1:]:
print(f" - {r.route_name} ({r.confidence:.4f})")
else:
print(f" ❌ 未匹配任何路由 → 走 Fallback")
print(f" ⏱️ 耗时: {decision.elapsed_ms}ms")预期输出示例：
📝 查询: 我的包裹什么时候到
✅ 路由到: order_query
📊 置信度: 0.8923
🔍 匹配方式: semantic
⏱️ 耗时: 15.32ms
📝 查询: 这东西我要退掉，质量太差了
✅ 路由到: after_sales
📊 置信度: 0.8741
🔍 匹配方式: semantic
⏱️ 耗时: 12.87ms
📝 查询: 查订单 物流 还有优惠
✅ 路由到: order_query
📊 置信度: 0.7612
🔍 匹配方式: semantic
📌 备选路由:
- price_inquiry (0.6543)
⏱️ 耗时: 14.01ms
📝 查询: 你好
❌ 未匹配任何路由 → 走 Fallback
⏱️ 耗时: 10.45ms4.3 集成到智能客服系统
class AICustomerService:
"""集成语义路由的智能客服系统"""
def __init__(self, router: SemanticRouter):
self.router = router
# 路由 → Agent 映射
self._handlers = {
"order_query": self._handle_order_query,
"after_sales": self._handle_after_sales,
"price_inquiry": self._handle_price_inquiry,
"technical_support": self._handle_technical_support,
}
def handle(self, query: str) -> str:
"""处理用户查询"""
decision = self.router.route(query)
if decision.best and decision.best.route_name in self._handlers:
handler = self._handlers[decision.best.route_name]
return handler(query, decision)
else:
return self._handle_fallback(query)
def _handle_order_query(self, query: str, decision) -> str:
llm_prompt = f"""
你是一个订单查询助手。用户查询：
{query}
请：
1. 询问订单号（如果用户未提供）
2. 查询物流状态
3. 提供预计送达时间
回复简洁友好。
"""
return self._call_llm(llm_prompt)
def _handle_after_sales(self, query: str, decision) -> str:
llm_prompt = f"""
你是一个售后服务助手。用户查询：
{query}
请：
1. 确认用户的问题类型（退货/换货/退款/投诉）
2. 引导用户提供订单号和原因
3. 说明售后流程和时间
回复耐心理智。
"""
return self._call_llm(llm_prompt)
def _handle_fallback(self, query: str) -> str:
return f"您好！我是 AI 客服助手。请问您需要什么帮助？" \
f"我可以帮您查询订单、处理售后或解答价格问题。"
def _call_llm(self, prompt: str) -> str:
"""调用大模型生成回复（简化示例）"""
# 实际集成 LLM API
return f"[LLM Response for: {prompt[:50]}...]"五、进阶优化
5.1 动态阈值调整
静态阈值无法适应所有场景，我们可以实现动态阈值：
class AdaptiveThresholdRouter(SemanticRouter):
"""带自适应阈值的语义路由器"""
def __init__(self,
base_threshold: float = 0.60,
adaptation_rate: float = 0.05,
min_threshold: float = 0.40,
max_threshold: float = 0.90,
history_size: int = 100,
**kwargs):
super().__init__(global_threshold=base_threshold, **kwargs)
self.base_threshold = base_threshold
self.adaptation_rate = adaptation_rate
self.min_threshold = min_threshold
self.max_threshold = max_threshold
self.history_size = history_size
self._history: List[Dict] = []
def record_feedback(self, query: str, route_name: str, correct: bool):
"""
记录用户反馈，用于动态调整阈值
Args:
query: 原始查询
route_name: 路由名称
correct: 路由是否正确
"""
self._history.append({
"query": query,
"route": route_name,
"correct": correct,
"timestamp": time.time()
})
# 保持历史记录大小
if len(self._history) > self.history_size:
self._history.pop(0)
# 动态调整阈值
self._adapt_threshold()
def _adapt_threshold(self):
"""根据近期反馈调整全局阈值"""
if len(self._history) < 10:
return
recent = self._history[-20:]
accuracy = sum(1 for h in recent if h["correct"]) / len(recent)
if accuracy < 0.7:
# 准确率低 → 可能是阈值太高漏掉了正确路由
self.global_threshold = max(
self.min_threshold,
self.global_threshold - self.adaptation_rate
)
elif accuracy > 0.95:
# 准确率太高 → 可能阈值过低混入了错误路由
self.global_threshold = min(
self.max_threshold,
self.global_threshold + self.adaptation_rate * 0.5
)
def get_threshold_stats(self) -> Dict:
"""获取调整统计"""
return {
"current_threshold": self.global_threshold,
"adaptations_count": ...,
"recent_accuracy": ...
}5.2 路由缓存
对于重复查询，缓存可以大幅提升性能：
from collections import OrderedDict
import hashlib
class CachedSemanticRouter(SemanticRouter):
"""带 LRU 缓存的语义路由器"""
def __init__(self, cache_size: int = 1000, **kwargs):
super().__init__(**kwargs)
self.cache_size = cache_size
self._cache: OrderedDict[str, RoutingDecision] = OrderedDict()
def route(self, query: str) -> RoutingDecision:
# 生成缓存键（归一化后哈希）
cache_key = self._get_cache_key(query)
if cache_key in self._cache:
# 缓存命中，移到最近使用
self._cache.move_to_end(cache_key)
return self._cache[cache_key]
# 正常路由
decision = super().route(query)
# 写缓存
self._cache[cache_key] = decision
if len(self._cache) > self.cache_size:
self._cache.popitem(last=False)
return decision
def _get_cache_key(self, query: str) -> str:
"""生成缓存键"""
normalized = query.strip().lower()
return hashlib.md5(normalized.encode()).hexdigest()
def get_cache_stats(self) -> Dict:
return {
"cache_size": len(self._cache),
"max_size": self.cache_size,
}5.3 路由回退链
当某个 Agent 处理失败时，需要自动回退到备选路由：
class FallbackChainRouter(SemanticRouter):
"""带回退链的语义路由器"""
def __init__(self, **kwargs):
super().__init__(enable_multi_intent=True, **kwargs)
# 路由回退链定义：order_query → after_sales → fallback
self._fallback_chains: Dict[str, List[str]] = {}
def set_fallback_chain(self, route_name: str, chain: List[str]):
"""
设置回退链
Args:
route_name: 主路由名称
chain: 回退路由列表（按优先级）
"""
self._fallback_chains[route_name] = chain
def route_with_fallback(self, query: str,
handler: callable) -> tuple:
"""
执行带回退链的路由
Returns:
(final_route_name, handler_result)
"""
decision = self.route(query)
if not decision.best:
return ("fallback", None)
primary_route = decision.best.route_name
chain = [primary_route] + \
self._fallback_chains.get(primary_route, [])
for route_name in chain:
if route_name not in self._routes:
continue
try:
result = handler(route_name, decision)
if result is not None:
return (route_name, result)
except Exception:
continue
return ("fallback", None)六、性能与准确率
6.1 嵌入模型选择对比
| 模型 | 维度 | 相对速度 | MTEB 得分 | 适用场景 |
|---|---|---|---|---|
all-MiniLM-L6-v2 |
384 | 最快 | 58.80 | 实时路由、低延迟 |
all-mpnet-base-v2 |
768 | 中等 | 61.14 | 平衡场景 |
text-embedding-3-small |
512 | API 调用 | 62.30 | 云端部署 |
text-embedding-3-large |
3072 | API 调用 | 64.59 | 高精度路由 |
推荐 ：all-MiniLM-L6-v2 在速度和精度之间取得最佳平衡，适合生产环境的实时路由场景。
6.2 样本数量与路由质量
# 样本覆盖实验
def experiment_sample_coverage(router, test_cases: List[tuple]):
"""
实验：不同样本数量对路由准确率的影响
test_cases: [(query, expected_route), ...]
"""
results = {}
for n_samples in [1, 2, 3, 5, 10, 20]:
correct = 0
for query, expected in test_cases:
decision = router.route(query)
if decision.best and decision.best.route_name == expected:
correct += 1
accuracy = correct / len(test_cases)
results[n_samples] = accuracy
print(f"样本数 {n_samples:2d} → 准确率 {accuracy:.1%}")
return results经验结论：
-
1 条样本 ：60-70% 准确率（够用，但不稳定）
-
3 条样本 ：80-85% 准确率（推荐的基线配置）
-
5 条样本 ：87-92% 准确率（大多数场景的甜蜜点）
-
10+ 条样本：93-96% 准确率（收益递减）
6.3 延迟基准
| 嵌入方式 | 单次路由延迟 | 内存消耗 |
|---|---|---|
| 本地模型 (MiniLM) | 5-15ms | ~500MB |
| 本地模型 (mpnet) | 15-30ms | ~1GB |
| OpenAI API | 100-500ms | ~0MB |
| 缓存命中 | <1ms | 取决于缓存大小 |
生产建议：使用本地嵌入模型 + LRU 缓存，可以做到 95% 以上的请求在 10ms 内完成路由。
七、生产部署注意事项
7.1 模型热更新
class HotReloadRouter(SemanticRouter):
"""支持热更新的语义路由器"""
def __init__(self, config_path: str, **kwargs):
super().__init__(**kwargs)
self.config_path = config_path
self._last_mtime = 0
def check_and_reload(self):
"""检查配置文件是否有更新"""
try:
mtime = os.path.getmtime(self.config_path)
if mtime > self._last_mtime:
self._load_from_config()
self._last_mtime = mtime
print(f"[{datetime.now()}] 路由配置已热更新")
except Exception as e:
print(f"配置热更新失败: {e}")
def _load_from_config(self):
"""从 YAML/JSON 配置加载路由"""
import yaml
with open(self.config_path, 'r') as f:
config = yaml.safe_load(f)
self._routes.clear()
for route_cfg in config.get('routes', []):
self.add_route(
name=route_cfg['name'],
samples=route_cfg['samples'],
description=route_cfg.get('description', ''),
threshold=route_cfg.get('threshold'),
keywords=route_cfg.get('keywords'),
metadata=route_cfg.get('metadata', {})
)配置文件示例（routes.yaml）：
routes:
- name: order_query
description: 订单查询
threshold: 0.65
samples:
- "我的订单到哪里了"
- "查一下快递物流状态"
keywords:
- "订单"
- "物流"
- name: after_sales
description: 售后服务
threshold: 0.60
samples:
- "我想申请退款"
- "要退货"
keywords:
- "退款"
- "退货"7.2 监控与告警
class MonitoredRouter(SemanticRouter):
"""带监控的语义路由器"""
def route(self, query: str) -> RoutingDecision:
decision = super().route(query)
# 记录指标
self._record_metrics(decision)
# 低置信度告警
if decision.best and decision.best.confidence < 0.50:
logger.warning(
f"低置信度路由: query={query[:50]}... "
f"route={decision.best.route_name} "
f"conf={decision.best.confidence:.3f}"
)
return decision
def _record_metrics(self, decision: RoutingDecision):
"""记录 Prometheus 指标"""
# 路由延迟
# histogram_observe('semantic_router_latency_ms', decision.elapsed_ms)
# 路由分布计数
route_name = decision.best.route_name if decision.best else "fallback"
# counter_inc('semantic_router_requests_total', {'route': route_name})
# 未路由次数
if not decision.best:
# counter_inc('semantic_router_unrouted_total')
pass7.3 配置文件模板
完整的生产配置（config.yaml）：
semantic_router:
global_threshold: 0.60
similarity_method: cosine
enable_multi_intent: true
max_intents: 3
enable_keyword_fallback: true
embedding:
provider: local
model: all-MiniLM-L6-v2
dimensions: 384
cache:
enabled: true
max_size: 5000
ttl_seconds: 3600
monitoring:
enabled: true
low_confidence_threshold: 0.40
log_unrouted: true
hot_reload:
enabled: true
config_path: "/etc/semantic-router/routes.yaml"
check_interval_seconds: 60八、总结
本文从零实现了完整的语义路由系统，核心要点：
- 架构清晰：嵌入引擎 → 相似度计算 → 多意图路由 → 关键词兜底 → 缓存加速
- 灵活扩展：支持本地/云端嵌入、多种相似度方法、动态阈值调整、热更新
- 生产就绪：LRU 缓存、回退链、监控告警完整集成
- 性能出色：本地 MiniLM + 缓存，10ms 内完成路由决策
语义路由将传统关键词匹配的"刚性"系统升级为"柔性"智能分发系统，是构建 AI Agent 网关的核心基础设施。基于本文的实现，你可以轻松构建自己的智能请求分发引擎。
📚 延伸阅读
如果你对 DeepSeek 的实战用法感兴趣，推荐阅读我的另一篇文章：
👉 DeepSeek 实战指南：提示词工程、API 集成与效率提升全攻略
这篇文章系统地拆解了 DeepSeek 的提示词工程技巧、API 封装方法以及日常效率提升场景，全文代码可直接运行，适合已经上手 DeepSeek 但希望更高效使用的开发者。
本文是"手写 AI 系统"系列文章之一。该系列从零实现 AI 系统中的关键组件，涵盖 RAG、Agent、Function Calling、MCP 等核心技术，帮助你深入理解底层原理，构建属于自己的 AI 工具。