- 后端
- API网关
- 模型推理服务
- AI Agent
【免费下载链接】semantic-router
An open, programmable decision layer for models and compute.
模型选择（Model Selection）是 Semantic Router 在完成路由决策之后、真正把请求发送给某个 LLM 之前的关键一环：当一条决策命中了多个候选模型（modelRefs）时，由选择算法决定"这一次到底用哪个模型"。本文以 v0.1 版本文档《Choosing a Selection Algorithm》为核心骨架，结合当前仓库中src/semantic-router/pkg/selection/的实现源码与config/fragments/algorithm/selection/的真实配置片段，系统讲解 8 种选择算法的适用场景、默认参数与配置写法。读完本文，你将能够根据自身业务特征（是否需要确定性、是否有用户反馈、是否有模型描述、是否重视成本）快速选定算法，并写出可直接落地的最小配置。
快速决策树：30 秒确定算法方向
选型的第一步不是比较参数，而是回答四个递进的问题。以下是原文档给出的决策树，建议把每个节点的判断写进你的选型评审里：
Do you need deterministic routing? ├── Yes → Static Selection └── No → Continue... Do you have user feedback available? ├── Yes, abundant → Elo Rating ├── Some feedback → Hybrid (with Elo component) └── No feedback → Continue... Do you have good model descriptions? ├── Yes → RouterDC └── No → Continue... Is cost optimization important? ├── Yes → AutoMix └── No → Static or Hybrid简单记忆版（与 overview.md 中的建议一致）：
- 刚起步？→ 用
static（默认） - 有用户反馈？→ 用
elo - 有模型描述？→ 用
router_dc - 想优化成本？→ 用
automix - 全都想要？→ 用
hybrid
需要说明的是：v0.1 文档把算法分为核心算法（Core）与强化学习驱动算法（RL-Driven）两大类，共 8 种。当前仓库的选择器实现已经扩展到更多方法（如multi_factor、latency_aware、random，以及 ML 系列knn/kmeans/svm/mlp），本文以 v0.1 的 8 种为主线，其余方法在"算法全景"一节做补充介绍。
算法全景对比
核心算法
| 算法 | 是否需要反馈 | 部署复杂度 | 适应性 | 成本优化 |
|---|---|---|---|---|
| Static（静态） | 无 | 低 | 无 | 手动 |
| Elo（评分制） | 高 | 中 | 高 | 间接 |
| RouterDC（语义匹配） | 无 | 中 | 中 | 无 |
| AutoMix（级联混用） | 低 | 中 | 中 | 是 |
| Hybrid（加权融合） | 视情况 | 高 | 高 | 是 |
强化学习驱动算法
| 算法 | 是否需要反馈 | 部署复杂度 | 适应性 | 个性化 |
|---|---|---|---|---|
| Thompson Sampling | 中 | 低 | 高 | 可选按用户 |
| GMTRouter | 中 | 高 | 很高 | 内置 |
| Router-R1 | 无 | 高 | 高 | 通过 LLM 实现 |
从源码看算法家族的演进
从当前仓库的目录结构可以更直观地理解这套体系的组织方式：所有选择器的运行时实现集中在 src/semantic-router/pkg/selection，每个算法一个文件，例如：
static.go：静态选择elo.go：Elo 评分（含 elo.go#L30-L35 中DefaultEloRating = 1500、EloKFactor = 32两个默认常量）router_dc.go：语义相似度匹配automix.go：成本-质量权衡的级联选择hybrid.go：多信号加权融合rl_driven.go：Thompson Sampling 与 Router-R1 LLM 路由的统一实现gmtrouter.go：图神经网络个性化路由- 以及扩展方法：
multi_factor.go（质量/延迟/成本/负载加权或字典序比较）、latency_aware.go（TPOT/TTFT 百分位策略）、random.go、ml_adapter.go（KNN/KMeans/SVM/MLP）
选择器的创建入口在 factory.go#L163-L229 的Factory.Create()：根据配置中的method字符串走switch分支，为每种算法实例化对应选择器，并注入模型配置、分类目录、Embedding 函数等依赖。这也是理解"算法类型名（type: elo）与实现类一一对应"的最直接证据。
此外，pkg/modelselection/README.md 明确指出一个重要的行为约束：选择结果必须命中候选modelRefs之一，否则请求失败而非静默换模型。这意味着算法只会从当前决策的候选集中挑选，不会越权选择候选之外的模型。
按使用场景的配置实战
Startup / MVP：Static（静态选择）
推荐理由：用显式规则起步，行为确定、零依赖、容易调试；待积累数据后再迁移到自适应方法。
algorithm: type: static static: default_model: gpt-3.5-turbo从当前仓库看，静态选择的语义比文档示例更简单直接：默认选取该决策modelRefs中的第一项；若配置了按域（domain）的model_scores，则选取最高分候选。仓库提供的 static.yaml 片段只有两行：
algorithm: type: static minimum_candidates: 1细节可参考 selection/static.md：静态选择"不向后继候选故障转移、不对负载作出反应、不从结果中学习"，后端可用性仍由常规 provider 路径负责。
High-Volume Production：AutoMix 或 Hybrid
推荐理由：在规模化场景下，既要维持质量又要控制成本。
algorithm: type: automix automix: cost_quality_tradeoff: 0.4cost_quality_tradeoff的取值范围是 0 到 1：0.0表示永远选质量最高的模型，1.0表示永远选最便宜的模型。当前仓库源码 automix.go#L51-L108 给出了更完整的默认值：VerificationThreshold默认0.7（自校验置信度低于该阈值触发升级）、MaxEscalations默认2、CostQualityTradeoff默认0.3。仓库预置的 automix.yaml 片段展示了生产向的取值：
algorithm: type: automix automix: verification_threshold: 0.78 max_escalations: 2 cost_aware_routing: trueAutoMix 依赖模型侧的quality_score与pricing（input_cost_per_1k/output_cost_per_1k），用于在候选模型之间做成本-质量效用排序。文档建议 quality score 可通过基准测试（MMLU、HumanEval 等）、内部评测与用户满意度聚合得出。
User-Facing Applications：Elo
推荐理由：让用户反馈驱动主观质量维度上的模型选择。Elo 基于 Bradley-Terry 配对比较模型做在线学习，是经典 RouteLLM 思路的运行时版本——不训练静态路由器，而是根据实时反馈持续更新评分。
algorithm: type: elo elo: k_factor: 32 storage_path: /data/elo-ratings.jsonk_factor控制评分波动速度：16 为慢而稳定（适合反馈成熟的系统）、32 为平衡默认值、64 为快而剧烈（适合快速实验期）。当前仓库 elo.go 确认默认initial_rating = 1500、k_factor = 32，并支持storage_path（持久化评分）与auto_save_interval（保存频率，如1m）。若配置了category_weighted，可按类别分别维护评分。
反馈通过 feedback API 提交（v0.1 文档中的示例）：
# Positive feedback (model performed well) curl -X POST http://localhost:8080/api/v1/feedback \ -H "Content-Type: application/json" \ -d '{"request_id": "req-123", "model": "gpt-4", "rating": 1}' # Negative feedback (model performed poorly) curl -X POST http://localhost:8080/api/v1/feedback \ -d '{"request_id": "req-456", "model": "gpt-3.5-turbo", "rating": -1}'Specialized Domains：RouterDC
推荐理由：当模型各有明确专长时，用语义嵌入把查询与模型描述进行余弦相似度匹配，让"对口模型"承接对应查询。该方法受 RouterDC（基于双对比学习 Query-Based Router）论文启发，本仓库实现采用"预先计算模型描述嵌入"的简化方案。
algorithm: type: router_dc router_dc: require_descriptions: true当前仓库 router_dc.go#L37-L69 给出的默认值为：temperature = 0.07（softmax 缩放，按论文取值）、min_similarity = 0.3（低于该相似度则回退默认模型）。require_descriptions: true会强制启动时校验所有模型都有描述，缺描述则启动失败，从而尽早暴露配置问题。仓库预置的 router-dc.yaml 片段：
algorithm: type: router_dc router_dc: temperature: 0.2 dimension_size: 384 min_similarity: 0.7 use_query_contrastive: true模型侧需要配置描述与能力标签：
models: - name: gpt-4 description: "Advanced reasoning, complex analysis, mathematical proofs, and detailed explanations" capabilities: - reasoning - mathematics - code-review - analysis撰写描述的原则：具体化（写模型擅长的具体任务）、用关键词（覆盖用户可能在查询中使用的措辞）、差异化（突出独特能力）、简洁（1～2 句聚焦优势）。能力标签建议每个模型保持 3～5 个。
Enterprise / Multi-objective：Hybrid
推荐理由：需要同时平衡质量、成本、用户满意度与模型专长等多目标时，用加权组合把 Elo、RouterDC、AutoMix、成本四个信号统一为一个分数。
algorithm: type: hybrid hybrid: elo_weight: 0.3 router_dc_weight: 0.3 automix_weight: 0.2 cost_weight: 0.2组合分数公式（来自原文档）：
score(m, q) = w_elo × E(m) + w_dc × S(q,m) + w_mix × V(m,q) + w_cost × C(m)当前仓库 hybrid.go#L56-L65 的默认权重为experience_weight = 0.3、router_dc_weight = 0.3、automix_weight = 0.2、cost_weight = 0.2，且normalize_scores = true（各分量归一化到 [0,1] 后再加权）。注意仓库 v0.1 文档中的elo_weight在 selection_config.go 中对应experience_weight字段，配置时以你所使用版本的 schema 为准。仓库预置的 hybrid.yaml 片段示例：
algorithm: type: hybrid hybrid: experience_weight: 0.4 router_dc_weight: 0.4 automix_weight: 0.2 cost_weight: 0.1权重预置参考：
| 预置方案 | Elo/经验 | RouterDC | AutoMix | 成本 | 适用场景 |
|---|---|---|---|---|---|
| 均衡 | 0.25 | 0.25 | 0.25 | 0.25 | 通用 |
| 质量优先 | 0.4 | 0.3 | 0.2 | 0.1 | 高价值任务 |
| 成本优先 | 0.1 | 0.2 | 0.2 | 0.5 | 预算敏感 |
| 学习优先 | 0.5 | 0.2 | 0.2 | 0.1 | 快速适应期 |
硬性约束：权重之和必须等于 1.0（容差 ±0.01），否则校验失败。
Personalized Multi-User Platforms：Thompson Sampling 或 GMTRouter
推荐理由：多用户平台需要随时间学习每个用户的偏好。Thompson Sampling 将模型选择建模为多臂老虎机问题，通过 Beta 分布采样在探索（尝试不确定的模型）与利用（选择已知好模型）之间自动平衡。
algorithm: type: thompson thompson: per_user: true min_samples: 10核心参数：prior_alpha/prior_beta决定先验（(1,1) 均匀、 (2,1) 乐观、 (1,2) 悲观、 (10,10) 保守），per_user决定是否为每个用户维护独立分布，decay_factor控制旧观测的衰减（适合模型质量会漂移的非平稳环境），min_samples控制全量利用前的最少样本数。反馈更新规则为：成功α += 1，失败β += 1。
需要指出的是：v0.1 中的独立thompson算法，在当前仓库已并入 rl_driven.go 的 RL 驱动选择器（use_thompson_sampling: true即开启采样，默认开启），并配套exploration_rate = 0.3、exploration_decay = 0.99、min_exploration = 0.05等默认值；该实现还提供enable_personalization与personalization_blend（全局与用户级偏好的混合比例，默认 0.7）。
GMTRouter则用异构图神经网络（HGT）建模 用户—查询—响应—LLM 多轮交互图，学习用户级偏好：
algorithm: type: gmtrouter gmtrouter: num_layers: 2 # HGT 层深度 hidden_dim: 64 # 嵌入维度 num_heads: 4 # 注意力头数 learn_preferences: true # 启用在线偏好学习 model_path: null # 可选的预训练权重当前仓库 gmtrouter.go#L78-L92 的默认值：embedding_dimension = 768、num_gnn_layers = 2、attention_heads = 8。GMTRouter 适合用户基数大、多轮交互历史丰富的场景；如果用户太少、无历史数据或对延迟极其敏感（GNN 推理约增加 10ms），则应考虑其他算法。
Research / Complex Routing Logic：Router-R1
推荐理由：当路由逻辑难以用规则编码、需要语义理解时，让 LLM 本身充当路由器，通过<think>（推理）与<route>模型名</route>（决策）的循环来做出选择。
algorithm: type: router_r1 router_r1: router_endpoint: http://localhost:8001 use_cot: truethink/route 协议示例：
<think> Analyzing query: "Debug this Python code" - Query type: coding task - Requires: code understanding, debugging - Best model: code-llama (specialized for code) </think> <route>code-llama</route>关键参数：router_endpoint（Router-R1 服务地址）、max_iterations（默认 3）、temperature（默认 0.7）、use_cot（链式推理）、fallback_to_static（路由器不可用时回退静态选择，推荐开启以实现优雅降级）。多模型聚合模式（enable_aggregation: true）下，路由器可依次调用多个模型并把响应并入上下文后综合成最终答案，这更贴近原论文的多轮聚合思路。
当前仓库中该能力由 rl_driven.go 的EnableLLMRouting+RouterR1ServerURL配置控制，并配套 router_r1_client.go 作为 LLM 路由客户端。Router-R1 的代价是明显的延迟增量（原文档给出的典型参考值 100–500ms），只适合对延迟不敏感的场景。
渐进迁移路径
系统成熟度提升时的典型演进路线（原文档）：
- 起步：Static 选择 + 简单规则
- 收集反馈：积累用户反馈后迁移到 Elo
- 补充描述：加入 RouterDC 做查询-模型匹配
- 优化成本：引入 AutoMix 提升成本效率
- 组合：使用 Hybrid 综合所有方法
实践中可以分阶段切换，且每次切换前都要用历史流量或影子模式验证效果——v0.1 文档指出算法变更可通过配置重载生效，在途请求仍按旧算法完成。
关键考量
数据需求
| 算法 | 数据需求 |
|---|---|
| Static | 不需要数据 |
| Elo | 需要持续一致的用户反馈（点赞/点踩） |
| RouterDC | 需要高质量的模型描述 |
| AutoMix | 需要准确的定价与质量评分 |
| Hybrid | 上述组合 |
| Thompson Sampling | 需要反馈，可在线运行 |
| GMTRouter | 受益于交互历史，可预训练 |
| Router-R1 | 需要独立的 Router LLM 服务；模型描述有助于决策 |
延迟影响
以下为原文档给出的典型参考值，实际数值取决于部署环境：
| 算法 | 典型延迟 |
|---|---|
| Static | < 1ms |
| Elo | < 2ms |
| RouterDC | 2–5ms（含 embedding） |
| AutoMix | < 3ms |
| Hybrid | 3–5ms |
| Thompson | < 2ms |
| GMTRouter | 5–15ms（GNN 推理） |
| Router-R1 | 100–500ms（LLM 决策） |
维护成本
- Static：手动更新规则
- Elo：反馈驱动，自维护
- RouterDC：模型变更时更新描述
- AutoMix：成本变化时更新定价
- Hybrid：建议周期性调优权重
运行时前置条件
结合 modelselection/README.md 的说明，几种自适应算法并非开箱即用，需要先满足外部依赖：
- RouterDC / Hybrid 的语义匹配分量依赖Embedding 能力（RouterDC 默认维度 768，
dimension_size需与 Embedding 模型输出一致）； - Elo / Thompson 依赖反馈通道（feedback API 持续投递）与持久化存储（
storage_path，未配置时数据在重启后丢失）； - AutoMix 依赖模型pricing 与 quality_score字段；
- Router-R1 依赖独立部署的Router LLM 服务，未就绪时应保持
fallback_to_static； - GMTRouter 依赖多轮交互历史与可选预训练权重（
model_path）。
排障与调优速查
来自 troubleshooting.md 的常见问题处理要点：
- Elo 评分不变化：检查 feedback 请求是否返回 200；K-factor 过低可提到 64；反馈量不足时需累积流量。若某个模型长期霸榜，可删除
storage_path文件重置评分，或启用decay_factor降低旧比较的权重。 - RouterDC 选错模型：先检查模型描述是否过于笼统（"A good AI model" 是反面典型），再确认 Embedding 是否正常计算（
curl /metrics | grep embedding）。require_descriptions: true下缺失描述会导致启动失败。 - AutoMix 总选贵模型：
cost_quality_tradeoff过低（偏向质量），调高到 0.5 左右；总选便宜模型则反向调低到 0.2 左右。同时确认定价数据完整。 - Hybrid 权重校验失败：权重之和必须为 1.0（±0.01）。
- 组件不贡献分数：Elo 缺反馈历史、RouterDC 缺模型描述、AutoMix 缺定价数据，都会让对应分量失效。
- 调试手段：将
logging.level设为debug；用X-Request-ID请求头（如debug-123）追踪单请求并检索日志；关注model_selection_duration_seconds、model_selection_total、model_elo_rating等选择相关指标。
从源码理解选择算法的执行生命周期
最后把这套机制串起来看。一次带选择算法的请求在 Semantic Router 中的执行链路大致是（依据 extproc/router_selection.go 与 factory.go 的实现推断）：
- extproc 启动时通过
createModelSelectorRegistries构建选择器注册表：读取全局model_selection配置、注入模型配置（WithModelConfig）、分类目录（WithCategories）、上下文 Embedding 函数与查询表，最终CreateAll()实例化全部选择器； - 请求到达后先做路由决策匹配，命中的决策若配置了
algorithm，则从注册表取出对应选择器； - 选择器读取该决策的
modelRefs候选集，按算法逻辑打分（静态规则、Elo 评分、余弦相似度、POMDP 值或加权组合）； - 选出分数最高的候选并校验其必须命中
modelRefs，随后请求被路由到该模型。
正是这个"先匹配决策、再在决策候选内选模型"的两段式结构，让你可以为不同查询类型（tech、coding、general 等）分别配置不同算法——例如技术类查询用 Elo、常规查询用 Static——实现精细化的多策略共存。
小结
选型没有绝对最优，只有"当前阶段最合适"。起步用 Static 保证确定性与可审计性，有反馈后引入 Elo，有描述后叠加 RouterDC，重视成本时启用 AutoMix，最后用 Hybrid 统一多目标；面向个性化多用户平台再考虑 Thompson Sampling / GMTRouter，需要语义推理时引入 Router-R1。每一类算法在当前仓库中都有对应的源码实现（src/semantic-router/pkg/selection）与可参考的配置片段（config/fragments/algorithm/selection），切换时注意以你所用版本的配置 schema 为准（v0.1 文档与当前主线的字段名存在演进，如similarity_threshold→min_similarity、confidence_threshold→verification_threshold、elo_weight→experience_weight）。理解每个算法的数据前提、延迟代价与维护成本，比记住任何一组参数都更重要。
- 后端
- API网关
- 模型推理服务
- AI Agent
【免费下载链接】semantic-router
An open, programmable decision layer for models and compute.
相关推荐
semantic-router 的 decision 选择算法：让决策模型为每条请求挑选最合适的模型
semantic router 的 decision 选择算法：让决策模型为每条请求挑选最合适的模型 导读 decision 是 vLLM semantic r
后端API网关模型推理服务AI Agentsemantic-router KNN 模型选择算法指南：基于历史示例的最近邻路由策略
semantic router KNN 模型选择算法指南：基于历史示例的最近邻路由策略 knn 是 semantic router 内置的四种 ML 模型选择算
后端API网关模型推理服务AI Agentsemantic-router 静态选择（static）算法实战指南：确定性模型路由、领域分数排序与配置详解
semantic router 静态选择（static）算法实战指南：确定性模型路由、领域分数排序与配置详解 导读 static 是 semantic rout
后端API网关模型推理服务AI Agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
