Prompt 分类路由

相关问题： #313, #200

该提议引入了一个统一的内容扫描和路由框架，通过三个互补的信号源扩展了 vLLM Semantic Router：

1. 基于关键字的路由 - 确定性的、快速的、用于精确术语匹配的布尔逻辑 (Boolean Logic)。
2. Regex 内容扫描 - 基于模式的检测，用于安全、合规和结构化数据。
3. 嵌入相似度扫描 - 对改写具有鲁棒性的语义概念检测。

所有这三个信号都通过信号融合层 (Signal Fusion Layer)与现有的基于 BERT 的分类集成，在保持与当前架构向后兼容的同时，为用户提供强大、灵活的路由控制平面。

关键设计原则

• 互补而非替代：增强现有的 BERT 分类，而不是取代它。
• 双重执行路径：支持树内 (In-Tree)（低延迟）和通过 MCP 实现的树外 (Out-of-Tree)（高灵活性）模式。
• 策略驱动融合：允许用户使用布尔表达式、阈值和加权规则组合信号。
• 性能意识：为常见情况提供快速路径，同时支持复杂场景。
• 安全第一：ReDoS 防护、输入验证和全面的审计日志记录。

问题陈述与动机

当前局限性

vLLM Semantic Router 目前完全依赖 ModernBERT 分类进行语义类别检测。虽然功能强大，但这种方法有几个局限性：

来自 Issue #313：缺乏确定性路由

问题： 无法根据特定关键字或技术术语路由查询。

• 查询：“如何使用 RBAC 保护 Kubernetes 集群？”
• 当前：必须运行 ML 推理（~20-30ms）→ 分类为“计算机科学”→ 路由到通用模型。
• 期望：匹配关键字 ["kubernetes", "k8s", "RBAC"] → 直接路由到 [k8s-expert, devops-model]。

影响：

• 对于可以 1-2ms 内确定性路由的查询，产生了不必要的延迟（~20-30ms）。
• 路由精度较低（“计算机科学”类别过于宽泛）。
• 无法利用领域知识（例如，“CVE-”模式总是指向安全模型）。
• 复杂匹配缺乏布尔逻辑（例如，“Kubernetes AND 安全” vs “Kubernetes OR Docker”）。

缺乏类别之外的语义概念检测

问题： 无法检测查询中是否存在特定概念/主题。

• 无法基于“多步推理”概念检测进行路由。
• 无法检测特定领域的意图，如“情感分析”或“代码生成”。
• 嵌入相似度仅用于缓存，而不用于路由决策。

使用场景

场景 1：技术特定路由 (Issue #313)

场景： 企业 AI 网关路由到专门的基础设施模型。

# 期望配置
keyword_routing:
  rules:
    - name: "kubernetes-infrastructure"
      keywords: ["kubernetes", "k8s", "kubectl", "helm"]
      operator: "OR"
      models: ["k8s-expert", "devops-model"]
      priority: 100

优势：

• 确定性路由仅需 ~1-2ms，而 ML 推理需 ~20-30ms。
• 基于领域专业知识的精确模型选择。
• 易于更新和维护，无需 ML 重新训练。

场景 2：安全关键模式检测

场景： 防止数据泄露和合规违规。

regex_scanning:
  rules:
    - name: "ssn-detection"
      pattern: '\b\d{3}-\d{2}-\d{4}\b'
      action: "block"
      response: "Cannot process queries containing SSN patterns"
    
    - name: "cve-routing"
      pattern: 'CVE-\d{4}-\d{4,7}'
      action: "route"
      models: ["security-hardened-model"]

优势：

• 保证拦截 PII/敏感模式（无 ML 漏报）。
• 合规审计追踪。
• 亚毫秒级检测。

场景 3：语义意图检测

场景： 路由需要多步推理的查询。

embedding_similarity:
  concepts:
    - name: "multi-step-reasoning"
      keywords:
        - "step-by-step"
        - "break down the problem"
        - "analyze systematically"
      threshold: 0.75
      action: "boost_category"
      category: "reasoning"

优势：

• 对改写具有鲁棒性（“详细解释” → 类似于“逐步”）。
• 无需精确词匹配即可检测语义存在。
• 通过细粒度的意图检测补充 BERT 分类。

提议的解决方案架构

高层系统设计

Click to enlarge

组件分解

树内 (In-Tree) 信号提供者（低延迟路径）

树内路径提供了四个核心信号提供者，它们直接在路由进程内运行，以实现最小延迟：

A. 关键字匹配器 (Keyword Matcher)

关键字匹配器对查询中的精确术语或短语执行快速、确定性的匹配。

工作原理：

• 维护一个关键字规则集合，每个规则包含一个待匹配的术语列表。
• 扫描传入查询中是否存在这些关键字。
• 支持布尔运算符（AND/OR）以组合多个关键字。
• 可以是大小写敏感或大小写不敏感的。
• 返回匹配的规则及其关联的候选模型。

特性：

• 性能： 处理包含数百个关键字的数十条规则约为 ~1-2ms。
• 使用场景： 技术术语（Kubernetes, SQL）、产品名称、领域特定词汇。
• 复杂度： O(n×m)，其中 n=规则数，m=每条规则的关键字数。
• 局限性： 无模糊匹配，无正则表达式模式，仅限精确术语匹配。

示例用途： 将包含“Kubernetes”或“k8s”的查询路由到基础设施专家模型。

B. Regex 扫描器 (Regex Scanner)

Regex 扫描器使用正则表达式模式来检测查询中的结构化数据和特定模式。

工作原理：

• 启动时使用 RE2 引擎编译正则表达式模式（保证线性时间匹配）。
• 针对所有模式扫描查询内容。
• 每个模式可以指定一个动作（拦截、路由或记录）。
• 返回带有相关动作的匹配项。

特性：

• 性能： 处理数十个模式约为 ~2-5ms。
• 使用场景： PII 模式（SSN、信用卡）、CVE ID、电子邮件地址、结构化数据。
• 安全： RE2 引擎防止灾难性回溯（ReDoS 防护）。
• 局限性： 适用于少于 100 个模式；对于更大的规则集，请使用带有 Hyperscan 的 MCP。

示例用途： 检测并拦截社会安全号码，将 CVE ID 路由到安全模型。

C. 嵌入相似度扫描器 (Embedding Similarity Scanner)

嵌入相似度扫描器检测可能以不同方式表达的语义概念和意图。

工作原理：

• 复用路由中现有的 BERT 嵌入器。
• 启动时预先计算概念关键字的嵌入。
• 对传入查询进行一次嵌入。
• 计算查询嵌入与每个概念关键字嵌入之间的余弦相似度。
• 聚合相似度（均值、最大值或任何阈值）。
• 返回超过其配置相似度阈值的概念。

特性：

• 性能： ~5-10ms（一次性嵌入 + 快速余弦相似度）。
• 使用场景： 语义意图检测（多步推理、代码生成、情感分析）。
• 优势： 对改写和词选择变化具有鲁棒性。
• 局限性： 需要阈值校准；可解释性低于关键字/Regex。

示例用途： 检测“多步推理”请求，即使其表述为“详细解释”或“引导我完成”。

D. BERT 分类器（现有）

现有的基于 BERT 的分类器仍然是一个核心信号提供者，现在被视为与新扫描方法平等的同行。

工作原理：

• 使用 ModernBERT 模型将查询分类为语义类别。
• 返回类别名称和置信度分数。
• 类别映射到带有评分的模型池。

特性：

• 性能： ~20-30ms。
• 使用场景： 广泛的语义分类（计算机科学、推理、生物学等）。
• 优势： 成熟稳定，处理细微的语义理解。
• 角色： 既作为信号，也作为其他信号不匹配时的回退方案。

树外 (Out-of-Tree) 信号提供者（MCP 路径）

MCP（模型上下文协议）服务器作为独立的进程或服务运行，以适度增加延迟为代价提供灵活性和可扩展性。

A. MCP 关键字扫描器

外部关键字扫描服务，可以处理海量规则集和专门的匹配引擎。

能力：

• Aho-Corasick 算法：高效地同时搜索数千到数万个字面关键字。
• Hyperscan 引擎：使用编译好的模式数据库处理数万到数十万个复杂的 Regex 模式。
• 自定义匹配逻辑：领域特定算法（例如 SQL 注入检测、代码分析）。

优势：

• 无需重启路由即可热重载规则集。
• 扩展到海量模式数据库（100K+ 模式）。
• 将 CPU 密集型匹配卸载到专用服务。
• 独立的版本控制和生命周期管理。
• 对不同规则配置进行 A/B 测试。

权衡：

• 增加了网络延迟（本地主机/集群内部约为 ~2-5ms）。
• 额外的运维复杂度。
• 需要独立的部署和监控。

B. MCP 相似度评分器

具有可定制嵌入模型和高级功能的外部语义相似度服务。

能力：

• 自定义嵌入模型：领域微调的 SBERT、Embedding Gemma、多语言模型。
• GPU 批处理：批量处理多个请求以获得更高的吞吐量。
• 向量数据库集成：使用 Milvus、Qdrant 或其他向量数据库进行大规模概念搜索。
• 微调模型：部署专门为您的领域训练的模型。

优势：

• 自带嵌入模型。
• 领域特定微调以获得更好的准确性。
• 高级聚合策略。
• 多语言支持。
• 独立扩展嵌入推理。

权衡：

• 延迟高于树内（额外增加 ~10-20ms）。
• 需要 GPU 资源以获得最佳性能。
• 更复杂的部署架构。

信号融合层 (Signal Fusion Layer)

信号融合层是将所有信号（关键字、Regex、嵌入相似度和 BERT）组合成可执行路由决策的决策引擎。

工作原理：

1. 收集信号：收集所有活动信号提供者（树内和 MCP）的结果。
2. 评估策略规则：按优先级顺序（最高优先）处理规则。
3. 匹配条件：评估引用信号结果的布尔表达式。
4. 执行动作：执行第一个匹配规则的动作。
5. 返回决策：拦截、路由到特定模型、提升类别权重或回退到 BERT。

策略类型：

1. 拦截动作 (Block Actions)

• 立即拒绝违反安全或合规规则的请求。
• 示例：拦截所有包含 SSN 模式的查询。

2. 路由动作 (Route Actions)

• 根据信号匹配直接路由到特定的候选模型。
• 示例：将 Kubernetes 查询路由到 k8s-expert 模型。

3. 提升动作 (Boost Actions)

• 根据信号的存在对 BERT 类别应用权重乘数。
• 示例：检测到多步推理时，将“推理”类别的权重提升 1.5 倍。

4. 回退动作 (Fallthrough Actions)

• 当没有特定规则匹配时使用标准 BERT 分类。
• 作为默认的兜底方案。

策略评估：

• 基于优先级：规则从最高到最低优先级评估 (200 → 0)。
• 短路机制：第一个匹配的规则获胜，不再进行进一步评估。
• 布尔表达式：使用 AND、OR、NOT 组合多个信号条件。
• 灵活比较：支持数字阈值的 ==, !=, >, <, >=, <=。

表达式能力：

• 引用关键字匹配：keyword.<rule>.matched
• 检查相似度分数：similarity.<concept>.score > 0.75
• 使用 BERT 结果：bert.category == 'computer science'
• 组合信号：keyword.security.matched && bert.category == 'security'

配置架构

内容扫描框架通过几个相互关联的配置文件进行配置，这些文件定义了规则、模式、概念和策略。

顶层配置

主路由配置通过一个新的 content_scanning 部分进行扩展，该部分控制：

框架控制：

• 启用/禁用整个内容扫描系统。
• 无规则匹配时的默认动作（回退到 BERT 或拦截）。
• 审计日志开关。

树内 (In-Tree) 提供者：

• 关键字匹配： 启用/禁用，规则文件路径。
• Regex 扫描： 启用/禁用，模式文件路径，Regex 引擎选择（推荐 RE2）。
• 嵌入相似度： 启用/禁用，概念文件路径，默认相似度阈值。

MCP 提供者（可选）：

• 关键字扫描器： 端点 URL、身份验证、规则集版本 ID、超时。
• 相似度评分器： 端点 URL、身份验证、概念集版本 ID、超时。

融合策略：

• 融合策略文件路径。
• 默认动作行为。
• 审计日志配置。

关键字规则配置

关键字规则为确定性路由定义精确术语匹配：

每条规则：

• 名称： 规则的唯一标识符。
• 描述： 人类可读的解释。
• 关键字： 要匹配的术语列表（例如 "kubernetes", "k8s", "kubectl"）。
• 运算符： 布尔逻辑（OR = 任何关键字，AND = 所有关键字）。
• 大小写敏感性： 是否进行大小写敏感匹配。
• 候选模型： 匹配时路由到的模型列表。
• 优先级： 用于冲突解决的数字优先级（越高 = 越先评估）。

示例规则：

• Kubernetes 基础设施（OR 运算符，大小写不敏感）。
• 数据库操作（OR 运算符，大小写不敏感）。
• 安全关键术语（OR 运算符，对于 CVE ID 大小写敏感）。

Regex 模式配置

Regex 模式定义结构化数据检测和安全检查：

每个模式：

• 名称： 唯一标识符。
• 描述： 模式检测的内容。
• 模式： 正则表达式（RE2 语法）。
• 动作： 匹配时的操作（拦截、路由、记录）。
• 拦截消息： 动作为拦截时的错误消息。
• 候选模型： 动作为路由时路由到的模型。
• 优先级： 数字优先级（越高 = 越先评估）。

示例模式：

• SSN 检测（拦截动作，高优先级）。
• 信用卡检测（拦截动作，高优先级）。
• CVE ID 路由（对安全模型的路由动作）。
• 电子邮件检测（用于审计的记录动作）。

嵌入相似度概念配置

概念定义了可以以各种方式表达的语义意图：

每个概念：

• 名称： 唯一标识符。
• 描述： 此意图检测的内容。
• 关键字： 代表该概念的参考短语。
• 阈值： 匹配的最小相似度分数 (0.0-1.0)。
• 聚合方法： 如何组合关键字相似度（均值、最大值、任何）。
• 动作： 匹配时的操作 (boost_category, route)。
• 类别/模型： 目标提升类别或路由到的模型。
• 提升权重： 类别提升的乘数。

示例概念：

• 多步推理（均值聚合，将推理类别提升 1.5 倍）。
• 代码生成（最大值聚合，路由到代码模型）。
• 情感分析（均值聚合，路由到 NLP 专家）。

融合策略配置

融合策略将所有信号组合成路由决策：

策略结构：

• 规则按优先级顺序评估 (200 → 0)。
• 第一个匹配的规则获胜（短路评估）。

每条规则：

• 名称： 唯一标识符。
• 条件： 引用信号的布尔表达式。
• 动作： 决策类型 (block, route, boost_category, fallthrough)。
• 优先级： 数字优先级（200=安全，150=路由，100=提升，50=共识，0=默认）。
• 模型/类别： 路由或提升动作的目标。
• 消息： 动作为拦截时的拦截消息。

优先级级别：

• 200： 安全拦截（SSN、信用卡、PII）。
• 150： 高置信度路由覆盖（关键字 + Regex 匹配）。
• 100： 类别提升（嵌入相似度信号）。
• 50： 共识要求（多个信号必须一致）。
• 0： 默认回退到 BERT。

表达式语言：

• 引用信号：keyword.<rule>.matched, regex.<pattern>.matched, similarity.<concept>.score
• 布尔运算符：&& (AND), || (OR), ! (NOT)
• 比较：==, !=, >, <, >=, <=
• BERT 结果：bert.category, bert.confidence

与现有路由器的集成

请求处理流程

内容扫描框架无缝集成到现有路由器的请求处理流程中：

集成点： 请求处理器中的 handleModelRouting 函数。

处理步骤：

1. 检查内容扫描是否启用

   • 如果禁用，使用现有的仅 BERT 路由（向后兼容）。
   • 如果启用，继续进行信号收集。

2. 并行收集信号

   • 启动并发信号提供者（关键字、Regex、嵌入、BERT）。
   • 每个提供者独立运行以最小化延迟。
   • 调用 MCP 提供者时带有超时保护。
   • BERT 分类始终作为回退选项运行。

3. 评估融合策略

   • 将所有信号结果收集到一个统一的输入结构中。
   • 传递给信号融合层进行策略评估。
   • 策略引擎按优先级顺序处理规则。
   • 第一个匹配的规则决定动作。

4. 处理融合决策

   • 拦截决策： 立即返回 403 错误并附带说明。
   • 路由决策： 从候选列表中选择最佳模型。
   • 提升决策： 对 BERT 类别应用权重乘数，然后进行分类。
   • 回退决策： 使用标准 BERT 分类。

5. 继续正常流程

   • 选择的模型传递给端点选择。
   • 请求被修改，包含新的模型和路由标头。
   • 转发到适当的 vLLM 后端。

关键设计原则：

• 非阻塞并行执行，实现最小延迟。
• 组件失败时的优雅降级。
• 每一步的全面可观测性。
• 与现有路由逻辑向后兼容。

向后兼容性

保证： 现有部署无需更改即可继续工作。

• 默认行为： content_scanning.enabled: false → 使用现有的仅 BERT 路由。
• 选择性加入模式： 用户在配置中明确启用内容扫描。
• 回退策略： 如果没有扫描规则匹配，系统将回退到 BERT 分类。
• 配置验证： 无效的扫描配置在启动时会被拒绝，并显示清晰的错误消息。