【开源自荐】JAiRouter：一个轻量级 AI 模型服务网关的开源实践

前言

在 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 -DskipTests

4.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-1

4.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 值得一试！

【开源自荐】JAiRouter：一个轻量级 AI 模型服务网关的开源实践

前言

一、项目简介

1.1 什么是 JAiRouter？

1.2 核心优势

二、核心特性详解

2.1 多模型适配器

2.2 智能负载均衡

2.3 熔断与限流

2.4 安全认证

2.5 可观测性

三、架构设计

3.1 整体架构

3.2 核心组件

3.3 最近架构优化（v2.10.0）

四、快速上手

4.1 环境要求

4.2 一键启动

4.3 配置模型服务

4.4 调用 API

五、Web 管理控制台

5.1 功能概览

5.2 界面预览

登录页面：

全局仪表盘：

实例管理：

全局熔断器配置：

链路追踪

六、与竞品对比

6.1 功能对比

6.2 性能对比

6.3 适用场景

七、实际应用案例

7.1 案例一：私有化 AI 平台

7.2 案例二：AI 创业公司

7.3 案例三：教育机构

八、社区与生态

8.1 开源协议

8.2 项目信息

8.3 技术栈

8.4 贡献指南

九、路线图

9.1 已完成功能 (v2.10.0)

9.2 计划功能 (v3.0)

9.3 长期规划

十、总结

相关链接