Semantic Router：让 AI 决策快 100 倍的路由层

图1：Semantic Router 项目 banner

开篇：LLM 的「选择困难症」怎么治？

想象你开了一家外卖客服中心。每当用户发来一条消息，客服都要把整段对话发给 GPT-4，等 GPT-4 回复「这条应该转给售后部门」——结果光是做这个判断就要花 10 秒钟、消耗大量 token。用户等得不耐烦，你也在烧钱。

这正是大多数 AI Agent 系统的真实困境：每一步决策都要调用昂贵的 LLM，延迟高、成本高、效率低。

Semantic Router（语义路由器）做的事情，就是给 LLM 装一个「前台接待员」。用户消息来了，先经过语义路由——基于向量空间匹配，在几毫秒内判断该走哪条路：是转人工、查订单、还是 AI 自主回答。只有真正需要理解推理的时候，才调用 LLM。

背景故事：来自 Aurelio AI 的技术积累

Semantic Router 由 Aurelio AI 团队开发和维护，这是一家专注于 LLM 应用基础设施的开源公司。项目最早于 2023 年底开源，迅速获得了开发者社区的关注。截至 2026 年初，该项目在 GitHub 上已获得超过 3500 颗星，吸引了全球数千名开发者使用和研究。

该项目由 Aurelio AI 团队内部生产环境验证后开源，代码质量较高，配有完整的文档、测试套件和持续集成流程。MIT 许可证也让它非常易于在商业项目中集成。

类比理解：像一个智能分类书架

你可以把 Semantic Router 理解成一个极度高效的分类书架管理员。

传统的 AI 决策流程，就像一个管理员每次拿到一本新书，都要通读全书才能决定把它放在哪一栏。Semantic Router 的方式则像：管理员在书架前快速「扫一眼」书的封面和关键词，就能精准归位——因为书架上的每一条路径（Route）都已经预先定义好了特征样本。

这就是所谓语义向量空间路由的直观原理：每条路径（Route）预先存入多条「示例话语」的向量；当新消息到来时，计算它与各路径向量的相似度，距离最近的即为匹配路径。整个过程不需要 LLM 生成回复，速度自然极快。

核心功能：静态路由 + 动态路由

静态路由（Static Routing）

最基础的用法。定义若干条固定路径，每条路径包含名称和示例话语：

from semantic_router import Route

politics = Route(
    name="politics",
    utterances=[
        "isn't politics the best thing ever",
        "why don't you tell me about your political opinions",
        "don't you just love the president",
    ]
)
chitchat = Route(
    name="chitchat",
    utterances=[
        "how's the weather today?",
        "how are things going?",
    ]
)

收到消息后，路由器根据向量相似度判断走哪条路径，适合话题分类、意图识别、多轮对话分流等场景。

动态路由（Dynamic Routing）

进阶用法。在路径中定义 function_schema，路由器不仅判断走哪条路，还能提取参数、自动触发函数调用。例如一个客服机器人，可以定义「查订单」路径，附带提取订单号的 schema，路由器自动解析消息中的订单号并触发查询逻辑。

from semantic_router import Route

order_lookup = Route(
    name="order_lookup",
    utterances=[
        "can you check my order status",
        "where is my package",
    ],
    function_schemas=[{
        "name": "get_order_status",
        "description": "Retrieve order status by order ID",
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"}
            }
        }
    }]
)

多模态路由

支持基于图像内容的路由（需安装 semantic-router[vision]）。可以识别图片内容后路由到相应处理路径，例如将产品图片路由到质检流程，将场景照片路由到不同 AI Agent。

技术架构：三层模块化设计

项目的代码结构清晰，分为三层：

1. 编码器层（Encoders）

负责将文本/图像转换为向量表示。目前支持 16 种编码器，覆盖主流 API 服务和本地模型：

类别	编码器
API 服务	OpenAI、Cohere、HuggingFace、Jina、Google、Mistral、NVIDIA NIM、Azure OpenAI、FastEmbed
本地模型	LlamaCpp（GGUF）、Transformers（sentence-transformers）、BM25（稀疏向量）、TF-IDF
多模态	CLIP（图像）、ViT（图像分类编码）

这意味着开发者可以在完全离线（使用本地编码器）和高性能 API 之间自由切换，无需修改业务逻辑。

2. 路由器层（Routers）

核心路由决策逻辑，三种实现：

• SemanticRouter：标准密集向量路由，基于余弦相似度匹配
• HybridRouter：混合路由，结合密集向量和稀疏向量（BM25/TF-IDF），提升准确率
• LinearRouter：轻量级线性路由，适合超低延迟场景

3. LLM 层（LLMs）

支持在路由成功后调用 LLM 执行具体任务（如生成回复、提取参数）。支持：OpenAI、Azure OpenAI、Cohere、Mistral、Ollama（本地）、LLamaCpp 等。

整体架构遵循依赖倒置原则，各层通过抽象基类交互，便于扩展新编码器或 LLM。

部署与上手

安装

基础安装仅需一行 pip 命令：

pip install semantic-router

本地离线版本（推荐中国大陆用户）：

pip install "semantic-router[local]"

这将安装 sentence-transformers 和 LlamaCpp，无需任何外部 API。

使用门槛

纯 Python 库，无 Web UI，需要在业务代码中集成。对于有 Python 开发能力的团队，上手非常容易；对于非技术用户，需要通过 LangChain、LlamaIndex 等中间件间接使用。

官方提供 9 个 Jupyter Notebook 教程（位于 docs/ 目录），涵盖从入门到高级用法（阈值优化、异步路由、多模态路由等），学习曲线平缓。

局限与挑战

1. 示例话语的质量直接影响路由准确率

Semantic Router 的本质是 KNN（K近邻）分类器，路由准确性高度依赖预定义的示例话语（utterances）是否足够丰富、是否准确代表目标类别的语义空间。如果某些话题的示例不足，路由可能会出错。

2. 不支持复杂推理的路由决策

语义路由适合「语义相似度匹配」场景，但对于需要多跳推理、上下文理解的复杂路由场景，仍然需要 LLM 的参与。Semantic Router 的定位是「加速简单决策」，而非「替代 LLM 推理」。

3. 本地模型性能受限

虽然支持本地编码器，但 sentence-transformers 在 CPU 上运行较慢，本地 LLM（如 LlamaCpp）也需要足够的内存支持。对于追求极致性能的场景，仍建议使用 API 编码器。

行业意义：LLM Agent 基础设施的重要拼图

Semantic Router 的出现，反映了 LLM Agent 架构中一个核心矛盾：决策速度 vs 决策质量。随着 Agent 系统变得越来越复杂，每一步都调用 LLM 是不现实的——成本和延迟都会成为瓶颈。

类似 Semantic Router 的路由层，正在成为 Agent 系统的标配基础设施。它与向量数据库（Pincone/Qdrant）、Agent 框架（LangChain/LlamaIndex）共同构成了现代 LLM 应用的技术栈。

从 GitHub Stars 增长曲线来看，该项目自 2024 年以来保持了稳定增长，说明市场对「AI 决策加速」的需求在持续扩大。随着更多 Agent 框架将语义路由作为内置功能，这一方向的技术价值将进一步凸显。