126 lines
5.9 KiB
Markdown
126 lines
5.9 KiB
Markdown
# 多专业小模型 + 路由模型系统（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 轻量方案）
|