版本：最新版（未发布）

基于 ML 的模型选择

基于 ML 的选择学习决策候选池中哪个模型最适合某个请求。当历史评测数据比固定优先级顺序或少量手写规则携带更多信息时，它很有用。

选择器在路由决策匹配之后运行。它只能从该决策的 modelRefs 中选择；它不会发现、部署或认证 provider 模型。

可用选择器

选择器	如何选择	在以下情况考虑
KNN	在相似查询上组合记录的质量和速度	相似请求往往偏好同一模型，且可追溯性很重要
KMeans	将请求映射到已学习的簇	工作负载形成稳定簇，且查找成本很重要
SVM	使用已学习的决策边界	候选模型在特征空间中干净分离
MLP	用神经网络为候选打分	你有足够数据训练非线性选择器；Router 在 CPU 上执行训练后的产物

没有普遍最好的选择器。将每个候选与简单基线比较，例如固定默认、随机选择，以及同一留出数据集上的最佳单模型。

训练前准备

你需要：

两个或更多 OpenAI 兼容模型端点
代表性查询和标准答案，或其他可辩护的评分方法
足够的重复覆盖，以便在重要工作负载切片上评测每个候选模型
训练和在线推理时相同的嵌入模型
密钥、速率限制、成本以及模型响应保留计划

基准测试将每个所选查询发送到多个 provider 端点，并存储其响应、质量分数和延迟。当提示词或响应包含用户数据时，将输出视为敏感。

控制面板工作流

在控制面板中打开 /ml-setup 以运行引导工作流：

上传模型端点 YAML 文件和查询 JSONL 文件。
对候选模型做基准测试。
训练一个或多个选择器。
定义决策并下载配置片段。

Benchmark 和 Train 步骤会在控制面板的 ML 数据目录下产生数据和模型产物。

当前配置导出

生成的 ml-model-selection-values.yaml 是迁移片段，不是独立的规范 Router 配置。其 config.model_selection、config.strategy 和 config.decisions 字段必须经过评审，并映射到完整配置中的 global.router.model_selection、global.router.strategy 和 routing.decisions。添加所需的 listeners 和 providers，然后在部署前运行 vllm-sr config validate --config ...。

命令行工作流

1. 安装训练依赖

cd src/training/model_selection/ml_model_selection
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

2. 准备评测查询

每行使用一个 JSON 对象。ground_truth 是为模型输出打分所必需的；category 可选，但对切片评测有用。

{"query":"What is the derivative of x^2?","ground_truth":"2x","category":"math","metric":"MATH"}
{"query":"Which city is the capital of France?","ground_truth":"B","category":"other","metric":"em_mc","choices":"A) London B) Paris C) Berlin D) Rome"}

选择与任务匹配的指标。基准支持精确/包含匹配、选择题提取、GSM8K 和 MATH 答案提取、文本 F1 以及代码评测。检查基准输出，而不是假设一个指标适合每个领域。

3. 描述候选端点

将凭据放在环境变量中。不要把字面 API 密钥写进 YAML 文件。

models:
  - name: local-small
    endpoint: http://localhost:8000/v1
  - name: hosted-model
    endpoint: https://provider.example/v1
    api_key: ${PROVIDER_API_KEY}

4. 对每个候选做基准测试

python benchmark.py \
  --queries queries.jsonl \
  --model-config models.yaml \
  --output benchmark-output.jsonl \
  --concurrency 4

从低并发开始。仅在确认每个端点都能维持请求速率，且 provider 速率限制没有扭曲延迟测量后，再提高并发。

5. 训练选择器

python train.py \
  --data-file benchmark-output.jsonl \
  --output-dir models

默认情况下脚本训练 KNN、KMeans、SVM 和 MLP 产物。使用 --algorithm knn|kmeans|svm|mlp 训练单个选择器，或在 PyTorch 依赖不可用时使用 --skip-mlp。训练接受 cpu、cuda 或 mps。当前 Router 决策工厂在 CPU 上运行已加载的 MLP 产物；其 device 字段为兼容性接受，但未接到选择上。

输出目录包含 knn_model.json、kmeans_model.json、svm_model.json 和 mlp_model.json 等 JSON 产物。其内容特定于被基准测试的模型名、嵌入模型和特征布局。

6. 配置 Router

将选择器设置合并进完整规范配置。此示例是片段；完整文件仍需要 listeners、providers 以及决策使用的任何信号。

global:
  router:
    model_selection:
      ml:
        models_path: /models/selection
        model_type: qwen3
        embedding_dim: 1024
        knn:
          k: 5
          pretrained_path: /models/selection/knn_model.json

routing:
  decisions:
    - name: math
      description: Route math requests with the trained KNN selector.
      priority: 100
      rules:
        operator: AND
        conditions:
          - type: domain
            name: math
      algorithm:
        type: knn
      modelRefs:
        - model: local-small
        - model: hosted-model

配置的 model_type 和 embedding_dim 选择 ML 选择器使用的嵌入特征空间，必须与训练产物匹配。其他选择算法和嵌入消费者继续使用默认语义嵌入配置。若省略 model_type，ML 选择器也为向后兼容使用该默认值。modelRefs 中的模型名必须与基准数据中记录的名称以及已配置的 provider 别名匹配。

vllm-sr config validate --config config.yaml

上线前评测

使用未用于拟合或调优选择器的留出数据集。报告：

按工作负载切片的回答质量指标
所选模型分布
端到端延迟和 provider 成本
相对选择最佳已评测响应的 oracle 的 regret
与固定默认、最佳单模型和随机基线的比较
失败、超时和排除的样本

将数据集修订、源提交、模型修订、嵌入模型、硬件、命令和原始报告与任何头条结果一起发布。没有这些来源的百分比或 QPS 不能描述预期生产性能。

常见问题

找不到产物

从 Router 运行时内部检查 models_path 和每个 pretrained_path，而不仅仅在主机上。按配置使用的同一路径挂载或打包文件。

嵌入维度不匹配

训练和推理使用同一嵌入模型和特征布局，并将 embedding_dim 设为导出产物的维度。

留出质量差

确认模型名和标签匹配，检查类别和领域覆盖，查找训练/测试泄漏，并与简单基线比较。更复杂的选择器无法补偿不具代表性的基准数据。

可用选择器​

训练前准备​

控制面板工作流​

命令行工作流​

1. 安装训练依赖​

2. 准备评测查询​

3. 描述候选端点​

4. 对每个候选做基准测试​

5. 训练选择器​

6. 配置 Router​

上线前评测​

常见问题​

找不到产物​

嵌入维度不匹配​

留出质量差​

参考​