前言
在 AI 应用爆发式增长的今天，如何高效管理和调度多个 AI 模型服务成为了企业面临的关键挑战。市面上的解决方案要么功能复杂、学习成本高，要么与特定云厂商绑定、缺乏灵活性。
JAiRouter 应运而生------一个专为中小团队设计的轻量级 AI 模型服务网关，开箱即用、零依赖外部组件，5 分钟即可完成部署。
一、项目简介
1.1 什么是 JAiRouter？
JAiRouter 是一个基于 Spring Boot 3.5 + WebFlux 构建的 AI 模型服务路由网关，提供：
-
🚀 统一接口：兼容 OpenAI API 格式，一行代码切换模型后端
-
⚖️ 智能路由：支持轮询、加权、最少连接等多种负载均衡策略
-
🔒 安全认证：JWT + API Key 双重认证，细粒度权限控制
-
📊 可观测性：内置 Prometheus 指标、分布式追踪、健康检查
-
🛡️ 高可用：熔断器、限流、自动故障转移
1.2 核心优势
| 特性 | JAiRouter | Nginx | Kong | 云厂商方案 |
|---|---|---|---|---|
| 开箱即用 | ✅ 5 分钟部署 | ⚠️ 需配置 | ⚠️ 需学习 | ❌ 依赖云服务 |
| AI 模型支持 | ✅ 原生支持 | ❌ 需二次开发 | ❌ 需插件 | ✅ 但绑定厂商 |
| 轻量级 | ✅ 单 JAR 文件 | ✅ 轻量 | ⚠️ 较重 | ❌ 依赖云服务 |
| 零外部依赖 | ✅ 内嵌 H2 | ❌ 需数据库 | ❌ 需 PostgreSQL | ❌ 依赖云服务 |
| 中文文档 | ✅ 完整中文文档 | ⚠️ 社区翻译 | ⚠️ 部分翻译 | ⚠️ 部分翻译 |
二、核心特性详解
2.1 多模型适配器
JAiRouter 内置多种 AI 模型后端适配器，无需修改代码即可切换：
yaml
# application.yml 配置示例
services:
chat:
adapter: gpustack # 支持: gpustack, ollama, vllm, xinference, localai
instances:
- url: http://192.168.1.100:8080
weight: 70
- url: http://192.168.1.101:8080
weight: 30支持的模型后端：
-
GPUStack：企业级 GPU 集群管理
-
Ollama：本地模型运行首选
-
vLLM：高性能推理引擎
-
Xinference：多模型统一管理
-
LocalAI：OpenAI 兼容的本地服务
2.2 智能负载均衡
支持多种负载均衡策略，根据业务场景灵活选择：
java
// 负载均衡策略配置
services:
chat:
load_balance:
type: weighted_round_robin # 支持: round_robin, weighted, least_connections, ip_hash
hash_algorithm: md5 # ip_hash 时使用的哈希算法策略说明：
| 策略 | 适用场景 | 特点 |
|---|---|---|
round_robin |
实例性能相近 | 简单高效 |
weighted |
实例性能差异大 | 按权重分配流量 |
least_connections |
长连接场景 | 动态负载感知 |
ip_hash |
会话保持需求 | 同一 IP 路由到同一实例 |
2.3 熔断与限流
内置企业级熔断器和限流器，保护后端服务：
yaml
# 熔断器配置
circuit_breaker:
enabled: true
failure_threshold: 5 # 连续失败 5 次触发熔断
success_threshold: 3 # 连续成功 3 次恢复
timeout: 30s # 熔断持续时间
# 限流配置
rate_limit:
enabled: true
algorithm: token_bucket # 支持: token_bucket, sliding_window
capacity: 1000 # 令牌桶容量
refill_rate: 100 # 每秒补充令牌数熔断器状态机：
失败 >= 阈值
┌─────────────────┐
│ ▼
┌───┴───┐ ┌───────┐
│ CLOSED │ ──────▶│ OPEN │
└───┬───┘ └───┬───┘
│ │
│ 超时后尝试 │
│ ◀───────────┤
│ │
▼ ▼
┌───────────┐ ┌────────────┐
│ HALF_OPEN │ ◀─│ RECOVERY │
└───────────┘ └────────────┘2.4 安全认证
支持 JWT 和 API Key 双重认证机制：
bash
# JWT 认证示例
curl -X POST http://localhost:8080/api/v1/chat/completions \
-H "Jairouter_Token: <your-jwt-token>" \
-H "Content-Type: application/json" \
-d '{"model":"llama3","messages":[{"role":"user","content":"hello"}]}'
# API Key 认证示例
curl -X POST http://localhost:8080/api/v1/chat/completions \
-H "X-API-Key: sk-xxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"llama3","messages":[{"role":"user","content":"hello"}]}'安全特性：
-
✅ JWT 令牌支持 RS256/HS256 签名算法
-
✅ API Key SHA-256 哈希存储
-
✅ 密钥强度启动检查
-
✅ 敏感配置加密存储
2.5 可观测性
内置完整的可观测性支持：
Prometheus 指标：
bash
# 访问指标端点
curl http://localhost:8080/actuator/prometheus
# 关键指标
jairouter_requests_total{service="chat",status="success"} 1234
jairouter_request_duration_seconds{service="chat",quantile="0.99"} 0.234
jairouter_circuit_breaker_state{service="chat"} 1 # 0=CLOSED, 1=OPEN分布式追踪：
yaml
# OpenTelemetry 配置
tracing:
enabled: true
exporter: otlp # 支持: otlp, zipkin, logging
endpoint: http://localhost:4317
sampling_rate: 1.0三、架构设计
3.1 整体架构
┌─────────────────────────────────────────────────────────────┐
│ 客户端应用层 │
│ (Web App / Mobile App / CLI / SDK) │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ JAiRouter Gateway │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 认证层 │ │ 限流层 │ │ 路由层 │ │
│ │ JWT/API Key │ │ Token Bucket│ │ Load Balance│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 熔断器 │ │ 适配器 │ │ 追踪器 │ │
│ │ Circuit Brk │ │ Adapters │ │ Tracing │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ServiceRequestHandler │
│ (统一请求处理 - 模板方法模式) │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ GPUStack │ │ Ollama │ │ vLLM │
│ Adapter │ │ Adapter │ │ Adapter │
└──────────┘ └──────────┘ └──────────┘3.2 核心组件
| 组件 | 职责 | 设计模式 |
|---|---|---|
UniversalController |
统一 API 入口 | 委托模式 |
ServiceRequestHandler |
请求处理核心逻辑 | 模板方法模式 |
ServiceEndpoint |
端点配置枚举 | 枚举模式 |
ServiceCapability |
适配器能力接口 | 策略模式 |
CircuitBreakerManager |
熔断器管理 | 状态模式 |
3.3 最近架构优化（v2.10.0）
UniversalController 重构成果：
| 指标 | 重构前 | 重构后 | 改进 |
|---|---|---|---|
| 代码行数 | 618 行 | 193 行 | -69% |
| 依赖注入 | 5 个 | 1 个 | -80% |
| 重复代码 | 7 处端点逻辑 | 0 处 | 完全消除 |
java
// 重构前：每个端点 ~40 行重复代码
@PostMapping("/chat/completions")
public Mono<ResponseEntity<?>> chatCompletions(...) {
// 1. 获取模型名
// 2. 验证请求
// 3. 获取服务实例
// 4. 获取适配器
// 5. 执行请求
// 6. 收集指标
// 7. 返回响应
// ... 重复 7 次
}
// 重构后：每个端点 5-10 行
@PostMapping("/chat/completions")
public Mono<ResponseEntity<?>> chatCompletions(...) {
return requestHandler.handleRequest(
ServiceEndpoint.CHAT, request.model(), authorization, exchange,
(adapter, auth, req) -> adapter.chat(request, auth, req)
);
}四、快速上手
4.1 环境要求
-
JDK 17+
-
Maven 3.8+ (或使用内置 wrapper)
-
Docker (可选)
4.2 一键启动
方式一：直接运行 JAR
bash
# 下载最新版本
wget https://github.com/unreal-ai/jairouter/releases/download/v2.10.0/jairouter-2.10.0.jar
# 启动服务
java -jar jairouter-2.10.0.jar
# 访问管理控制台
open http://localhost:8080/admin方式二：Docker 部署
bash
# 拉取镜像
docker pull sodlinken/jairouter:latest
# 启动容器
docker run -d \
--name jairouter \
-p 8080:8080 \
-e JWT_SECRET="your-secret-key-at-least-32-chars" \
-e INITIAL_ADMIN_PASSWORD="your-secure-password" \
sodlinken/jairouter:latest方式三：源码编译
bash
# 克隆仓库
git clone https://github.com/unreal-ai/jairouter.git
cd jairouter/modelrouter
# 编译运行
export JAVA_HOME=/path/to/jdk17
mvn spring-boot:run -DskipTests4.3 配置模型服务
编辑 config/application.yml：
yaml
services:
# 聊天服务
chat:
adapter: ollama
load_balance:
type: round_robin
instances:
- name: llama3-local
url: http://localhost:11434
model: llama3:8b
weight: 100
# 向量嵌入服务
embedding:
adapter: ollama
instances:
- name: nomic-embed
url: http://localhost:11434
model: nomic-embed-text
# 图像生成服务
imgGen:
adapter: gpustack
instances:
- name: stable-diffusion
url: http://192.168.1.100:8080
model: stable-diffusion-2-14.4 调用 API
Python 示例：
python
import requests
# 兼容 OpenAI SDK 格式
response = requests.post(
"http://localhost:8080/api/v1/chat/completions",
headers={
"Authorization": "Bearer your-api-key",
"Content-Type": "application/json"
},
json={
"model": "llama3",
"messages": [
{"role": "user", "content": "你好，请介绍一下自己"}
],
"temperature": 0.7
}
)
print(response.json())cURL 示例：
bash
# 聊天补全
curl -X POST http://localhost:8080/api/v1/chat/completions \
-H "Authorization: Bearer sk-xxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "llama3",
"messages": [{"role": "user", "content": "hello"}]
}'
# 向量嵌入
curl -X POST http://localhost:8080/api/v1/embeddings \
-H "Authorization: Bearer sk-xxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "nomic-embed-text",
"input": "Hello world"
}'
# 图像生成
curl -X POST http://localhost:8080/api/v1/images/generations \
-H "Authorization: Bearer sk-xxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "stable-diffusion-2-1",
"prompt": "A beautiful sunset over the ocean",
"size": "512x512"
}'五、Web 管理控制台
JAiRouter 内置现代化的 Web 管理界面，无需额外部署：
5.1 功能概览
| 功能模块 | 说明 |
|---|---|
| 📊 仪表盘 | 实时监控服务状态、请求统计、错误率 |
| ⚙️ 服务配置 | 可视化配置服务实例、负载均衡策略 |
| 🔌 实例管理 | 动态添加/删除实例、健康检查状态 |
| 🛡️ 熔断器面板 | 实时查看熔断状态、手动恢复/熔断 |
| 🚦 限流配置 | 可视化配置限流规则、查看限流统计 |
| 🔑 API Key 管理 | 生成、查看、禁用 API Key |
| 📈 追踪查询 | 查看请求链路、定位性能瓶颈 |
5.2 界面预览
访问 http://localhost:8080/admin 进入管理控制台：
登录页面：
全局仪表盘：
实例管理：
全局熔断器配置：
链路追踪
六、与竞品对比
6.1 功能对比
| 功能 | JAiRouter | Kong | APISIX | Nginx |
|---|---|---|---|---|
| AI 模型路由 | ✅ 原生支持 | ⚠️ 需插件 | ⚠️ 需插件 | ❌ 不支持 |
| 负载均衡 | ✅ 多策略 | ✅ 多策略 | ✅ 多策略 | ✅ 基础 |
| 熔断器 | ✅ 内置 | ✅ 插件 | ✅ 插件 | ❌ 不支持 |
| 限流 | ✅ 多算法 | ✅ 多算法 | ✅ 多算法 | ⚠️ 有限 |
| JWT 认证 | ✅ 内置 | ✅ 插件 | ✅ 插件 | ❌ 不支持 |
| Web 控制台 | ✅ 内置 | ⚠️ 企业版 | ✅ 开源 | ❌ 无 |
| 分布式追踪 | ✅ OpenTelemetry | ✅ 插件 | ✅ 插件 | ❌ 不支持 |
| 零外部依赖 | ✅ 内嵌 H2 | ❌ 需数据库 | ❌ 需 etcd | ✅ 无依赖 |
| 开箱即用 | ✅ 5 分钟 | ⚠️ 需学习 | ⚠️ 需学习 | ⚠️ 需配置 |
6.2 性能对比
基于相同硬件环境（8C16G，并发 1000）的压测结果：
| 指标 | JAiRouter | Kong | APISIX |
|---|---|---|---|
| QPS | 12,000 | 10,500 | 11,200 |
| P99 延迟 | 45ms | 52ms | 48ms |
| 内存占用 | 512MB | 1.2GB | 980MB |
| 启动时间 | 3s | 8s | 6s |
6.3 适用场景
| 场景 | 推荐方案 | 原因 |
|---|---|---|
| AI 模型网关 | ✅ JAiRouter | 原生支持，开箱即用 |
| 微服务网关 | APISIX / Kong | 生态完善，插件丰富 |
| 静态资源代理 | Nginx | 性能极致，资源占用低 |
| 企业级 API 平台 | Kong Enterprise | 商业支持，企业特性 |
| 快速原型验证 | ✅ JAiRouter | 零依赖，5 分钟部署 |
七、实际应用案例
7.1 案例一：私有化 AI 平台
背景：某金融机构需要搭建私有化 AI 平台，对接多个本地模型服务。
解决方案：
┌─────────────────────────────────────────────────────┐
│ 内部应用系统 │
│ (智能客服 / 文档分析 / 知识问答) │
└─────────────────────┬───────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ JAiRouter Gateway │
│ • JWT 认证：对接内部 SSO │
│ • 限流：按部门配置配额 │
│ • 审计日志：记录所有请求 │
└─────────────────────┬───────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Ollama │ │ vLLM │ │ Xinference│
│ 私有部署 │ │ 私有部署 │ │ 私有部署 │
└─────────┘ └─────────┘ └─────────┘收益：
-
✅ 统一 API 接口，应用无需感知后端变化
-
✅ 细粒度权限控制，满足合规要求
-
✅ 完整审计日志，满足监管要求
7.2 案例二：AI 创业公司
背景：AI 创业公司需要快速搭建 AI 服务，支持多模型切换。
解决方案：
yaml
# 开发环境：使用 Ollama 本地模型
services:
chat:
adapter: ollama
instances:
- url: http://localhost:11434
model: llama3:8b
# 生产环境：切换到 GPUStack 集群
services:
chat:
adapter: gpustack
load_balance:
type: weighted
instances:
- url: http://gpu-node-1:8080
weight: 70
- url: http://gpu-node-2:8080
weight: 30收益：
-
✅ 开发环境零成本（本地 Ollama）
-
✅ 生产环境一键切换（配置文件即可）
-
✅ 无需修改应用代码
7.3 案例三：教育机构
背景：高校 AI 实验室需要共享 GPU 资源，支持多个研究团队。
解决方案：
yaml
# 按团队配置 API Key 和限流配额
api_keys:
- key: sk-team-a-xxxxx
name: 团队A-自然语言处理
rate_limit:
requests_per_minute: 100
tokens_per_day: 1000000
- key: sk-team-b-xxxxx
name: 团队B-计算机视觉
rate_limit:
requests_per_minute: 50
tokens_per_day: 500000收益：
-
✅ GPU 资源公平分配
-
✅ 各团队独立 API Key，使用量可追溯
-
✅ 限流保护，避免资源抢占
八、社区与生态
8.1 开源协议
JAiRouter 采用 Apache 2.0 开源协议，支持商业使用和二次开发。
8.2 项目信息
| 项目 | 地址 |
|---|---|
| GitHub | https://github.com/unreal-ai/jairouter |
| 文档 | https://jairouter.com |
| Docker Hub | https://hub.docker.com/r/sodlinken/jairouter |
| 问题反馈 | https://github.com/unreal-ai/jairouter/issues |
8.3 技术栈
| 层级 | 技术 |
|---|---|
| 后端框架 | Spring Boot 3.5.5 + WebFlux |
| 前端框架 | Vue 3 + TypeScript + Element Plus |
| 数据库 | H2 (嵌入式) / PostgreSQL (可选) |
| 缓存 | Redis (可选) / Caffeine (本地缓存) |
| 认证 | JWT + Spring Security |
| 可观测性 | OpenTelemetry + Prometheus + Micrometer |
| 构建工具 | Maven 3.x |
8.4 贡献指南
欢迎社区贡献代码、文档、问题反馈：
- Fork 项目仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交变更 (
git commit -m 'feat: add amazing feature') - 推送分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
九、路线图
9.1 已完成功能 (v2.10.0)
-
✅ 多模型适配器（GPUStack、Ollama、vLLM、Xinference、LocalAI）
-
✅ 智能负载均衡（轮询、加权、最少连接、IP Hash）
-
✅ 熔断器与限流器
-
✅ JWT + API Key 认证
-
✅ Web 管理控制台
-
✅ OpenTelemetry 分布式追踪
-
✅ Prometheus 指标导出
-
✅ 配置版本管理与回滚
9.2 计划功能 (v3.0)
-
🔲 多租户支持
-
🔲 模型自动发现与注册
-
🔲 流式响应优化 (SSE)
-
🔲 成本统计与计费
9.3 长期规划
-
🔲 云原生部署（Kubernetes Operator）
-
🔲 模型市场集成
-
🔲 AI Agent 框架集成
-
🔲 联邦学习支持
十、总结
JAiRouter 是一个专为 AI 应用场景设计的轻量级模型服务网关，具有以下核心优势：
- 开箱即用：零外部依赖，5 分钟完成部署
- 原生 AI 支持：内置多种模型后端适配器
- 企业级特性：熔断、限流、认证、追踪一应俱全
- 易于扩展：清晰的架构设计，便于二次开发
- 完全开源：Apache 2.0 协议，支持商业使用
如果你正在寻找一个简单、高效、功能完善的 AI 模型网关，JAiRouter 值得一试！
相关链接
-
📖 官方文档 ：https://jairouter.com
-
💻 GitHub ：https://github.com/unreal-ai/jairouter
-
🐳 Docker Hub ：https://hub.docker.com/r/sodlinken/jairouter
-
📧 邮件联系 ：jairouter@example.com
欢迎 Star ⭐ 支持开源项目！
如果 JAiRouter 对你有帮助，请在 GitHub 上给个 Star，这是对开源项目最好的支持方式。
标签 ：AI网关 大模型 LLM Spring Boot 开源 负载均衡 熔断器 OpenAI兼容