多专业小模型 + 路由模型系统（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）

🚀 快速开始

# 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）标准化评测路由质量
4. 接入 DeepSeek 等大模型 API 作为真实回退层
5. 语义缓存升级为 embedding 检索（当前为 n-gram 轻量方案）