# ai-gateway-pro

**Repository Path**: happy-youth/ai-gateway-pro

## Basic Information

- **Project Name**: ai-gateway-pro
- **Description**: 本项目基于若依框架，打造轻量化AI智能体代理平台。支持火山引擎、OpenAI、智谱等主流厂商统一接入，内置滑动窗口熔断与跨厂商降级，单模型故障自动切换备选。提供代码执行、动态SQL、第三方接口三类技能及自定义参数透传。全链路提示词版本记录与一键回滚，降级事件异步审计。统一对话接口自动完成意图识别、技能调度与 AI总结，快速为现有系统私有化接入智能体能力。
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/happy-youth/ai-gateway-pro
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 1
- **Created**: 2026-04-15
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot, AI, Gateway, Agent, 熔断限流

## README

# AI Gateway Pro —— AI 智能网关平台

连接无限模型，编排极致智能

## 开源许可说明
本项目基于 **木兰宽松许可证 Mulan PSL v2** 开源分发。
1. 允许个人、企业免费复制、修改、闭源商用、私有化部署；
2. 分发、二次改造、打包发布（开源/闭源均可）时，**必须完整保留本项目全部版权声明、LICENSE文件、源码头部授权注释**，不得删除、屏蔽、篡改；
3. 禁止删除、涂抹源码内版权标识，禁止抹去来源宣称自研；
4. 禁止未经授权使用本项目名称、Logo进行商业宣传（本协议无商标授权）；
5. 若违反上述分发约束，属于侵犯软件著作权，我方将通过平台投诉、公证、民事诉讼追责，追究停止侵权、赔偿损失。

源码头部授权模板、部署规范见仓库LICENSE文件末尾使用指南。

***

## 🚀 平台简介

**AI Gateway Pro** 是一款基于 Java 17 + Spring Boot 4 + Vue 3 开发的 AI 智能网关平台。它在 RuoYi 框架权限管理能力的基础上，深度集成了 **MCP 协议**、**多模型动态调度**与**可视化技能编排**，旨在打造一个安全、高性能、可观测的 AI 能力中台。

> [!IMPORTANT]
> **✨ 核心愿景**：无需关注底层大模型差异，通过低代码方式快速构建具备复杂业务逻辑的 AI Agent。
> ![项目预览图](image/001.png)

***

## ✨ 核心特性

### 1. 🤖 多模型统一适配与调度

- **全厂商接入**：原生适配 OpenAI、阿里云通义千问、火山引擎豆包、智谱清言等主流厂商。
- **三段式架构**：支持 MCP 决策层、业务执行层与结果总结层独立选择不同模型，平衡成本与性能。
- **流式响应**：完美支持 SSE 流式输出，提供极致的打字机交互体验。

### 2. 🛠️ 深度技能编排 (Skill Orchestration)

- **多类型技能支持**：
  - **代码类 (Java/Bean)**：全量控制复杂业务逻辑。
  - **动态 SQL 类**：配置化编写 SQL，支持动态参数注入（如 `#{userId}`）。
  - **外部 HTTP 类**：一键对接第三方 API，支持 JSON 响应解析。
- **参数全链路透传**：支持自定义全局动态参数，实现从用户 Context 到技能执行的无缝流转。

### 3. 🧠 MCP 意图识别引擎

- **智能决策**：基于 Model Context Protocol，自动识别用户意图并匹配最优技能组合。
- **思考过程可视化**：实时展示 AI 的“深度思考”过程（Reasoning），提升用户信任感。

### 4. 📊 实时数据监控看板

- **Token 审计**：精确统计各模型、各业务维度的 Token 消耗（Input/Output）。
- **性能分析**：实时追踪请求量、成功率及平均响应耗时趋势。
- **成本画像**：基于饼图分析厂商资源占比，助力精细化成本管控。

### 5. 🛡️ 模型熔断降级 (Circuit Breaker & Fallback)

- **滑动窗口熔断**：支持按模型配置统计窗口、失败阈值与冷却时间，在时间窗口内失败达到阈值自动熔断跳过该模型。
- **跨厂商降级链**：支持 MCP、收口总结、默认兜底三个阶段各自配置降级模型链，按优先级自动切换至备选模型。
- **半开试探恢复**：熔断冷却结束后自动放行一次试探请求，成功则关闭熔断，失败则重新熔断。
- **异步日志审计**：降级事件通过 Spring Event 异步写入数据库，不阻塞主业务流程。
- **可视化监控**：提供降级日志查询页与降级统计页（模型失败排名、失败趋势图），首页看板实时展示当前熔断模型数量。

***

## 🏗️ 技术架构

### 1. 系统架构图

```mermaid
graph TD
    User((用户/客户端)) -->|HTTPS/SSE| LB[负载均衡]
    LB --> Admin[Gateway Admin - 接口层]
    Admin --> Framework[Gateway Framework - 安全/核心配置]
    Framework --> System[Gateway System - 业务逻辑层]

    subgraph AI 能力层
        System --> Fallback[Model Fallback - 降级编排]
        Fallback --> CB[Circuit Breaker - 熔断器]
        CB --> Strategy[Model Strategy - 模型策略]
        Strategy --> OpenAI[OpenAI API]
        Strategy --> DouBao[DouBao API]
        Strategy --> Other[其他模型]
        CB -.->|熔断状态| Redis
    end

    subgraph 数据支撑层
        System --> MySQL[(MySQL - 业务/统计)]
        System --> Redis[(Redis - 缓存/鉴权/熔断)]
        System --> EventBus[Spring Event Bus]
        EventBus --> Stats[Stats Service - 异步统计入库]
        EventBus --> FallbackLog[Fallback Log Listener - 异步降级日志]
        FallbackLog --> MySQL
    end
```

### 2. AI 智能对话流转 (MCP Sequence)

```mermaid
sequenceDiagram
    participant U as 用户
    participant M as MCP (意图识别)
    participant S as Skill (技能执行)
    participant SM as Summary (总结收口)
    participant LLM as 大模型厂商

    U->>M: 发起请求 ("查询北京天气")
    M->>LLM: 意图分析
    LLM-->>M: 识别意图: WEATHER_QUERY<br/>参数: {city: "北京"}
    
    rect rgb(240, 240, 240)
    note right of M: 技能编排阶段
    M->>S: 触发技能 (注入参数: city="北京")
    S->>S: 执行 SQL/HTTP 调用
    S-->>SM: 返回原始数据
    end

    SM->>LLM: 结果总结
    LLM-->>SM: 生成自然语言回复
    SM-->>U: "北京今天晴，气温 25℃..."
```

***

## 🛠️ 技术栈

| 维度        | 技术选型                  | 说明               |
| :-------- | :-------------------- | :--------------- |
| **后端核心**  | Spring Boot 4.0.3     | 响应式与高性能基础框架      |
| **权限安全**  | Spring Security + JWT | 无状态认证与细颗粒度权限控制   |
| **持久层**   | MyBatis 4.0.1         | 灵活的 SQL 映射与高性能查询 |
| **前端框架**  | Vue 3.5 + Vite        | 现代化响应式 UI 框架     |
| **UI 组件** | Element Plus          | 适配 AI 主题的现代化组件库  |
| **图表库**   | ECharts 5.6           | 统计数据可视化看板        |

***

## 📂 快速启动

### 1. 环境要求

- **JDK 17+**
- **MySQL 8.0+**
- **Redis 6.0+**
- **Node.js 18+**

### 2. 数据库初始化

执行 `sql/` 目录下的脚本：

1. `ai_gateway_pro.sql`: 系统基础权限表
2. `quartz.sql`: 定时任务表

### 3. 应用启动

**后端启动：**

```bash
cd ai-gateway
mvn clean install -DskipTests
mvn spring-boot:run -pl gateway-admin
```

**前端启动：**

```bash
cd ai-gateway-vue
npm install
npm run dev
```

> 默认账号：`admin` / `admin123`

***

## 📸 界面预览

|                 登录页面                 |               首页(统计)            |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/001.png)            | ![项目预览图](image/002.png)            |

|                 厂商管理              |                  新增厂商              |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/003.png)            | ![项目预览图](image/004.png)           |

|                 厂商模型管理              |                  新增修改模型            |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/005.png)            | ![项目预览图](image/006.png)           |

|                 智能体管理              |                  新增修改智能体            |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/007.png)            | ![项目预览图](image/008.png)           |

|                 智能体动态参数          |                  新增修改参数              |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/009.png)            | ![项目预览图](image/010.png)           |


|                智能体默认兜底          |                  智能体收口总结              |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/011.png)            | ![项目预览图](image/012.png)           |


|                 MCP管理          |                  MCP 新增修改             |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/013.png)            | ![项目预览图](image/014.png)           | 


|      技能管理 (可自定义实现 SQL http 的方式)  |                  SQL 技能 (下方给出具体教程)             |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/015.png)            | ![项目预览图](image/016.png)           |


|                 自定义方法实现技能       |             Https 技能              |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/017.png)            | ![项目预览图](image/018.png)           |


|                 提示词历史版本          |                  提示词历史版本对比 查看  |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/019.png)            | ![项目预览图](image/020.png)           |


|                 智能体对话          |           智能体对话触发技能(查询用户信息)       |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/021.png)            | ![项目预览图](image/022.png)           |

|      智能体触发技能 (查询订单信息)       |           智能体对话触发技能(查询用户岗位信息)       |
| :-----------------------------------: | :-----------------------------------: |
| ![项目预览图](image/023.png)            | ![项目预览图](image/024.png)           |


|         熔断降级日志          |         熔断降级统计          |
|:-----------------------:|:-----------------------:|
| ![项目预览图](image/025.png) | ![项目预览图](image/026.png) |



## 自定义技能具体实现方式

1. 后端这个目录下进行操作
ai-gateway/gateway-system/src/main/java/com/gateway/system/agent/skill/executor/code
2. 创建一个类
3. 实现 `SkillExecutor` 接口
4. 注册到 `SkillExecutorFactory` 中

```java
/**
 * 查询用户信息执行器
 * 
 * 示例实现：模拟查询用户信息
 */
@Service("queryUserInfo")
public class QueryUserInfoExecutor implements SkillCodeExecutor {

    @Override
    public Object execute(Map<String, Object> params) {
        // 从参数中获取 userId
        String userId = params.get("userId") != null ? params.get("userId").toString() : "unknown";
        
        // 模拟查询用户数据
        Map<String, Object> userInfo = new HashMap<>();
        userInfo.put("userId", userId);
        userInfo.put("userName", "用户" + userId);
        userInfo.put("email", "user" + userId + "@example.com");
        userInfo.put("phone", "138" + String.format("%08d", (int)(Math.random() * 100000000)));
        userInfo.put("status", "active");
        userInfo.put("createTime", "2024-01-15 10:30:00");
        
        // 模拟部门信息
        Map<String, Object> deptInfo = new HashMap<>();
        deptInfo.put("deptId", "D001");
        deptInfo.put("deptName", "技术部");
        userInfo.put("department", deptInfo);
        
        return userInfo;
    }

    @Override
    public String getDescription() {
        return "根据用户ID查询用户详细信息，包括基本信息、部门信息等";
    }
}
```

***

## 📜 开源协议

本项目遵循 [木兰宽松许可证 Mulan PSL v2](http://license.coscl.org.cn/MulanPSL2) 开源协议。