feat: 多专业小模型+路由模型系统 MVP（mock 全链路 + FastAPI 网关 + 论文调研）

2026-08-12 10:40:04 +08:00
commit 1e51167ea5
50 changed files with 49382 additions and 0 deletions
@@ -0,0 +1,125 @@
+# 多专业小模型 + 路由模型系统（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 轻量方案）