vLLM Semantic Router: System Level Intelligent Router for Mixture-of-Models

framework vllm-project-semantic-router
semantic-routingmixture-of-modelsllm-routerai-gatewaykubernetesmcp
← Synthesis ← framework Survey Source ↗

vLLM Semantic Router — L2 蒸馏笔记 #

§1 TL;DR #

Signal-driven intelligent router for mixture-of-models, deployed as Envoy ExtProc gRPC sidecar. Uses a DecisionEngine that evaluates recursive boolean expression trees over 20+ signal types to route LLM requests across heterogeneous model fleets, balancing cost, privacy, safety, and capability. Kubernetes-native, MCP-compatible, with embedded ML inference via Rust/Candle FFI in the Go runtime.

§2 Q1 / Q2 / Q3 #

Q1 痛点 #

LLM 模型爆炸式增长，不同模型在能力、规模、成本、隐私边界上差异显著。生产环境需要同时使用多个模型（local / private / frontier），但缺乏系统级智能路由层来根据请求语义、安全性、用户权限等维度自动选择最优模型。现有方案要么只做简单负载均衡，要么只做意图分类——无法表达复杂的组合路由策略。

Q2 方法 #

Signal-Driven Decision Routing: 核心架构是一个 DecisionEngine，将路由决策建模为 20+ 种异构信号类型上的布尔表达式树（AND/OR/NOT）递归求值。

信号类型覆盖：keyword、embedding、domain、fact_check、user_feedback、reask、preference、language、context、structure、complexity、modality、authz、jailbreak、PII、KB、conversation、session_metric、event_context、projection。每个信号携带 confidence 分数。

决策选择支持三种策略：priority（按优先级）、confidence（按置信度）、tiered（分层后再按置信度排序）。

部署架构: 不是自建代理，而是作为 Envoy External Processing (ExtProc) gRPC filter 运行，可以无侵入地部署到任何 Envoy-based gateway（Istio、Gloo、standalone）。

ML 推理内嵌: 通过 candle-binding / ml-binding / nlp-binding 三层 Rust → Go FFI，将分类、嵌入等 ML 模型推理直接嵌入 Go 进程，避免外部模型服务的额外延迟。

核心技术壁垒: 20+ 异构信号类型 × 布尔表达式树组合决策。复制这一架构需要同时解决两个难题：(1) 每种信号类型都需要独立的 ML 模型或规则引擎进行提取（jailbreak detector、domain classifier、embedding model、PII filter 等），(2) 信号之间的组合逻辑需要可配置的表达式树求值器——而非硬编码 if-else。两者的耦合使得系统的 signal surface area 成为核心护城河。

Q3 结果 #

§3 架构 / 方法图 #

sequenceDiagram participant Client participant Envoy as Envoy Proxy participant ExtProc as Semantic Router
(ExtProc gRPC) participant Signals as Signal Extractors
(Candle/ONNX via FFI) participant Engine as DecisionEngine
(Bool Expr Tree) participant Models as Model Fleet
(Local/Private/Frontier) Client->>Envoy: HTTP request (OpenAI-compat) Envoy->>ExtProc: gRPC ext_proc request ExtProc->>Signals: Extract 20+ signal types Note over Signals: keyword, embedding, domain,
jailbreak, PII, complexity,
modality, authz, etc. Signals-->>ExtProc: SignalMatches + confidences ExtProc->>Engine: EvaluateDecisionsWithSignals() Engine->>Engine: evalNode() recursive
AND/OR/NOT tree walk Engine-->>ExtProc: DecisionResult {model, confidence} ExtProc-->>Envoy: Route to selected backend Envoy->>Models: Forward to chosen model Models-->>Envoy: Response Envoy-->>Client: Response

Kubernetes 控制面: Router 通过 controller-runtime watch CRD（RouterConfig），支持 hot-reload 配置变更。CRD 定义路由规则、决策树、模型选择策略。

数据面关键路径:

  1. Envoy 收到请求 → 调用 ExtProc gRPC → Router 提取信号
  2. 信号提取利用内嵌 ML 推理（Candle FFI / ONNX Runtime），避免网络往返
  3. DecisionEngine 对所有 configured decisions 执行布尔表达式树求值
  4. selectBestDecision 根据策略（priority / confidence / tiered）选出最优
  5. 返回路由指令给 Envoy，由 Envoy 完成实际转发

    6. 语言分工:

    • Go (45.6%) — 核心路由运行时、Envoy ExtProc server、K8s controller、决策引擎
    • Rust (11.2%) — Candle ML 推理引擎、tokenizer、embedding 计算（通过 FFI 暴露给 Go）
    • Python (17.7%) — CLI (vllm-sr)、SDK、模型训练（LoRA fine-tuning）
    • TypeScript (14.2%) — 监控 Dashboard (React)

    §4 作者证明 #

    无形式化作者证明 — 仅实证。

    本项目为工程系统（代码仓库），非学术论文，不包含显式的数学性能模型或定理证明。相关学术工作：

    文档内容状态
    Vision Paper (2026-03-24)Workload-Router-Pool Architecture已发布，未含于本 L1
    White Paper (2026-02-27)Signal Driven Decision Routing for MoM已发布，未含于本 L1
    When to Reason (2510.08731)语义路由决策时机Accepted
    Category-Aware Semantic Caching (2510.26835)异构 workload 缓存策略Published

    若需形式化模型，以下维度值得建模：

    • 信号提取延迟 vs. 决策准确度的 trade-off（更多信号 → 更准但更慢）
    • 表达式树深度与求值延迟的关系
    • 语义缓存命中率在不同 workload 分布下的期望值
    • 多模型 fleet 下 token cost 的优化目标函数

    §5 实验与数据 #

    本 L1 来源为代码仓库，不直接包含实验数据表格。可获取的实证信息如下。

    5.1 项目增长指标 #

    指标值时间段
    Stars4,200~8 months (Sep 2025 – May 2026)
    Forks682同期
    Commits1,399同期
    Open PRs75截至 2026-05
    Open Issues104截至 2026-05
    发布版本v0.1 Iris → v0.2 AthenaJan 2026 → Mar 2026

    5.2 工程验证基础设施 #

    仓库内含多层测试与验证工具：

    • bench/ — 路由性能基准测试套件
    • perf/ — 性能剖析工具
    • e2e/ — 端到端集成测试
    • src/fleet-sim/ — 异构模型 fleet 模拟器，用于在部署前测试路由策略
    • src/training/ — LoRA fine-tuning pipeline，用于训练 domain classifier 和 jailbreak detector

    5.3 支撑论文实验 #

    相关论文中的实验结果（未含于本 L1，但由项目直接产出）：

    • When to Reason (2510.08731): 评估何时需要调用 reasoning model vs. 普通 model 的路由决策准确率
    • Category-Aware Semantic Caching (2510.26835): 评估分类感知的语义缓存在异构 workload 下的命中率和延迟改善
    • HaluGate (blog 2025-12-15): Token-level 实时幻觉检测在生产 LLM 上的效果

    5.4 工作负载适用性分析 #

    工作负载场景适用程度原因
    多模型异构 fleet，请求语义多样强20+ 信号类型 + 布尔表达式树可精细路由
    单模型部署，纯负载均衡弱信号提取开销无法被路由优化抵消
    安全合规场景（jailbreak/PII 过滤）强内置 jailbreak、PII、hallucination 信号
    低延迟在线服务（<10ms routing overhead）中等Candle FFI 内嵌推理降低延迟，但多信号提取仍有开销
    Edge 部署（资源受限）中等架构支持，但 Envoy + Router 两进程的 footprint 较大

    §6 论证链 #

    #论证步骤证据 / 设计选择
    1模型爆炸 → 需要系统级路由README: "the number of models is exploding... choosing and connecting the right models is a system problem"
    2路由需要多维信号，不只是 intent classificationSignalMatches 定义了 20+ 种信号类型，远超典型路由器的 keyword/embedding 两类
    3复杂路由策略需要可组合的逻辑表达DecisionEngine 用 AND/OR/NOT 布尔表达式树递归求值，而非硬编码规则
    4信号提取需要 ML 推理 → 延迟敏感 → 需要内嵌推理通过 Rust Candle FFI 将 ML 推理嵌入 Go 进程，避免网络往返
    5部署不应侵入现有基础设施选择 Envoy ExtProc 而非自建代理，可无缝接入 Istio/Gloo/standalone Envoy
    6配置应是声明式、可热更新的Kubernetes CRD + controller-runtime watch，支持 hot-reload
    7安全是路由的一等公民，不是附加功能jailbreak、PII、hallucination 检测作为内置信号类型，参与决策树求值
    8路由策略需要在生产前可验证fleet-sim 模拟器用于离线测试路由策略

    §7 实现 cross-reference #

    7.1 核心决策引擎 #

    pkg/decision/engine.go — DecisionEngine 完整实现：

    • EvaluateDecisionsWithSignals() — 遍历所有 decisions，对每个执行布尔表达式树求值，收集匹配结果
    • evalNode() — 递归求值 RuleNode，支持 AND/OR/NOT 三种算子，叶节点调用 evalLeaf()
    • evalLeaf() — 对单个信号条件求值，通过 matchesSignalType() 分发到具体信号类型的查找逻辑
    • matchesSignalType() — 将 19 种信号类型映射到 SignalMatches 结构体的对应字段，domain 类型有特殊匹配逻辑（matchesDomainCondition）
    • selectBestDecision() — 根据 strategy (priority / confidence / tiered) 排序选出最优决策

    7.2 信号数据结构 #

    SignalMatches 结构体（pkg/decision/engine.go）定义了完整的信号词汇表：

    
KeywordRules, EmbeddingRules, DomainRules, FactCheckRules,
UserFeedbackRules, ReaskRules, PreferenceRules, LanguageRules,
ContextRules, StructureRules, ComplexityRules, ModalityRules,
AuthzRules, JailbreakRules, PIIRules, KBRules,
ConversationRules, SessionMetricRules, EventContextRules,
ProjectionRules + SignalConfidences map[string]float64

    7.3 系统入口 #

    cmd/main.go — 启动序列：

    1. parseRuntimeOptions() → 解析命令行参数
    2. loadRuntimeConfigOrFatal() → 加载 YAML 配置
    3. routerruntime.NewRegistry() → 初始化运行时组件注册表
    4. ensureModelsDownloadedOrFatal() → 下载 HuggingFace 模型
    5. initializeRuntimeDependencies() → 初始化 embedding runtime（Candle/ONNX FFI）
    6. newExtProcServerOrFatal() → 创建 Envoy ExtProc gRPC server
    7. warmupRouterRuntime() → 预热推理引擎
    8. startKubernetesControllerIfNeeded() → 启动 K8s CRD controller
    9. startExtProcServerOrFatal() → 监听 gRPC 请求

      10. 7.4 Kubernetes 控制面 #

      pkg/k8s/ — CRD controller 实现：

      • NewController(ControllerConfig{...}) — 创建 controller，接受 OnConfigUpdate 回调实现 hot-reload
      • Start(ctx) — 启动 watch & reconcile 循环

      7.5 关键依赖版本 #

      依赖版本用途
      envoyproxy/go-control-planev1.35.0Envoy ExtProc gRPC API
      mark3labs/mcp-gov0.42.0-beta.1MCP server 实现
      openai/openai-gov1.12.0OpenAI API 集成
      anthropics/anthropic-sdk-gov1.19.0Anthropic API 集成
      qdrant/go-clientv1.17.1Qdrant 向量存储
      milvus-io/milvus-sdk-gov2.4.2Milvus 向量存储
      controller-runtimev0.22.4K8s CRD reconciliation
      alecthomas/participlev2.1.4DSL 解析器

      7.6 关键实现细节 #

      1. 空 AND = 兜底路由: DecisionEngine 将空 AND 节点（无子条件）视为匹配但 confidence 为 0，用作 default/fallback 路由。这确保了总有一个决策被选中，同时保证有信号支持的决策始终优先。
        1. DSL 路由语言: 项目使用 participle 解析器实现了专用的路由 DSL（pkg/dsl/），允许运维人员用自定义语法编写路由规则，超越纯 YAML 配置的表达力。