智能模型路由（Router 服务）

版本：v0.13.2+ · 状态：阶段一（容灾与信号底座）+ 阶段二（任务感知与模型池）已落地

Router 是 VeyraOS 的智能模型路由服务，承担模型调用的「路由大脑」与「信号闭环」角色。它把 LiteLLM 从「模型转发器」升级为可观测、可容灾、可审计、按任务自动选模型的智能路由平台。

架构定位

Router 与其专属的 LiteLLM 实例组成独立部署栈（独立 namespace veyra-router），与主系统零耦合：不引用主系统的 Deployment/Service/Secret，不使用主系统的 LiteLLM 实例与数据库。成熟后主系统再以服务方式集成。

调用方（per-key，OpenAI 兼容）
        │
        ▼
  LiteLLM（:4000，L1 供应适配层 + 数据面；本栈专属 wrapper 实例）
        │  GenericAPILogger 批量上报调用事件（脱敏，不带对话内容）
        ▼
  Router 服务（:8005，L4 路由大脑 + L2 信号闭环）
        │
        ▼
  PostgreSQL（栈内两个独立 database：router / router_litellm）

数据面自包含：调用方直连本栈 LiteLLM /v1/chat/completions；模型注册、key 签发、计费归因全部在本栈 LiteLLM 实例内完成（Admin API + master key）。
控制面独立：Router 不查询 manager 或其他服务，只依赖本栈 LiteLLM（其 L1 适配层）与自身 PG 库。
归属反解自包含：签发方在创建 LiteLLM key 时把 {instance_id, group_id} 写入 key metadata；Router 周期同步 LiteLLM /key/list 到 api_key_registry 表，事件摄入时按 user_api_key_hash（= key 的 sha256，与 key list 的 token 一致）精确反解归属。

阶段一能力清单

能力	说明
自动容灾	LiteLLM Router 失败重试 + 连续失败冷却（`num_retries=2`、`allowed_fails=3`、`cooldown=60s`），上游 429/5xx 自动重试并隔离故障通道；降级链（`fallbacks`）为可配置项，默认关闭
健康画像	每 (模型组, 通道) 5min 滚动窗口聚合：错误率 / p50 / p99 / 三态（正常·恢复中·不可用），`model_health` 表快照
决策日志	每次 LLM 调用一行 `routing_decisions`（7 天 TTL），含错误三问分类（配置/客户端/上游）、fallback 链标记、成本与 token 用量
审计存证	决策日志日级链式 sha256 锚（`routing_decision_anchors` 长青表），支持重放校验与篡改/断链检测
权重再平衡	普通模型组多上游按健康×延迟×成本动态调权（热写回 LiteLLM，默认关闭，`UA_ROUTING_WEIGHT_ENABLED=true` 开启）
Wrapper 钩子	`engines/litellm/veyra_hooks.py`：路由决策响应头回传（`x-veyra-routing-`/`x-veyra-cls-`）、per-key 质量阈值注入、RPO 风险定价信号、G2 健康画像软转移、空回复保险——全部默认 shadow 观察模式，环境变量翻牌，任何异常一律放行（绝不影响请求路径）

阶段二能力清单

能力	说明
任务语义分类器	`engines/litellm/veyra_classifier.py`：BGE 嵌入原型（19 任务类型 × SIMPLE/MEDIUM/COMPLEX/REASONING 四档）+ 难度信号修正（长度/代码块/轮次深度/工具密度升档，高风险关键词地板 COMPLEX）；ONNX INT8 进程内推理，prompt 不出网关；`UA_CLASSIFIER_MODE=off/shadow/active` 三态
智能模型组（模型池）	`POST /api/router/model-groups` 创建即渲染为 LiteLLM 池部署（热生效）：`smart` 智能路由（成员画像自动推导难度阶梯）/ `tiered` 按难度选择 / `cost_first` 成本优先 / `quality_first` 质量优先（后两者走 bandit 从真实反馈学习）；支持关键词分档规则与成本↔质量偏好权重
分类粘性会话	短续轮（「继续」等）继承首轮分类结果，同会话语义连贯
级联观测（N5 shadow）	低置信偏低档分类记录「假设级联复核」（不调二次模型，零成本收集触发率数据）
飞轮聚合面板数据	`GET /api/router/routing-flywheel/summary`：决策量/环比、分类覆盖率、shadow 分歧率、日×档位趋势、任务类型分布、按 LiteLLM 实时定价估算的节省额
训练语料采样	`POST /api/router/internal/prompt-samples`（默认关，`UA_PROMPT_SAMPLE_RATE` 显式开启），分类器校准/重训语料，30 天 TTL

关键设计约束

错误三问：401/403/404 → 配置错误（不计健康，人工修正）；400/422 → 客户端错误（不计健康）；429/5xx/408/超时 → 上游错误（计入健康，触发冷却/fallback）。
软偏好硬兜底：Router 与钩子的全部智能都只降优先级、绝不阻断请求；Router 服务自身不可用时 LiteLLM 照常转发（事件上报 fire-and-forget）。
单副本：健康窗口与归属缓存是进程内状态，Router 固定 1 副本（多副本会视角分裂）。
事件端点防伪造：未配置 UA_LITELLM_CALLBACK_TOKEN 时 /api/router/internal/events 拒绝一切写入。

部署

独立部署栈 deploy/router/（独立 namespace veyra-router），主系统部署流程（deploy/ci/deploy.sh）不包含本栈。详细步骤与验证脚本见 deploy/router/README.md。

镜像：veyraos/router（services/router/Dockerfile）与 veyraos/litellm（wrapper，engines/litellm/Dockerfile），构建 make docker-router / make docker-litellm。
数据库：栈内两个独立库 router / router_litellm，由 initContainer 幂等创建；PG 实例由栈自己的 Secret 指定（可指向任意 PG，库级隔离）。
配置项（env 前缀 UA_）：UA_DATABASE_URL、UA_LITELLM_BASE_URL、UA_LITELLM_MASTER_KEY、UA_LITELLM_CALLBACK_TOKEN、UA_ROUTING_DECISION_TTL_DAYS（默认 7）、UA_ROUTING_WEIGHT_ENABLED（默认 false）等，完整见 services/router/app/settings.py。

查询接口（阶段一：X-Internal-Token 鉴权，集群内访问）

端点	说明
`GET /api/router/model-health`	通道健康列表（内存实时窗口覆盖 DB 快照）
`GET /api/router/model-health/history`	通道健康时间条（6h 桶 × 7 天）
`GET /api/router/routing-decisions`	决策明细分页查询（支持实例/模型组/档位/状态过滤）
`GET /api/router/routing-decisions/export`	决策明细 cursor 导出（训练集构建用）
`GET /api/router/routing-decisions/anchors`	日锚存证列表
`POST /api/router/routing-decisions/anchors/{day}/verify`	重放校验某日锚
`GET /api/router/routing-flywheel/summary`	飞轮聚合（覆盖率/分歧率/趋势/类型分布/节省估算）
`GET/POST/PUT/DELETE /api/router/model-groups`	智能模型组（池）管理，保存即渲染热生效
`POST /api/router/model-groups/preview-ladder`	难度阶梯预览（不落库）
`POST /api/router/model-groups/{id}/apply`	手动重新渲染（LiteLLM 侧漂移后恢复对齐）

本地排障示例：kubectl port-forward -n veyra-router svc/router 8005:8005 后携带 X-Internal-Token 访问。

路线图

~~阶段一：容灾止血（重试/冷却、健康画像、决策日志、审计锚）~~ ✅
~~阶段二：任务感知路由（语义分类器 + 智能模型组池 + 粘性会话）与飞轮聚合~~ ✅（分类器当前 shadow 灰度中，观察分歧率达标后翻 active）
阶段三：对外服务能力（external key 自助签发、配额与预算、语义缓存、成本账本与毛利引擎）；分类器 v2（LightGBM，用本服务沉淀的语料训练）；级联实装（响应后重决策）。

智能模型路由（Router 服务） ​

架构定位 ​

阶段一能力清单 ​

阶段二能力清单 ​

关键设计约束 ​

部署 ​

查询接口（阶段一：X-Internal-Token 鉴权，集群内访问） ​

路线图 ​