semantic-router 单条件决策（single/）配置指南：用一个决定性信号驱动整条路由

• 后端
• API网关
• 模型推理服务
• AI Agent

本文以 semantic-router（开源可编程决策层）v0.3 版本中config/fragments/decision/single/目录及配套决策引擎源码为核心，讲解「单条件决策」这一最简路由形态的适用场景、YAML 配置语法与底层求值原理。读完你可以直接复制示例配置落地一条“单一权威信号 + 专属模型”的路由，并理解其与AND/OR/NOT/composite决策形态的边界与升级路径。

一、为什么需要单条件决策

semantic-router 的核心抽象是“信号（signal）与决策（decision）分离”：信号负责回答“路由器检测到了什么”，决策负责回答“路由器应该拿检测结果做什么”——匹配哪条路由、候选模型是哪些、是否启用 reasoning、路由命中后执行哪些插件。在 v0.3 中，决策统一放在配置的routing.decisions下，见 决策总览。

很多路由其实并不需要布尔树：一个领域信号足够权威、一个安全信号需要立即拦截、一个偏好信号决定专属模型。如果强行把它们装进更大的AND或OR结构，只会给简单策略增加噪音、让评审变得更难。**单条件决策（single condition decision）**就是为此设计的：它是决策形态目录中最小的形状，让一条路由只聚焦于一次决定性匹配。

它在 决策形态总表 中对应的表述是：

二、何时使用 single/

根据官方教程与仓库片段，满足以下任一场景即可选择single/：

• 一个领域信号具有权威性：例如业务问题就该走业务专属模型，领域分类器已经足够可靠；
• 一个安全信号需要立即拦截：例如检测到敏感内容应立刻走安全后端或拒绝响应；
• 一个偏好信号决定专属模型：例如偏好简洁回答的用户会话应命中专用模型。

它的优势也很明确：决策形状最小、易于阅读和审计、是引入更多布尔逻辑之前的最佳基线、能让一个强信号“拥有”一条路由而无需额外嵌套。

三、配置示例与字段精解

官方片段位于 config/fragments/decision/single/domain-business.yaml：

routing: decisions: - name: business_route description: Route business and management questions. priority: 110 rules: operator: AND conditions: - type: domain name: business modelRefs: - model: qwen2.5:3b use_reasoning: false

即使只有一个条件，也请保持路由命名且可复用：如果策略日后变复杂，可以直接升级为and/、or/或composite/形态，而无需改动周围配置布局。

3.1 字段级源码对照

从语义路由器的 CRD/配置类型定义 src/semantic-router/pkg/apis/vllm.ai/v1alpha1/types_route.go 可以看到每个字段的约束与默认值：

• name（必填）：决策的唯一标识，长度 1~100；
• priority（可选，默认 0，范围 0~1000）：决策优先级，数值越高越优先，在priority路由策略下参与排序。仓库示例中business_route取 110，低于安全类高优决策、高于一般兜底；
• description（可选，最长 500）：给人看的策略说明，务必写好，便于审计；
• rules.operator（必填，枚举AND/OR/NOT）：单条件场景下写AND（对单条件而言，AND与OR等价，取AND是官方约定的规范写法）；
• rules.on_unknown（可选，枚举no_match / match / fail_request）：当信号树求值结果未知时的兜底策略，详见下文第四节；
• rules.conditions（必填，1~50 项）：信号条件列表。每个条件由type（信号类型，枚举见类型定义：keyword/embedding/domain/fact_check/context/structure/conversation/event，实际更广）与name（引用该类型下已命名的具体信号）组成；
• modelRefs（必填，当前版本约束 1 项）：命中的候选模型。model必须在模型池中存在；use_reasoning默认false；可选loraName挂载 LoRA 适配器、reasoning_mode（enabled/disabled/adaptive）等。

第二个官方片段 config/fragments/decision/single/domain-computer-science.yaml 展示了更完整的形态——同一决策结构下把科学计算类请求路由到高推理模型，并挂载领域专家 LoRA：

routing: decisions: - name: computer-science-route description: Route computer science requests to the higher-reasoning model tier. priority: 100 rules: operator: AND conditions: - type: domain name: "computer science" modelRefs: - model: qwen3-32b use_reasoning: true lora_name: computer-science-expert

3.2 被引用的信号从哪来

conditions里的name必须引用真实存在的信号定义。以domain类型为例，领域信号在 config/fragments/signal/domain/mmlu.yaml 中定义：每个领域信号对应一组mmlu_categories（MMLU 学科类别）。该文件定义了biology / business / chemistry / computer science / economics / engineering / history / law / math / philosophy / physics / psychology / health / other等 14 个领域。因此：

• type: domain, name: business等价于“MMLU 领域分类器判定该请求属于 business 类目”；
• type: domain, name: "computer science"则匹配计算机科学类目。

同目录下还有keyword、jailbreak、pii、safety、preference、complexity、embedding等 30 余类信号（见 config/fragments/signal），单条件决策可以引用其中任意一类。例如偏好信号 config/fragments/signal/preference/power-user.yaml 定义terse_answers时提供了示例语句与threshold: 0.7阈值；安全信号 config/fragments/signal/safety/content-safety.yaml 则演示了“独立 sigmoid 头 + hazard 多标签”的安全检测信号如何直接挂到type: safety决策条件上。

3.3 真实参考配置

仓库的完整规范配置 config/config.yaml 中也有大量单条件决策实例。例如static_business_route（见 config/config.yaml 第 873 行附近）在单条件AND + domain(business)之上补充了tier、output_contract、annotations等生产级字段，并可配合candidateIterations做候选模型迭代；另一个decision_model_route（第 1609 行附近）则是单条件场景叠加on_unknown: no_match与algorithm.type: decision的参考写法。

四、底层求值原理：单条件如何被解析

单条件决策在运行时被编译为一棵规则树，由决策引擎求值。相关源码位于 src/semantic-router/pkg/decision/engine.go：

• AND节点通过evalAND实现（engine.go 第 671 行起）：只有每个子节点都匹配才返回 true，即“全部命中才算命中”，且会把命中子节点的置信度聚合参与路由排序；
• NOT是严格一元操作符：只接受一个子条件并取反（engine.go 第 816 行起），需要组合NOR/NAND时应把NOT嵌套在OR/AND外层；
• 空AND（零条件）会被当作 catch-all/默认路由，以零置信度兜底，不会压过有信号支撑的决策。

对单条件决策而言，整棵树退化为一个叶子：子条件命中即整条路由命中，子条件未命中即路由不命中——这就是“一个权威信号拥有整条路由”在实现层面的含义。

4.1 on_unknown：未知结果三态策略

当某个信号的证据缺失或不可用时，决策会落入“未知”状态。此时由rules.on_unknown决定行为，实现见 src/semantic-router/pkg/decision/engine_unknown.go：

这一字段尤其适合安全类单条件决策：对安全信号通常希望fail_request（检测不确定时宁可不放行），参考片段 config/fragments/signal/safety/content-safety.yaml 中的安全决策即显式写on_unknown: fail_request。

五、从 single/ 升级到更复杂的决策形态

单条件是整个决策形态目录的起点，官方目录（config/fragments/decision）为后续演进预留了清晰路径：

• and/：多个信号必须同时满足，例如 urgent-business.yaml 用AND同时要求domain(business)与keyword(urgent_keywords)，收窄到“紧急业务”这一高置信切片，减少误报；
• or/：多条等价信号共享同一路由，例如 business-or-law.yaml 让业务与法律两个领域共用同一模型策略，避免复制路由导致策略漂移；
• not/：显式排除，例如 exclude-jailbreak.yaml 用NOT jailbreak(prompt_injection)保证路由只在无注入信号时命中，适合安全闸门与高级路由准入；
• composite/：嵌套AND/OR/NOT，例如 priority-safe-escalation.yaml 同时编码“领域 + 紧急/复杂度升级 + 排除注入”的生产级策略。

升级时无需改动外围配置布局：只需把rules部分按目标形态改写，再相应调整priority与modelRefs即可。单条件形态本身也适合作为基线：先让一个权威信号跑通路由，再按真实流量表现逐步叠加条件。

六、验证与落地建议

• 片段可以直接并入规范配置的routing.decisions，或用vllm-sr config validate --config config.yaml校验后vllm-sr serve --config config.yaml启动（见 config/README.md）；
• 决策匹配与部署绑定（providers.models[]）、候选模型选择（decision.algorithm）、命中后处理（decision.plugins）是分离的：单条件决策只负责“路由命中与否”，多候选模型选择请叠加 algorithm 片段，命中后的后处理请叠加 plugin 片段；
• 工程建议：为每条单条件决策写清description，用有意义的name与稳定的priority数值段规划好优先级层级；对安全类信号显式设置on_unknown，避免未知信号悄悄落入默认路由。

• 后端
• API网关
• 模型推理服务
• AI Agent