路由小模型微调

微调工具链、客户部署实例内训练、正反样本接口、训练任务生命周期、产出权属与数据隔离口径

平台的智能路由由一只轻量的路由小模型驱动：它在每次查询进入时研判复杂度、择优分流到最合适的上游模型。出厂的路由小模型基于通用查询分布训练，开箱即用；而每个客户的真实查询分布各有侧重——有的偏长文本检索，有的偏代码生成，有的偏中文问答。微调工具链让你用自己的查询样本继续训练这只路由小模型，使路由决策更贴合本实例的实际流量，从而在不牺牲质量的前提下让分流更准、整体成本更省。

本节介绍何时需要微调、训练在哪里发生、如何提交正反样本、训练任务的生命周期，以及产出模型的权属与数据隔离口径。微调相关能力仅在运营控制台可见，对应控制平面 /api/v1/finetune/* 一组端点。

1. 何时需要微调

出厂路由小模型对绝大多数场景已足够。出现下列信号时，微调通常能带来可观收益：

信号	说明
路由分布与查询特征不符	「请求监控」页显示大量简单查询被分流到强档模型，或复杂查询被分流到弱档模型
单一业务线流量高度集中	某子账户的查询长期集中于某一类任务（如代码、长文检索、结构化抽取），通用路由未能针对性优化
误判带来的成本或质量波动	复杂度研判偏差导致重试、故障转移偏多，或同类查询的模型选择不稳定
上游模型池有较大调整	新接入或下线了模型，路由小模型需要重新学习新的分流边界

微调改变的是「路由决策」——即把哪一类查询交给哪一档模型，不改变上游模型本身的生成行为，也不触及缓存检查点与安全护栏两层中间件。它是对中间件管道中「路由」一环的贴身优化。

判断是否值得微调，建议先在「请求监控」（GET /api/v1/monitor/overview）观察复杂度分布与模型选择分布是否与业务直觉一致，再决定是否启动训练。

2. 训练发生在哪里

路由小模型的训练在客户部署实例内进行：训练样本、训练过程与产出模型都不离开实例所在的运行环境。

部署模式	训练运行位置
私有化部署	客户自有控制环境内，样本与产出始终在客户侧
SaaS 部署	供应方托管环境内、属于本实例的 VM 级逻辑隔离边界内，与其他实例互不可见

两种部署模式下，训练样本都只在本实例的隔离边界内参与训练，不与任何其他实例共享，也不用于平台侧的全局模型训练。数据隔离与留存的详细口径见数据安全。

3. 正反样本接口

微调以「正反样本」驱动。每条样本是一次查询连同一个路由判定标签：

正样本：该查询应当路由到所标注的模型档位（强化这一类分流）。
反样本：该查询不应路由到所标注的模型档位（抑制这一类分流）。

正反样本成对积累，能让路由小模型既学会「该往哪走」也学会「不该往哪走」，比只给正样本收敛更稳。

3.1 提交样本

样本以样本集为单位提交，一个样本集归属于一个训练任务。提交端点接收一个样本数组：

curl https://your-platform/api/v1/finetune/jobs/<任务标识>/samples \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "polarity": "positive",
    "samples": [
      {
        "query": "把这段 Go 代码改写为并发安全版本并解释改动",
        "expected_tier": "strong",
        "note": "代码改写类，需要强档模型"
      },
      {
        "query": "今天星期几",
        "expected_tier": "weak",
        "note": "常识类简单查询，弱档即可"
      }
    ]
  }'

字段	含义
`polarity`	样本极性：`positive`（正样本）/ `negative`（反样本）
`samples[].query`	查询文本（参与训练的输入特征）
`samples[].expected_tier`	期望路由档位标签：正样本表示「应路由到此档」，反样本表示「不应路由到此档」
`samples[].note`	可选备注，便于人工复核样本

响应回执给出本次入库的样本计数与所属样本集：

{
  "sample_set_id": "<样本集标识>",
  "job_id": "<任务标识>",
  "polarity": "positive",
  "accepted": 2,
  "total_in_set": 2
}

反样本将上例 polarity 改为 negative 即可，字段结构一致。正、反样本分别落入同一任务下的不同样本集，训练时合并使用。样本只接受查询文本与档位标签，不要求也不应提交查询的完整响应内容或任何业务原文之外的敏感数据——路由决策只需查询特征即可学习。

4. 训练任务生命周期

一次微调对应一个训练任务。任务从创建、积累样本、训练，到产出可用的路由小模型，经历一条线性生命周期。

4.1 状态流转

状态	含义
`running`	进行中：样本已就绪并启动训练，或正在训练
`completed`	完成：产出新的路由小模型，可在路由中启用
`failed`	失败：训练未能完成（样本不足、特征不可用等），可查看原因后重试

4.2 创建任务

curl https://your-platform/api/v1/finetune/jobs \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "代码业务线路由优化",
    "base_model": "<当前在用路由小模型标识>"
  }'

{
  "job_id": "<任务标识>",
  "name": "代码业务线路由优化",
  "status": "running",
  "train_env": "in-customer-instance",
  "ownership": "customer",
  "started_at": "<训练起始日>"
}

train_env 恒为「在客户部署实例内训练」，ownership 恒为「权属归客户」——两者由部署形态决定，不可在请求中更改（详见第 5 节）。

4.3 查询任务列表

curl "https://your-platform/api/v1/finetune/jobs?status=running&page=1&page_size=20" \
  -H "Cookie: <控制台会话凭证>"

响应为分页的任务列表，每条含任务名、状态、起止时间与权属标注。

4.4 查询任务详情

任务详情除基本信息外，回显正反样本集摘要，以及该任务适用的权属、数据隔离与删除窗口口径：

curl https://your-platform/api/v1/finetune/jobs/<任务标识> \
  -H "Cookie: <控制台会话凭证>"

{
  "job_id": "<任务标识>",
  "name": "代码业务线路由优化",
  "status": "completed",
  "train_env": "in-customer-instance",
  "ownership": "customer",
  "started_at": "<训练起始日>",
  "finished_at": "<训练完成日>",
  "sample_sets": [
    { "polarity": "positive", "sample_count": 120 },
    { "polarity": "negative", "sample_count": 84 }
  ],
  "isolation_note": "<数据隔离口径标注>",
  "delete_window": "<样本删除窗口口径>"
}

任务完成后，新的路由小模型不会自动接管线上流量；是否启用、何时启用由你在「模型微调」页确认。这样可先对照「请求监控」观察新旧路由的分流差异，确认收益后再切换。

4.5 训练期计价说明

训练期内首次接入的密钥享折扣计价，用于覆盖样本积累与验证阶段的调用开销；其后新增密钥按全额计价，质检类调用不计费。相关折扣标识会随逐条调用记录与月度结算单一并呈现，便于核对。训练期时长与具体折扣比例以服务协议与控制台显示为准。

5. 产出权属与数据隔离

微调产出的路由小模型及其训练样本，权属与处置遵循以下口径：

项目	口径
模型权属	微调产出的路由小模型权属归客户。退出服务时，路由小模型随中间件、编排脚本、策略配置一并列入退出导出清单（见数据安全）
训练位置	训练全程在客户部署实例的隔离边界内进行，样本与产出不外流（见第 2 节）
数据隔离	训练样本仅用于本实例的路由小模型训练，不与其他实例共享、不进入平台侧任何全局训练
样本删除	训练样本在约定的删除窗口内清理，仅保留训练所得的路由小模型与必要的任务记录；具体删除窗口口径以服务协议为准

数据隔离与删除窗口的具体时限属合规口径，统一以服务协议约定与控制台显示为准，本文不固化具体数值。退出导出、数据留存与清理任务的整体说明见数据安全。