企业官网建设流程全解析

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

Semantic Router（vLLM-SR）是一个开放、可编程的模型与算力决策层：它让 Agent Harness 通过稳定的公开模型入口发起调用，由可读、可测的路由策略在异构模型池中选出合格路径，甚至协调有界的多模型执行。本文基于官方「为何需要语义路由」设计文档展开，完整梳理它要解决的五个问题、五项设计目标与「信号 → 投影 → 决策 → 算法 → 模型池」的路由流水线，并结合仓库配置与源码说明「先划硬边界、再做优化」的落地方式。读完你将领会 Agent 场景下模型选择与 harness 解耦的关键架构思路，以及如何用入口、配方、信号、决策等具名对象组织自己的路由策略。

为什么需要语义路由：把模型选择从 harness 代码里拿出来

Agent Harness 的任务循环、工具执行与持久任务状态都在快速演进，但每次推理调用面对的后端世界却充满差异：模型在推理能力、延迟、价格、语言、上下文长度、模态、工具支持、位置和安全性上各不相同，而模型服务的可用性还会随着升级、扩缩容与故障实时变化。

如果每个 harness 集成里都硬编码模型选择逻辑，那么任何一次模型池调整都会牵动所有客户端。Semantic Router 的答案是：通过策略选择模型，而不是在集成中硬编码。共享的路由策略让 harness 在任务中自适应这些差异，无需在每个集成里重复实现模型选择逻辑——这是整个项目的第一原则，也是 goals.md 开篇的核心主张。

它要解决的五个问题

1. 模型选择与 harness 耦合

Harness 的任务循环与工具在不断演进，因此它需要一个稳定的模型契约。公开模型入口的价值在于：路由策略和物理模型池可以独立于每个 harness 的集成而变更——harness 永远请求同一个公开模型名，背后是哪个物理模型、哪条策略路径由 Router 决定。从源码结构看，这一契约由 pkg/routing/engine.go 中的Engine接口承载：它面向所有网关模式提供与传输无关的路由核心，Plan负责解析入口与配方、执行信号与决策，Respond负责在响应侧运行插件。

2. 约束和偏好被混在一起

不是所有要求都是可优化的目标：

• 不可妥协的硬约束：授权、隐私、数据驻留、模态、上下文容量、工具兼容性；
• 需要优化的目标：质量、延迟、成本。

一个有用的路由器必须先剔除无效路径，再只对剩余候选排序。这个顺序在配置层面体现为决策（decision）先做资格判定，算法（algorithm）再做选择（见下文「路由流水线」）。

3. 一条路由规则不够用

不同检测手段各有盲区：

• 关键词能表达硬策略，但无法覆盖所有语义意图；
• 分类器能识别意图，但不应覆盖授权边界；
• 运行时指标能选出健康副本，却不理解任务。

Semantic Router 把这些职责分开成具名对象，再组合成一次决策。仓库中 config/fragments 目录即为此而设：signal/下维护 30 个信号片段（keyword、classifier、domain、embedding、jailbreak、pii、safety、user-feedback 等），decision/下是可组合的决策片段，algorithm/下是选择与编排算法片段，plugin/下是路由行为片段。

4. 物理池是动态的

路由既是语义问题，也是系统问题：

• 请求描述工作负载（意图、语言、复杂度、上下文、工具、模态、身份）；
• 模型池贡献容量、健康、延迟与放置。

Router 必须把这两种视角连起来，而不能让其中任何一种单独成为全部策略。这正对应 signal-driven-decisions.md 中「工作负载、Router 策略、模型池」三视角对照：工作负载说明需要什么，策略说明允许什么、偏好什么，模型池说明当前可用什么。把视角分开，系统才更容易变更与评估。

5. 有些答案需要协作

选一个模型往往就够了；另一些任务则受益于升级（escalation）、校验、并行意见或有界工作流。这些是不同的执行模式，应在路由策略中显式声明，而不是塞进 harness 的任务循环。外层任务循环与工具执行仍由 harness 负责，Router 只在策略边界内协调多次模型调用。

五项设计目标

vLLM Semantic Router 围绕五个目标设计：

1. 一个稳定 API，覆盖多个后端：Harness 使用公开入口（如vllm-sr/auto），运维人员在背后管理模型池；
2. 策略可读、可测：信号、投影、决策、算法和插件都是具名配置对象，而不是散落的条件分支；
3. 先划硬边界，再做优化：不合格路由先被剔除，质量、延迟、成本或负载才影响选择；
4. 模型选择与有界协作：一条路由可以在已配置的限制内选择一个模型、级联、比较或协调多个模型；
5. 运维反馈：回放、评估、指标和用户反馈支撑有意识的策略变更。

目标 3 的实现细节可以直接在源码中看到：pkg/decision/selection.go 的decisionResultLess排序逻辑把Tier 视为硬优先级边界（Tier不同直接按 tier 排序），catch-all 路由永远排在真实匹配之后，然后routing.strategy才在「策略排序」与「置信度排序」之间抉择——这正是「资格在前、优化在后」的代码级印证。

路由流水线：一次请求如何变成执行路径

需要路由的模型调用依次经过请求理解、策略和模型执行阶段，所选配方定义这些阶段。完整链路如下：

信号（Signals）：提取事实

信号给从请求、对话、身份或内容中检测到的事物命名。有些是确定性的（关键词、元数据谓词、上下文长度区间），另一些使用嵌入或分类器模型（语义意图、领域、复杂度、PII、越狱检测）。信号描述事实，不选择后端；同一信号可被同一配方内的多个决策复用。完整家族清单见 tutorials/signal/overview。

投影（Projections）：协调证据

投影把若干信号输出变成可复用结果：

• 分区（partitions）：在重叠匹配中选出一个连贯胜者；
• 分数（scores）：组合加权输入；
• 映射（mappings）：把分数转换成具名路由区间。

例如，领域证据形成互斥领域分区，复杂度、上下文与校验证据形成难度分数，多个决策随后可直接引用这些结果，不必重复组合逻辑。真实配置见 config/config.yaml 中projections段的support_intents分区、request_difficulty加权分数与request_band阈值映射。

决策（Decisions）：应用策略

决策用布尔规则组合信号和投影输出，其优先级与配方的策略决定哪条匹配路由胜出；匹配的决策提供候选模型、可选算法与路由局部插件。硬要求必须在这里写清楚：授权、仅本地处理、模态、上下文容量和工具兼容性，应在优化器比较成本或延迟之前就决定路由是否合格。

算法（Algorithms）：选择或协调模型

决策匹配后，其算法处理候选集：

• 选择算法按固定顺序、语义匹配、延迟、反馈或其他有界策略选出一个候选（如static、knn、svm、latency-aware等，见 config/fragments/algorithm/selection）；
• Looper 算法通过级联、评审组、多轮过程或工作流协调多次调用（见 config/fragments/algorithm/looper）。

当决策只有一个候选时，最简单的静态行为往往就是正确选择；编排应留给额外延迟与算力已有可度量价值的任务。

插件（Plugins）：应用路由特定行为

插件为所选路由附加行为，按插件不同可能在提供方请求之前、执行期间或处理响应时运行：请求参数变更、上下文压缩、检索、记忆、回放、响应缓存、响应控制等。检测与执行是两回事：例如 PII 信号只报告一次匹配，由决策与插件策略决定是拦截、改路、转换还是仅观察。config/fragments/plugin 维护了 20 个插件片段，包括header-mutation/tenant-routing、memory/session-memory、rag/milvus、response-cache/high-recall、router-replay/debug、shadow-dispatch/sampled、tool-selection/filter-request-tools等。

模型池：执行请求

提供方把逻辑模型名绑定到物理推理端点。池中可以包含本地 vLLM 或 Ollama 服务、Kubernetes 托管模型，或远程 OpenAI 兼容提供方。Semantic Router 选择模型路径；模型服务器或后端调度器执行它并拥有副本放置。模型选择与副本调度是两层独立职责：选择算法回答「哪个模型适合这项任务」，运行时副本池则回答「该 deployment 的哪个就绪 worker 执行它」——后者属于推理平台。

完整请求生命周期

system 概览 把上述流水线展开为 8 步：

1. Harness 使用 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 发送请求；
2. Standalone 前端或 ExtProc 网关把请求交给 Router；
3. 请求的模型解析为入口及其配方；
4. Router 提取相关信号并计算投影；
5. 决策强制约束并选出合格候选集；
6. 路由的算法选择一个模型，或执行有界的多模型策略；
7. 路由插件在已配置的请求、执行或响应钩子处运行；
8. 上游客户端或外部网关把提供方形态的请求发送到所选后端，并返回规范化响应。

核心对象与配置模型

system 概览 给出了核心对象表：

这组对象的组合方式可以概括为一条解析链：请求模型名 -> 入口 -> 配方 -> 决策 -> 算法 -> 后端（见 虚拟模型文档）。检测可以跨策略复用，策略可以独立于模型选择而变更，物理池可以在稳定的公开入口背后演进。

仓库中的 Agent 路由配方 config/recipes/agent/config.yaml 展示了最简入口声明：

entrypoints: - model_names: ["vllm-sr/auto"] recipe: default

而 config/config.yaml 是完整的单文件示例：listeners定义 HTTP/HTTPS 监听器与 TLS、providers.models定义带pricing、reliability、backend_refs权重的物理模型，routing.signals定义关键词、embedding、domain、safety、jailbreak、pii、structure、complexity 等信号，projections定义分区与加权分数，decisions定义优先级、规则、modelRefs、candidateIterations、algorithm与plugins（shadow_dispatch、system_prompt、response_cache、context_compression、tools 等）。

先划硬边界，再做优化：资格与排序的分离

「先划硬边界，再做优化」不是一句口号，它在决策引擎的排序实现中非常具体。从 pkg/decision/selection.go 可以读出完整的优先级层次：

1. Tier 是硬优先级边界：不同 tier 的决策直接按 tier 排序，不参与跨层比较；
2. catch-all 永远排在真实匹配之后；
3. 同层内才按routing.strategy（如priority）结合决策priority排序；
4. 只有在置信度可比较（同类分数、同种度量）时，置信度才参与排序——分类器概率与向量相似度是不同量纲，不能直接比较，这一点在comparableConfidencePools中会被显式判定并记入 ranking trace。

换句话说：授权、本地性、模态、上下文、工具兼容性等硬约束先把不合格路径剔除，之后成本、延迟、质量或置信度才开始影响选择。这也解释了为什么文档强调「有些要求不可妥协……有用的路由器会先剔除无效路径，再只对剩余候选排序」。

模型选择与有界协作：单模型之外的执行模式

不是所有答案都来自单个模型。在策略中显式声明的协作模式包括：

• 升级（escalation）：低置信度或复杂请求升级到更强模型；
• 级联（cascade）：先跑快速阶段，只有接受条件不满足才继续；
• 评审组 / 并行意见（panel / fusion）：多个模型给出意见再综合；
• 有界工作流（bounded workflow）：在调用次数与 deadline 预算内协调多个模型。

Looper 算法家族（config/fragments/algorithm/looper）实现了置信度、融合、评审、remom 与工作流等模式，而 bench/looper_tts 提供了对应合约与证据完整性测试。关键约束是「在已配置的限制内」：每次额外调用都必须有可度量的价值，编排不能无限蔓延；外层任务循环与工具执行始终留在 harness 一侧。

运维反馈：策略变更要有证据

第五个设计目标是运维反馈，对应能力包括：

• 回放（replay）：router-replay插件记录路由结果，供审计与策略改进（见 config/fragments/plugin/router-replay/debug.yaml）；
• 评估：仓库 bench 目录提供 agent_crew、grounded_fusion、hallucination、reasoning、redteam、router_flow 等基准模块；配方还带probes.yaml探针，可在不调用推理后端的情况下验证路由与插件选择（见 config/recipes/README.md 与 配方一致性指南）；
• 指标：路由结果通过x-vsr-selected-recipe、x-vsr-selected-model等响应头与观测接口暴露（见 接入 Agent Harness 与 vsr-headers）；
• 用户反馈：user-feedback与reask信号把不满意、重复提问等事实喂给策略。

Semantic Router 不是什么

明确边界与明确能力同样重要：

• 它不是 Agent harness：任务编排、工具执行与持久任务状态由 harness 负责，Router 只为其中的模型调用提供决策；
• 它不是 Chat 后端：回答生成由 vLLM、Ollama 或托管提供方负责；内置模型运行时负责判断、分类、embedding 等任务；
• 它不只是负载均衡器：副本健康很重要，但请求含义与策略决定哪个模型池有资格；
• 它不是通用质量保证：路由质量取决于已配置的模型、信号、策略与评估数据；
• 它不替代网络、身份或数据治理控制：它在更广的安全架构内执行路由策略。

使用场景一瞥：同一套策略，四种环境

使用场景文档 将部署环境归纳为四类（它们并不互斥）：

跨环境还反复出现五类模式：能力路由（先剔除不满足模态/上下文/工具/语言的模型再比成本延迟）、专项路由（把代码、数学、研究、领域工作导向合适池）、基于目标的虚拟模型（暴露fast/accurate/balanced等稳定名称）、有界恢复与编排（仅在额外调用有可度量价值时升级或比较）、策略优先路由（先应用授权与能力约束，再排序优化）。

从理念到实践：快速上手路径

如果你想在真实 harness 中体验这套决策层，官方推荐路径是：

1. 阅读 接入 Agent Harness，把推理地址指向公开监听器（本地快速开始为http://localhost:8899），公开模型 ID 默认使用vllm-sr/auto；
2. 从仓库配方起步：先读 配方 Model Card，启动所需后端，再校验并运行：

vllm-sr config validate --config config/recipes/<name>/config.yaml vllm-sr serve --config config/recipes/<name>/config.yaml

3. 用最小请求验证路由并检查回执头：

curl -sS -i http://localhost:8899/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "vllm-sr/auto", "messages": [{"role": "user", "content": "Hello!"}] }'

关注响应中的x-vsr-selected-recipe与x-vsr-selected-model；HTTP 成功不代表输出有效或路由正确。运行真实任务前，请先为 harness 配置上下文窗口与输出上限预算（从配方可选的全体模型取最小值），并在变更生产策略前用探针验证代表性请求。

结语

Semantic Router 的定位一句话可以概括：把「选哪个模型」从每次集成的硬编码中拿出来，变成一份可读、可测、可演进的策略。五个设计目标——稳定 API、可读可测策略、先边界后优化、有界协作、运维反馈——层层支撑起这个定位；而「信号描述事实、决策划定资格、算法优化排序、插件施加行为、配方隔离状态」的流水线，则是它落地为代码的具体形态。对于正在构建或维护 Agent 系统的工程师，这套「公共入口 + 隔离配方 + 分层流水线」的架构模板，本身就是一个值得借鉴的模型选择方案。

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