端边云三级路由 + S1/S2/S3 隐私分级：一个 OpenAI 兼容网关怎么决定请求上不上云

项目地址：https://github.com/adongwanai/hybrid-router-oss

这是一个 OpenAI-compatible 的端、边、云混合推理调度网关。请求不会直接发给某个固定模型，而是先经过任务复杂度分类、隐私分级、本地能力识别、上下文长度估算、缓存判断和运行状态评估，再决定走端侧、边侧还是云侧。

项目包含 Gateway、可视化 Dashboard、Redis 缓存与轨迹、Prometheus/Grafana 监控、Open WebUI 聊天入口和 Docker Compose 部署配置。

与常见方案的差别

核心能力

• 兼容 OpenAI /v1/chat/completions 和 /v1/models 接口。
• 两级复杂度分类：优先走本地 semantic-router（<5ms），置信度不足时用 RouteLLM MF 兜底（~20ms）。
• 隐私策略先于模型路由：S1 禁止上云，S2 可脱敏后上云，S3 按能力与成本调度。
• 本地能力策略：本地文件、本地动作请求默认不出云。
• 端侧（Ollama）、边侧（vLLM）、云侧（DeepSeek API）三层逻辑模型，可配置真实 OpenAI-compatible 后端。
• 支持共享真实后端，便于演示“路由是否正确”，同时保留端/边/云路由展示。
• Redis 语义缓存和路由轨迹记录。
• Dashboard 支持聊天测试、路由分布、KPI、路由轨迹和 Demo Case。
• Prometheus + Grafana 可观测性。
• 可接入 Open WebUI，作为标准聊天界面。

架构流程

用户 / Dashboard / Open WebUI
  -> Gateway /v1/chat/completions
  -> API Key 鉴权
  -> 分类缓存
  -> semantic-router 本地向量路由 (<5ms)
  -> RouteLLM MF 兜底分类 (~20ms)
  -> 隐私检测与脱敏 (S1/S2/S3)
  -> 本地文件/本地动作策略
  -> device / edge / cloud 路由决策
  -> 语义缓存
  -> OpenAI-compatible 模型后端 (Ollama / vLLM / DeepSeek)
  -> 路由轨迹 + Prometheus 指标

快速启动

cp .env.example .env
./start.sh

启动后访问：

• Dashboard：http://localhost:8080
• Gateway：http://localhost:4000
• Grafana：http://localhost:3001
• Prometheus：http://localhost:9090
• Open WebUI：http://localhost:3000

首次体验建议保留 .env 中的：

MODEL_BACKEND_MODE=mock

这样只 mock 最后的模型生成文本，分类、隐私、路由、缓存、轨迹和 Dashboard 都会真实执行，适合无 API Key、无 GPU 的环境先把系统跑通。

接入真实模型

支持两种真实模型接入方式。

方式一：演示用共享真实后端

适合演示“路由是否正确”。端、边、云三层逻辑仍然存在，但实际生成统一调用一个 OpenAI-compatible 模型接口。

MODEL_BACKEND_MODE=real
REAL_BACKEND_BASE_URL=https://api.deepseek.com
REAL_BACKEND_API_KEY=your-api-key
REAL_BACKEND_MODEL=deepseek-v4-pro
DEVICE_BACKEND_MODEL=deepseek-v4-pro
EDGE_BACKEND_MODEL=deepseek-v4-pro
CLOUD_BACKEND_MODEL=deepseek-v4-pro

方式二：端、边、云分别接入

适合真实部署。

MODEL_BACKEND_MODE=real

DEVICE_OPENAI_BASE_URL=http://ollama:11434/v1
DEVICE_BACKEND_MODEL=qwen3:1.5b

EDGE_OPENAI_BASE_URL=http://vllm:8000/v1
EDGE_BACKEND_MODEL=deepseek-ai/DeepSeek-V4-Flash

DEEPSEEK_API_BASE=https://api.deepseek.com/v1
DEEPSEEK_API_KEY=your-api-key
DEEPSEEK_CLOUD_MODEL=deepseek-v4-pro

路由策略

路由器综合以下信号做决策：

• 任务复杂度：SIMPLE、MEDIUM、COMPLEX、RESEARCH、REASONING。
• 隐私等级：S1、S2、S3。
• 上下文长度和阈值。
• 边侧是否可用、边侧队列深度。
• 端侧模型能力。
• 本地文件、本地动作等能力边界。
• 缓存命中情况。

默认策略：

两级分类器的分工也是成本来源之一：本地向量路由覆盖大部分请求，只有置信度不够时才交给 RouteLLM MF 兜底，不需要每条请求都让大模型当裁判，省下的是判官本身的 token 开销。

隐私模型

隐私检测在路由之前执行：

• S1：高敏数据，禁止上云。
• S2：中敏数据，可脱敏后上云。
• S3：公开或低风险数据，可按复杂度、成本和能力调度。

检测内容包括手机号、邮箱、身份证号、银行卡、IP、工资、财务、合同、专利、涉密关键词等。S2 数据会替换成占位符，例如 【PHONE-0001】、【ID-0001】、【AMOUNT-0001】。

技术栈

目录结构

gateway/              OpenAI-compatible 混合路由网关
dashboard/            Dashboard 后端和 React 前端
monitoring/           Prometheus 和 Grafana 配置
scripts/              Demo 和压测脚本
tests/                分类、隐私、路由、Demo Case 测试
ollama/               端侧模型辅助文件
vllm/                 边侧模型辅助文件
docs/                 PRD、技术报告、截图
docker-compose.yml    本地完整部署

本地开发

安装依赖并运行测试：

python3 -m pip install -r gateway/requirements.txt -r dashboard/requirements.txt pytest
pytest tests/ -v

构建前端：

cd dashboard/frontend
npm install
npm run build

国内网络说明

首次启动 Gateway 会下载分类器相关模型和权重。.env.example 默认配置了：

• USE_MODELSCOPE=true
• HF_ENDPOINT=https://hf-mirror.com
• PIP_INDEX_URL 使用国内镜像

如果在海外环境使用，也可以把这些镜像配置改回官方源。

开源注意事项

• 不要提交真实 .env。
• 不要提交 API Key、Token、数据库密码。
• 不要提交 .venv、node_modules、模型缓存、运行轨迹、Docker volume。
• 公开演示建议使用 MODEL_BACKEND_MODE=mock。
• 真实后端密钥建议通过私有部署环境变量或 GitHub Secrets 管理。

文档

• 技术报告：docs/TECHNICAL_REPORT.md
• 产品需求文档：docs/PRD_端边云混合推理调度系统.md

License

Apache License 2.0