# chat_ai_gateway

**Repository Path**: aiobc/chat_ai_gateway

## Basic Information

- **Project Name**: chat_ai_gateway
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Chat AI Gateway

基于 Java 21 + Spring Boot 3.x 的统一 AI Gateway，支持多种大模型提供商（OpenAI、Anthropic、国内大模型等）。

> 📋 [查看路线图](./ROADMAP.md) 了解项目未来规划和可扩展功能

## 功能特性

- **统一 API**: OpenAI 兼容的 API 接口，一套代码对接所有模型
- **多 Provider 支持**: OpenAI、Anthropic、通义千问、文心一言、智谱 AI、豆包等
- **认证授权**: API Key 认证，租户级隔离
- **限流配额**: Redis 滑动窗口限流，支持 API Key / 租户 / IP 多级限流
- **负载均衡**: 多 Provider 实例负载均衡（加权随机、轮询）
- **故障转移**: 自动检测 Provider 健康状态，故障时自动切换
- **响应缓存**: 基于请求哈希的响应缓存，降低成本
- **可观测性**: Prometheus 指标、请求日志、审计追踪

## 技术栈

- **Java 21**: 虚拟线程、模式匹配等新特性
- **Spring Boot 3.2**: 最新版本
- **Spring WebFlux**: 响应式编程支持
- **Redis 7**: 限流、缓存存储
- **Maven**: 多模块项目管理
- **Micrometer**: Prometheus 指标暴露

## 快速开始

### 环境要求

- Java 21+
- Maven 3.9+
- Redis 7+

### 本地开发

1. **克隆项目**
```bash
git clone <repository-url>
cd chat-ai-gateway
```

2. **配置环境变量**
```bash
export OPENAI_API_KEY=your-openai-key
export ANTHROPIC_API_KEY=your-anthropic-key
export DASHSCOPE_API_KEY=your-dashscope-key
```

3. **启动 Redis**
```bash
docker run -d -p 6379:6379 redis:7-alpine
```

4. **运行项目**
```bash
mvn clean install -DskipTests
cd gateway-app
mvn spring-boot:run
```

### Docker 部署

```bash
# 设置 API Key
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# 启动
docker-compose up -d
```

## 配置说明

编辑 `gateway-app/src/main/resources/application.yml`:

```yaml
gateway:
  # Provider 配置列表
  providers:
    # OpenAI
    - id: openai-default
      type: openai
      api-key: ${OPENAI_API_KEY:}
      base-url: https://api.openai.com/v1
      enabled: true
      weight: 10
      model-mapping:
        gpt-4: gpt-4
        gpt-3.5-turbo: gpt-3.5-turbo

    # Anthropic
    - id: anthropic-default
      type: anthropic
      api-key: ${ANTHROPIC_API_KEY:}
      enabled: true
      weight: 10

    # 通义千问
    - id: qwen-default
      type: qwen
      api-key: ${DASHSCOPE_API_KEY:}
      enabled: true
      weight: 10

  # 限流配置
  rate-limit:
    enabled: true
    default-window: 60    # 窗口大小（秒）
    default-limit: 100    # 窗口内最大请求数

  # 缓存配置
  cache:
    enabled: true
    default-ttl: 300s     # 默认缓存时间
```

## API 使用

### 统一认证

所有 API 请求都需要在 Header 中携带 API Key:

```
X-API-Key: your-api-key
X-Tenant-Id: optional-tenant-id
X-Provider: optional-provider-type  # 强制指定 provider
```

### 聊天补全 (非流式)

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'
```

**响应示例:**
```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": "chatcmpl-xxx",
    "object": "chat.completion",
    "created": 1700000000,
    "model": "gpt-3.5-turbo",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Hello! How can I assist you today?"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 8,
      "total_tokens": 18
    },
    "provider": "openai"
  },
  "requestId": "xxx",
  "timestamp": 1700000000000
}
```

### 聊天补全 (流式)

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

### Embeddings

```bash
curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": ["Hello world", "Goodbye"]
  }'
```

### 管理 API

```bash
# 查看 Provider 列表
curl -H "X-API-Key: test-key" http://localhost:8080/admin/providers

# 动态注册 Provider
curl -X POST http://localhost:8080/admin/providers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key" \
  -d '{
    "id": "new-provider",
    "type": "openai",
    "api-key": "sk-xxx",
    "enabled": true
  }'
```

## 可观测性

### Prometheus 指标

访问: `http://localhost:8080/actuator/prometheus`

关键指标:
- `gateway_requests_total`: 请求总数
- `gateway_request_latency_seconds`: 请求耗时分布
- `gateway_errors_total`: 错误总数
- `gateway_tokens_prompt_total`: Prompt Token 数
- `gateway_tokens_completion_total`: Completion Token 数

### 健康检查

```bash
curl http://localhost:8080/actuator/health
curl http://localhost:8080/v1/health
```

## 项目架构

```
chat-ai-gateway/
├── gateway-common/                  # 公共模块
│   ├── common-core/                 # 核心工具
│   │   ├── exception/               # 异常定义
│   │   ├── constant/                # 常量
│   │   └── model/                   # 基础模型
│   ├── common-web/                  # Web 通用
│   │   ├── result/                  # 统一响应
│   │   ├── exception/               # 全局异常处理
│   │   └── interceptor/             # 拦截器
│   └── common-redis/                # Redis 封装
│
├── gateway-provider/                # Provider 适配层
│   ├── provider-api/                # SPI 接口
│   │   ├── AiProvider.java         # Provider 接口
│   │   └── model/                   # 统一模型
│   ├── provider-openai/             # OpenAI 实现
│   ├── provider-anthropic/          # Anthropic 实现
│   └── provider-chinese/            # 国内大模型
│
├── gateway-auth/                    # 认证授权
│   ├── filter/                      # 认证过滤器
│   └── config/                      # 安全配置
│
├── gateway-router/                  # 路由负载均衡
│   ├── loadbalance/                 # 负载均衡策略
│   └── ProviderRegistry.java        # Provider 注册表
│
├── gateway-ratelimit/               # 限流配额
│   ├── annotation/                  # 限流注解
│   ├── aspect/                      # 限流切面
│   └── core/                        # 限流实现
│
├── gateway-cache/                   # 响应缓存
│   ├── annotation/                  # 缓存注解
│   ├── aspect/                      # 缓存切面
│   └── core/                        # 缓存实现
│
├── gateway-monitor/                 # 监控审计
│   ├── metrics/                     # Prometheus 指标
│   └── interceptor/                 # 请求日志
│
└── gateway-app/                     # 主应用
    ├── controller/                  # API 控制器
    ├── config/                      # 配置
    └── resources/
        └── application.yml
```

## 扩展开发

### 新增 Provider

1. 在 `gateway-provider` 下创建新模块
2. 实现 `AiProvider` 接口或继承 `AbstractAiProvider`
3. 创建自动配置类
4. 在 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 中注册

示例:
```java
public class MyProvider extends AbstractAiProvider {
    @Override
    public String getType() { return "my-provider"; }

    @Override
    public ChatCompletionResponse chatCompletion(ChatCompletionRequest request) {
        // 实现逻辑
    }
}
```

## 未来规划与可扩展功能

详细的路线图请查看 [ROADMAP.md](./ROADMAP.md)。

### 近期可添加的功能

1. **熔断与重试**
   - Resilience4j 集成
   - 自动重试与回退策略

2. **更多 Provider**
   - 百度文心一言
   - 智谱 AI
   - Google Gemini
   - Azure OpenAI

3. **数据库集成**
   - PostgreSQL + JPA
   - API Key 管理
   - 请求审计日志

4. **管理后台**
   - 配置热更新
   - 实时监控面板
   - 使用量统计

5. **增强限流**
   - Token 级限流
   - 租户配额管理
   - 自适应限流

### 长期规划

- 智能路由（基于成本/性能/质量）
- 分布式追踪（OpenTelemetry）
- Kubernetes 部署与 Operator
- 多语言 SDK（Python/JS/Go）
- A/B 测试与实验平台

## 贡献

欢迎提交 Issue 和 Pull Request！如果你想贡献代码，可以从以下任务开始：

- 新增 Provider（文心一言、智谱等）
- 完善单元测试
- 补充文档和示例
- 性能优化

## License

MIT