# 多专业小模型 + 路由模型系统（MVP）

用「轻量分类路由器 + 专业小模型池 + 质量控制器(Judge) + 大模型回退」在限定条件下替代单一通用大模型，
实现 **成本降低 80%+、延迟可控** 的目标。本仓库是《实现方案_多专业小模型+路由模型.md》的第一阶段落地。

## ✨ 当前能力（2026-08-12 已跑通）

- ✅ 零依赖 mock 全链路可运行：缓存 → 分类 → 专家 → Judge → 回退
- ✅ 5 领域意图分类（code / math / legal / medical / general），规则分类器准确率 **100%**（15 条评测样例）
- ✅ 两阶段缓存（L1 精确 + L2 语义 n-gram，零依赖），评测缓存命中率 **40%**
- ✅ 质量控制器（Judge）自动评估输出并触发升级，升级率 **20%**（命中第二阶段验收线）
- ✅ FastAPI 网关：`/chat` `/health` `/metrics`，20 项单元测试全部通过
- ✅ 可选接入真实模型：HuggingFace 小模型（`type: hf`）或 OpenAI 兼容 API（`type: api`）

## 🚀 快速开始

```powershell
# 1. 创建虚拟环境并安装依赖（核心 router_system 零依赖，网关/测试需要轻量依赖）
C:\Python314\python.exe -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

# 2. 运行演示（mock 模式，离线可跑）
.venv\Scripts\python.exe scripts/demo.py

# 3. 迷你评估（分类准确率 / 升级率 / 缓存命中率）
.venv\Scripts\python.exe scripts/eval.py --repeat 2

# 4. 运行单元测试
.venv\Scripts\python.exe -m pytest tests -v

# 5. 启动 API 网关
.venv\Scripts\python.exe scripts/serve.py --port 8000
#   停止：.venv\Scripts\python.exe scripts/serve.py --stop

# 6. 调用接口
curl http://127.0.0.1:8000/health
curl -X POST http://127.0.0.1:8000/chat -H "Content-Type: application/json" -d '{"query":"用 Python 写一个快速排序函数"}'
curl http://127.0.0.1:8000/metrics
```

## 🏗️ 架构

```
用户查询
   │
   ▼
┌───────────────────┐    ┌──────────────────┐
│ RouterCache 缓存   │───▶│ 命中 → 直接返回    │
│ (L1精确 / L2语义)  │    └──────────────────┘
└─────────┬─────────┘
          ▼ 未命中
┌───────────────────┐   低置信度(<0.60) ┌──────────────────┐
│ 分类路由器          │ ───────────────▶ │ 大模型回退         │
│ RuleClassifier /   │                  │ Mock / DeepSeek  │
│ HuggingFace        │                  └──────────────────┘
└─────────┬─────────┘
          ▼ 高置信度
┌───────────────────┐
│ 专家模型池          │  code/math/legal/medical/general
│ Mock / HF / API    │
└─────────┬─────────┘
          ▼
┌───────────────────┐   质量分<0.70 ┌──────────────────┐
│ Judge 质量控制器    │ ────────────▶ │ 升级大模型回退     │
│ Rule / LLM-as-Judge│              └──────────────────┘
└───────────────────┘
```

一次请求的完整路由轨迹示例：

```
cache:miss -> classify:code@0.95/hard -> expert:expert-code -> judge:0.96
cache:miss -> classify:general@0.50/easy -> direct_fallback
```

## ⚙️ 配置（config/config.yaml）

默认全 mock（零依赖离线）。接入真实模型只需改 `type`：

| 组件 | 当前 | 可切换 | 说明 |
|------|------|--------|------|
| classifier | `rule` | `hf` | 正式环境建议训练 BERT 级分类器（94-97%） |
| experts.* | `mock` | `hf` / `api` | HF 小模型或 OpenAI 兼容 API |
| judge | `rule` | `llm` | LLM-as-Judge |
| fallback | `mock` | `api` | 设置 `DEEPSEEK_API_KEY` 环境变量 |

关键阈值：
- `low_confidence_threshold: 0.60` —— 分类置信度低于此值直接走大模型
- `judge_fallback_threshold: 0.70` —— Judge 质量分低于此值升级大模型

## 📂 目录结构

```
├── router_system/          # 核心（零依赖纯标准库）
│   ├── classifier.py       # 意图分类器（规则 / HF）
│   ├── difficulty.py       # 难度估计
│   ├── experts.py          # 专家池（Mock / HF / API）
│   ├── judge.py            # 质量控制器
│   ├── fallback.py         # 大模型回退
│   ├── cache.py            # 两阶段缓存
│   ├── router.py           # 主路由
│   └── stats.py            # 指标
├── gateway/api.py          # FastAPI 网关
├── scripts/                # demo / eval / serve / train_classifier
├── tests/                  # 20 项单元测试
├── config/config.yaml      # 配置
└── research/               # 论文调研
```

## 📊 验收指标对照（实现方案 5.1/5.2）

| 指标 | 目标 | 当前（mock 评测） |
|------|------|------------------|
| 分类准确率 | ≥95%（正式） | 100%（15 条样例） |
| 升级率（fallback rate） | ≤20% | 20% |
| 缓存命中率 | ≥30% | 40% |
| 端到端延迟 | < 大模型 1.5× | mock 下 ~10-16ms |

## 🔜 下一步（对照实现方案）

1. 接入真实小模型：`pip install -r requirements-ml.txt`，`experts.*.type` 改 `hf`
2. 训练 BERT 级分类器替代规则分类器（`scripts/train_classifier.py` 流水线骨架）
3. 用 RouterArena（[GitHub](https://github.com/RouteWorks/RouterArena)）标准化评测路由质量
4. 接入 DeepSeek 等大模型 API 作为真实回退层
5. 语义缓存升级为 embedding 检索（当前为 n-gram 轻量方案）