Semantic Router — 本地智能体消息路由

使用三层评分架构将消息路由到多智能体系统中的正确智能体：

1. 1. 嵌入相似度（ChromaDB）— 语义理解
2. 关键词评分 — 精确领域匹配
3. 动作动词分层 — deploy始终→运维，secure→安全

为何存在

大多数智能体路由器要么：

• - 调用外部API（延迟高、成本高、隐私风险）
• 使用简单关键词匹配（不准确）
• 不支持法语/英语双语查询

本路由器完全本地运行，每次查询约1.5毫秒，准确率100%。

快速开始

1. 定义路由

创建路由配置文件（JSON或Python字典）：

python
ROUTES = {
ops: {
agent: orion,
descriptions: [
部署和管理基础设施及Docker容器,
安装、配置和重启服务,
DevOps运维、CI/CD、部署流水线,
],
keywords: [deploy, install, docker, compose, container, restart],
action_verbs: [déploie, installe, configure, redémarre],
},
security: {
agent: aegis,
descriptions: [
安全审计、漏洞扫描、加固,
防火墙规则、SSL证书、访问控制,
],
keywords: [security, firewall, ssl, vulnerability],
action_verbs: [sécurise, hardened],
},
# ... 添加更多路由
}

2. 初始化并路由

python
from semantic_router import SemanticRouter

router = SemanticRouter(routes_config=routes.json)
router.initialize() # 构建ChromaDB索引（冷启动约6秒，之后缓存）

result = router.route(在家庭实验室部署新的监控栈)

→ {route: ops, agent: orion, confidence: 0.94}

3. 在OpenClaw中使用

bash

启动API服务器

python3 scripts/router-api.py --port 8321

路由消息

curl -X POST http://localhost:8321/route \ -H Content-Type: application/json \ -d {message: 检查防火墙日志中的可疑活动}

架构

输入消息
│
├─► 法语标准化（口音处理、动词映射）
│
├─► 第一层：嵌入相似度（ChromaDB）
│ └─ 与路由描述进行余弦相似度计算
│
├─► 第二层：关键词评分
│ └─ 精确/子串匹配，避免关键词冲突
│
├─► 第三层：动作动词分层
│ └─ 运维动词 → 始终覆盖主题
│ └─ 主题动词 → 覆盖但限于特定路由
│ └─ 弱动词 → 让嵌入决定
│
└─► 加权融合 → 路由选择

评分公式

最终得分 = (0.4 × 质心相似度) + (0.3 × 最大示例相似度) + (0.3 × 关键词得分) + 动作提升

其中动作提升对匹配的动作动词进行加分，允许覆盖嵌入得分。

关键设计决策

1. 1. 无外部API — 全部通过ChromaDB + 默认嵌入本地运行
2. 关键词冲突预防 — 每个关键词仅出现在一个路由中
3. 动作检测前进行法语标准化 — 标准化口音，但在原始文本上检测动词
4. 磁盘缓存 — 嵌入持久化到/tmp/semanticroutercache/
5. 动作动词分层 — 从92.7%突破到100%的关键

API端点

端点	方法	描述
/route	POST	路由单条消息
/batch

POST | 路由多条消息 | | /benchmark | POST | 运行准确率基准测试 | | /stats | GET | 使用统计 | | /routes | GET | 列出已配置路由 | | /health | GET | 健康检查 |

性能

指标	数值
准确率（基准测试）	100%（41/41条消息）
查询延迟

约1.5毫秒（缓存后） | | 冷启动 | 约6秒（嵌入路由） | | 内存 | 约50MB | | ARM64兼容 | ✅（已在树莓派5上测试） |

使用场景

• - 多智能体编排 — 将用户消息路由到专业智能体
• 消息总线路由 — 智能体网格网络的前端负载均衡器
• 意图分类 — 分类支持工单、请求、命令
• 双语路由 — 原生支持法语/英语查询

文件结构

semantic-router/
├── SKILL.md ← 本文件
├── scripts/
│ ├── semantic_router.py ← 核心路由库
│ └── router-api.py ← REST API封装
└── references/
└── ROUTING-RESEARCH.md ← 设计笔记和基准测试

许可证

MIT — 自由使用，欢迎注明出处。