semantic-router K 近邻（KNN）模型选择算法：原理、配置与训练产物实战指南

后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载本指南系统讲解 semantic-router 中基于 K 近邻KNN的可学习模型选择算法它如何利用历史请求嵌入、模型分配、结果质量与延迟数据在路由决策命中后从候选模型中选出最优项。文章以官方教程文档为骨架结合pkg/modelselection、pkg/selection与训练流水线的源码实现覆盖算法原理、配置参数、产物格式、训练与验证全流程读完即可在自己的 Router 配置中落地一套可解释的检索式模型选择策略。概览从最相似的已记录请求中学习选模型knnK 近邻模型选择器是 semantic-router 提供的四种学习型模型选择算法之一另三种为kmeans、svm、mlp核心思路是从在最相似的已记录请求上表现良好的模型中选择一个候选。它的运行位置在路由器内部采用纯 Go 实现推理无需任何在线训练步骤——Router 启动时加载由历史示例构建的产物JSON 格式的预训练模型文件即可完成每次选择。从源码结构看整个机制由三部分协作完成训练端Pythonsrc/training/model_selection/ml_model_selection负责评测候选模型、构造带标签样本、导出 JSON 产物运行时Gosrc/semantic-router/pkg/modelselection加载产物并完成推理src/semantic-router/pkg/selection/ml_adapter.go将其桥接进路由器的选择系统配置端路由决策decision上的algorithm.type: knn与全局 ML 设置共同决定何时启用、如何加载产物。一个选择器只在某个路由决策匹配成功后运行并在该决策声明的modelRefs候选中挑出唯一模型其选择结果必须命中某个候选modelRef否则请求失败而非静默改选其他模型见 selector.go。主要优势可解释每次路由决策都可以追溯到相似的、已记录的历史示例——选中某个模型是因为一批最相似的历史查询在它上面表现良好而不是黑盒打分。无在线训练步骤Router 只加载由历史示例构建的产物文件运行时是纯 Go 推理不依赖 Python 环境或外部模型服务。自然匹配相似提示词选相似模型的场景当相似提示词应当选择相似模型时knn的效果往往优于固定优先级。质量与速度联合加权投票把每个邻居权重的 90% 分给结果质量10% 分给相对速度兼顾谁表现好与谁更快。算法原理嵌入 → 搜索 → 加权投票 → 选择knn的选择过程分四步嵌入每个查询被嵌入成稠密向量由嵌入模型生成如 Qwen3 系列嵌入模型。搜索在历史查询嵌入空间中找到k个最近邻。投票每个邻居为它当时训练记录中使用的模型投票。注意距离只决定哪些示例进入邻居集不改变它们的投票权重投票把记录的质量与产物内归一化的延迟结合起来。选择加权投票最高的模型被选中。其打分公式为$$\text{score}(m) \sum_{i \in \text{KNN}(q)} w_i \cdot \mathbb{1}[m_i m]$$其中 $w_i 0.9 \cdot \text{quality}_i 0.1 \cdot \text{speed_factor}_i$。记录中最快延迟的速度因子为1最慢为0。源码层面的精确实现Go 运行时的实现在 knn.go 中与文档公式逐项对应特征归一化查询与训练样本都先按欧氏范数做 L2 归一化normalized()函数零向量保持原样因此实际距离度量等价于余弦排序对非零向量而言参见 vector.go。最近邻搜索用最大堆neighborHeap维护当前最接近的k个样本距离采用vecmath.SquaredDistance64平方欧氏距离平局时取样本索引更小者closer()中的平局规则。速度因子与权重速度因子按speed 1 / (1 latency_ns / 10_000_000_000)计算延迟以纳秒存储权重为0.9 * quality 0.1 * speed与训练端models.py中的公式完全一致。投票与平局票数按邻居从近到远累计若多个模型的票数并列取字典序最靠前的模型名获胜。训练端models.py 的KNNModel使用 scikit-learn 的NearestNeighborsmetriceuclidean、algorithmball_tree、n_neighborsmin(k, len(samples))建立索引并在预测时通过 radius 边界平局处理保证与 Go 运行时契约一致。选择流程文档给出的完整选择流程如下补充一点实现细节如果选择上下文已携带查询嵌入SelectionContext.QueryEmbedding则直接复用否则MLSelectorAdapter会按需调用嵌入函数现场计算嵌入失败时退化为空嵌入见 ml_adapter.go 的Select方法。解决什么问题何时使用当路由应遵循相似历史提示词的先例时手写规则或固定优先级会丢失有用的局部上下文例如某些学科/语言/风格的问题天然更适合某个模型。knn按最近示例及其观测结果选择模型从而解决这个问题。推荐使用knn的条件你有历史提示词到模型的分配数据query-to-model 的评测结果。相似提示词通常应映射到同一候选模型。路由应使用检索式选择而不是固定排序。你需要可解释的路由决策决策可以追溯到具体历史样例。如果尚未积累足够的代表性查询 → 模型结果数据官方建议先使用无需训练产物的策略static、router_dc、automix、multi_factor、latency_aware等参见 modelselection README。已知限制每次选择都要扫描全部已加载样本文档将其概括为每次选择都会从已加载示例重建 BallTree更大的产物会增加搜索和分配成本。从当前 Go 实现看classify()每次会对全部训练样本做一次线性扫描并用大小为k的最大堆维护最近邻knn.go因此产物越大每次选择的搜索与分配成本越高。性能取决于嵌入质量差的嵌入会导致差的匹配——算法完全建立在嵌入空间的相似性假设上。无法捕获复杂非线性模式它只是局部先例投票不像 MLP 或带非线性核的 SVM 那样能学习全局非线性边界。需要为所有历史查询预先计算嵌入产物的构建依赖离线嵌入无法凭空生成。配置从最小片段到完整决策knn的配置分为两层决策上的算法声明 全局 ML 设置。最小算法片段在路由决策的algorithm上声明类型这也是 config/fragments/algorithm/selection/knn.yaml 提供的片段内容algorithm: type: knn全局 ML 设置文档给出的全局配置示例如下global: router: model_selection: ml: models_path: .cache/ml-models embedding_dim: 768 knn: k: 5 pretrained_path: .cache/ml-models/knn_model.json参数说明参数类型默认值说明kint5考虑的最近邻数量pretrained_pathstring—预训练 KNN 模型路径JSON 格式补充说明embedding_dim必须与产物中嵌入向量的维度一致否则选择请求会因特征维度不匹配而失败默认值在 ml_adapter.go 的DefaultMLSelectorConfig中为 1024对应 Qwen3 嵌入模型输出文档示例中的 768 与 README 示例中的 384 都要求训练与运行时严格对齐。若未指定pretrained_path而只设置models_pathNewSelector会按models_path/knn_model.json的约定路径加载见 selector.go 的NewSelector缺失或未训练的产物在多模型决策上是硬错误。global.router.model_selection.ml对应的 Go 配置结构体为MLSelectionConfigselection_config.go其中knn子块对应MLKNNConfig{K, PretrainedPath}。完整可运行的最小拓扑下面是从 modelselection README 继承的完整配置示例它声明了两个候选模型small-model / large-model、一个使用knn的决策以及全局 ML 设置部署前请替换 endpoint 与产物路径version: v0.3 listeners: - name: http-8899 address: 0.0.0.0 port: 8899 providers: models: - name: small-model provider_model_id: small-model backend_refs: - name: small-model-server endpoint: small-model:8000 protocol: http weight: 1 - name: large-model provider_model_id: large-model backend_refs: - name: large-model-server endpoint: large-model:8000 protocol: http weight: 1 defaults: default_model: small-model routing: decisions: - name: learned-route description: Select a candidate with the trained KNN policy. priority: 100 rules: operator: AND conditions: [] modelRefs: - model: small-model - model: large-model algorithm: type: knn modelCards: - name: small-model - name: large-model global: router: model_selection: enabled: true ml: embedding_dim: 384 knn: k: 5 pretrained_path: /models/selection/knn_model.json关键约束产物必须能被 Router 容器读取产物的嵌入维度、特征布局、模型名必须与运行时配置完全匹配model_selection.enabled: true是启用前提。产物中的模型标签名需要与modelRefs中的模型名或 LoRA 名见 selector.go 的candidateName对应否则即使 KNN 成功选出一个模型也会因selected model not found in available refs而失败。特征向量查询嵌入 领域 one-hot与kmeans、svm、mlp一样KNN 的特征向量并非只有查询嵌入而是查询嵌入后接一个固定顺序的领域 one-hot 向量Feature [QueryEmbedding] [CategoryOneHot]领域类别由 features.go 中的VSRCategories定义共 14 个math、physics、chemistry、biology、computer science、history、economics、business、law、health、psychology、philosophy、other、unknown。未知类别默认落入other。这个顺序必须与 Python 训练端data_loader.py保持一致更换嵌入模型或其维度都需要重新训练产物。这也解释了为什么产物里的样本维度往往是embedding_dim 14例如 1024 14 1038 维。训练从评测记录到 JSON 产物训练在服务进程之外独立完成。完整流水线位于 training README步骤为准备评测数据JSONL 格式至少包含queryground_truth与category在存在时保留{query:What is the capital of France?,ground_truth:Paris,category:other}安装依赖cd src/training/model_selection/ml_model_selection python -m venv .venv . .venv/bin/activate pip install -r requirements.txt评测候选模型把每条查询发给每个候选模型记录响应、延迟与质量分python benchmark.py --help python benchmark.py \ --queries queries.jsonl \ --model-config models.yaml \ --output benchmark_output.jsonl训练选择器默认嵌入模型为 Qwen3--algorithm all可同时导出 KNN/KMeans/SVM/MLP 四种产物python train.py --help python train.py \ --data-file benchmark_output.jsonl \ --output-dir models \ --algorithm all \ --device cpu导出文件与选择器的对应关系文件选择器knn_model.json质量加权近邻本文主题kmeans_model.json基于聚类的选择svm_model.json支持向量分类mlp_model.json多层感知机需要 PyTorch发布或下载产物涉及鉴权时使用HF_TOKENpython download_model.py --output-dir models python upload_model.py --model-dir models --repo-id ORGANIZATION/REPOSITORYKNN 产物的 JSON 结构以训练端KNNModel.save()与 Go 端parseKNN()为准knn_model.json的核心字段为字段说明algorithm固定为knnformat_version产物格式版本新版 Python 导出为2需要配套能识别的 Routertrained是否已训练false会被 Go 加载器拒绝k训练时的邻居数embeddings每行一个样本的特征向量含 one-hot 类别段labels每个样本对应的模型名qualities每个样本的结果质量分latencies每个样本的延迟整数纳秒仓库自带的校验产物 testdata/knn_model.json 展示了最小可用形态16 维特征、2 个样本、qualities与latencies数组与样本数对齐。加载器会拒绝特征形状错误、非有限数值NaN/Inf、样本数与标签/质量/延迟数组不一致等非法产物。数据与保留策略KNN 产物保留从历史提示词和结果派生的信息本质上是对源评测数据的再加工。请对其应用与源评测数据相同的访问和保留策略——不要因为它是训练产物就放松合规审查。测试与验证从 Router 模块运行单元测试cd src/semantic-router go test ./pkg/modelselection ./pkg/selection单元测试覆盖产物加载、特征构造、候选匹配与选择器行为使用testdata/下的小型入库产物从不下载模型。推理是纯 Go其选择结果还会与它所替代的 Rust 绑定FusionFactory、Avengers-Pro 等记录下来的夹具testdata/selection_binding_fixtures.json.gz做一致性比对。如需额外用发布产物跑一遍需要先自行准备目录并放置knn_model.json等四个文件VLLM_SR_TEST_ML_MODELS_DIR/absolute/path/to/ml-models \ go test ./pkg/modelselection -run Published|Pretrained训练端还提供确定性 parity 校验从仓库根目录执行需要 NumPy、scikit-learn、pytest 与 Gomake test-model-selection-parity它会真实训练 sklearn 选择器、导出产物并把同一批查询通过 Router 的选择器重放覆盖 KNN 的延迟加权与邻居平局规则。部署前还可用validate.go通过模型运行时服务嵌入模型对产物做端到端校验vllm-sr serve Qwen/Qwen3-Embedding-0.6B --device cpu --port 8100 make run-ml-selection-validate GO_TOOL_ARGS--runtime http://127.0.0.1:8100 \ --no-download --data-file benchmark_output.jsonl --models-dir models --algorithm all小结knn是 semantic-router 学习型模型选择家族中最直观、最可解释的一员用历史请求的先例投票代替手写规则与固定优先级质量占 90%、相对速度占 10% 的加权机制让选择既看重效果也兼顾效率。使用它的关键前提是有可靠的 query-to-model 评测数据、有与训练一致的嵌入模型与特征布局、产物能按约定路径被 Router 加载。按照本文的配置示例、训练命令与验证流程即可把一套可解释的检索式模型选择策略接入生产路由。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐Semantic Router 的 ML 模型选择器knn / kmeans / svm / mlp 四种学习式选择算法的配置、原理与训练产物Semantic Router 的 ML 模型选择器knn / kmeans / svm / mlp 四种学习式选择算法的配置、原理与训练产物 本文围绕 se后端API网关模型推理服务AI Agentsemantic-router 的 SVM 模型选择算法原理、配置与训练实战指南semantic router 的 SVM 模型选择算法原理、配置与训练实战指南 本文以 website/docs/tutorials/algorithm/s后端API网关模型推理服务AI AgentOpenCV K 近邻kNN算法实战从分类原理到手写数字与字母 OCROpenCV K 近邻kNN算法实战从分类原理到手写数字与字母 OCR 导读 本教程围绕 OpenCV 的 cv.ml.KNearest 展开分两个章节科学计算科研数据分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考