---
sidebar_position: 1
description: vLLM Semantic Router 的研究导论，介绍这套基于 Envoy 的控制平面如何实现面向信号的 LLM 路由、策略执行与 token 效率优化。
translation:
  source_commit: "ab2aa160"
  source_file: "docs/intro.md"
  outdated: false
---

# vLLM Semantic Router

vLLM Semantic Router 是一个面向 **LLM 路由（LLMRouting）** 与 **Token 经济** 前沿问题的研究型项目。我们为 **混合模型（Mixture-of-Models, MoM）** 构建系统级能力：如何捕获合适信号、选择合适模型路径、执行合适策略，并为每次请求花费合适的 token 预算。

项目位于客户端与模型后端之间，以 Envoy External Processor（`ext_proc`）形式运行，将路由从零散的应用逻辑提升为**可观测、可配置**的多模型系统控制面。

## 研究关注点

我们借助本项目回答一组困难的系统问题：

1. **如何从请求、响应、用户与运行时上下文中捕获缺失的信号？**
2. **如何将这些信号组合成稳健的路由与策略决策？**
3. **多个模型如何作为系统协作，而非彼此孤立的后端？**
4. **如何在可落地的 token 经济中优化延迟、开销与工具使用？**
5. **如何在服务栈不碎片化的情况下加入安全、反馈与可观测性？**

## 核心系统

### 信号与投影路由

捕获 **14 类维护中的信号族**，并在路由选择前通过可复用的 **投影（projections）** 进行协调：

| 层级 | 组成部分 | 作用 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| **Signals（信号）** | `authz`、`context`、`keyword`、`language`、`structure`、`complexity`、`domain`、`embedding`、`modality`、`fact-check`、`jailbreak`、`pii`、`preference`、`user-feedback` | 提取可复用的请求、安全与偏好事实 |
| **Projections（投影）** | `partitions`、`scores`、`mappings` | 协调 competing 匹配并输出具名路由带 |
| **Decisions（决策）** | 对信号与投影做 AND/OR 策略规则 | 选择激活路由与模型候选 |

**工作方式**：从请求中提取信号，投影协调匹配证据，决策规则对结果事实求值，所选路由驱动插件与模型下发。

### 插件链架构

可扩展的请求/响应处理插件体系：

| 插件类型 | 说明 | 适用场景 |
| ------------------- | --------------------------------------------- | --------------------------------------------- |
| **semantic-cache** | 基于语义相似度的缓存 | 降低相似查询的延迟与成本 |
| **jailbreak** | 对抗性提示检测 | 拦截提示注入与越狱尝试 |
| **pii** | 个人可识别信息检测 | 保护敏感数据并满足合规 |
| **system_prompt** | 动态系统提示注入 | 按路由添加上下文相关指令 |
| **header_mutation** | HTTP 头修改 | 控制路由与后端行为 |
| **hallucination** | Token 级幻觉检测 | 生成过程中实时事实校验 |

**工作方式**：插件组成处理链，各插件可检查/修改请求与响应，且可按决策单独启用或关闭。

## 主要优势

### LLM 路由的控制面

- **策略替代硬编码分支**：将路由逻辑从应用代码迁出，进入可复用的信号、决策与配置。
- **按能力选择**：按任务形态、风险与质量要求路由，而不是把所有请求打到单一模型。

### 可实践的 Token 经济层

- **把预算花在刀刃上**：为真正需要的请求保留顶级模型、长上下文与工具调用。
- **在尽量不牺牲质量的前提下降本**：通过语义缓存、上下文感知路由与显式策略控制延迟与 token 消耗。

### 请求路径上的治理

- **内置安全与合规**：在与路由决策同一层应用越狱、PII、幻觉、提示与头控制。
- **决策可观测**：路由与策略结果可审计，团队能用数据调参而非凭感觉。

### 既能做研究也能交付

- **快速试验**：新增信号、算法与插件而无需重写服务路径。
- **与生产对齐**：实验、可观测与部署在同一套维护体系中衔接。

## 使用场景

- **多模型推理网关**：按能力、上下文与策略路由到专门模型。
- **成本敏感的 Copilot**：在内部助手与开发者工具中平衡质量、延迟与开销。
- **高安全助手**：在实时请求路径上强制执行 PII、越狱与幻觉控制。
- **研究平台**：评估路由策略、收集反馈信号并迭代模型协作策略。

## 从这里开始

- [**概览**](overview/goals)：项目目标、语义路由概念与集体智能。
- [**安装**](installation)：部署方式与配置。
- [**Fleet Simulator**](fleet-sim/overview)：GPU 机群规划、路由策略评估与指南 PDF。
- [**能力（Capacities）**](tutorials/signal/overview)：信号、投影、决策、插件、算法与全局控制。
- [**提案（Proposals）**](proposals/unified-config-contract-v0-3)：尚未并入稳定文档集的设计工作。

## 贡献

欢迎贡献！请参阅 [Contributing Guide](https://github.com/vllm-project/semantic-router/blob/main/CONTRIBUTING.md)。

## 许可

本项目采用 Apache 2.0 许可，详见 [LICENSE](https://github.com/vllm-project/semantic-router/blob/main/LICENSE)。
