# simple api

**Repository Path**: shijunbao1/simple-api

## Basic Information

- **Project Name**: simple api
- **Description**: 一个建简易的大模型api中转
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-01
- **Last Updated**: 2026-01-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SimpleAPI Library

## 项目简介
本项目实现了一个基于 **FastAPI** 的 OpenAI API 中转服务器，能够将请求转发至部署在 Ubuntu 上的 lmdeploy 服务（如 `http://192.168.3.95:8000`），并兼容 OpenAI 官方的 `/v1/chat/completions` 接口，支持普通返回和流式（Server‑Sent Events）返回。

项目支持多模型多服务器架构，具备负载均衡和故障转移功能，可通过简单的配置文件添加更多模型和服务器，无需修改代码。

## 负载均衡原理

### 什么是负载均衡？

负载均衡是一种将网络请求分配到多个服务器的技术，目的是优化资源使用、最大化吞吐量、最小化响应时间，并避免任何单一服务器过载。在我们的多模型多服务器架构中，负载均衡确保请求能够高效地分配到不同的服务器上。

### 为什么需要负载均衡？

1. **提高性能**：通过将请求分散到多个服务器，提高整体处理能力
2. **增强可靠性**：当某个服务器故障时，其他服务器可以接管请求
3. **扩展性**：可以轻松添加更多服务器来处理增长的需求
4. **优化资源利用**：根据服务器性能分配不同比例的请求

### 负载均衡策略

系统支持四种主要的负载均衡策略：

1. **轮询 (Round Robin)**：依次将请求分配给每个服务器，循环往复
2. **加权轮询 (Weighted Round Robin)**：根据服务器权重分配请求，权重高的服务器接收更多请求
3. **随机 (Random)**：随机选择一个服务器处理请求
4. **最少连接 (Least Requests)**：选择当前处理请求数最少的服务器

### 模型路由与负载均衡

在我们的多模型架构中，负载均衡与模型路由紧密相关：

- **模型只在单个服务器上**：系统会直接路由到该服务器，不触发负载均衡
- **模型在多个服务器上**：系统会根据配置的负载均衡策略在这些服务器之间分配请求

### 权重(Weight)详解

权重是控制请求分配比例的重要参数。例如，如果服务器A权重为1，服务器B权重为2，则请求分配比例为1:2。

权重配置可用于：
- **性能差异**：高性能服务器设置更高权重
- **地理位置**：本地服务器设置更高权重
- **成本考虑**：低成本服务器设置更高权重

### 负载均衡开关

系统提供了负载均衡开关功能，允许您根据需要启用或禁用负载均衡：

- **启用负载均衡 (enable_load_balancing: true)**：系统会根据配置的负载均衡策略（round_robin、weighted、random、least_requests）在多个服务器之间分配请求
- **禁用负载均衡 (enable_load_balancing: false)**：系统将始终选择第一个可用的服务器，不进行负载均衡

此功能适用于以下场景：
- **调试和测试**：禁用负载均衡可以更方便地调试特定服务器的问题
- **简单部署**：在只有一个服务器或不需要负载均衡的简单场景中，可以禁用此功能
- **故障排查**：当怀疑负载均衡导致问题时，可以临时禁用以确认问题根源

### 健康检查与故障转移

负载均衡系统会定期检查服务器健康状态：
1. **健康检查**：定期向每个服务器发送测试请求
2. **故障检测**：如果服务器连续多次未响应，标记为不健康
3. **自动排除**：不健康的服务器暂时从负载均衡中排除
4. **自动恢复**：不健康的服务器恢复后，自动重新加入负载均衡

### 负载均衡配置示例

```yaml
global:
  default_model: "gpt-3.5-turbo"
  load_balancing: "weighted"  # 使用加权轮询策略
  enable_load_balancing: true  # 是否启用负载均衡功能
  health_check_interval: 30   # 健康检查间隔
  max_retries: 2              # 最大重试次数

servers:
  - name: "server-1"
    host: "192.168.1.100"
    port: 8000
    timeout: 30
    weight: 1                 # 权重为1
    models:
      - name: "gpt-3.5-turbo"
      - name: "gpt-4"
  
  - name: "server-2"
    host: "192.168.1.101"
    port: 8000
    timeout: 30
    weight: 2                 # 权重为2，接收更多请求
    models:
      - name: "gpt-3.5-turbo"  # 与server-1共享此模型
      - name: "claude-3"
```

更多详细配置和示例请参考[多模型多服务器配置新手教程](多模型多服务器配置新手教程.md)。

## 快速开始

```bash
# 安装依赖
pip install -r requirements.txt

# 运行服务
uvicorn src.app:app --host 0.0.0.0 --port 8008
# 或者，设置工作进程为 10，实现并行中转
uvicorn src.app:app --host 0.0.0.0 --port 8008 --workers 10

## 依赖安装脚本
项目提供了 `install_deps.py` 脚本，可一次性自动安装所有运行、开发和测试所需的 Python 依赖。
使用方法：

```bash
python install_deps.py
```

脚本会列出需要安装的包数量，逐个执行 `pip install <package>`，并在完成后给出成功/失败统计。成功后即可直接启动服务或运行测试。
```
访问 `http://127.0.0.1:8008/hello` 将返回：

```json
{
  "message": "Hello, SimpleAPI!"
}
```

## 配置

### 新版配置格式（推荐）

新版配置支持自托管服务器和在线API服务器的混合使用：

```yaml
global:
  default_model: "gpt-3.5-turbo"
  load_balancing: "weighted"
  enable_load_balancing: true  # 是否启用负载均衡功能
  health_check_interval: 60
  max_retries: 2

servers:
  # 自托管服务器配置
  - name: "local-server"
    type: "self_hosted"
    host: "192.168.1.100"
    port: 8000
    timeout: 30
    weight: 1
    models:
      - name: "gpt-3.5-turbo"
      - name: "gpt-4"
  
  # 在线API服务器配置
  - name: "openai-api"
    type: "online_api"
    base_url: "https://api.openai.com"
    api_key_env: "OPENAI_API_KEY"  # 从环境变量读取API密钥
    timeout: 30
    weight: 1
    models:
      - name: "gpt-3.5-turbo"
      - name: "gpt-4"
  
  - name: "deepseek-api"
    type: "online_api"
    base_url: "https://api.deepseek.com"
    api_key_env: "DEEPSEEK_API_KEY"  # 从环境变量读取API密钥
    timeout: 30
    weight: 1
    models:
      - name: "deepseek-chat"
```

#### 服务器类型说明

1. **自托管服务器 (self_hosted)**
   - 需要提供 `host` 和 `port` 参数
   - 系统会自动构建 `base_url` 为 `http://{host}:{port}`
   - 适用于本地或内网部署的模型服务

2. **在线API服务器 (online_api)**
   - 需要提供 `base_url` 参数
   - 可以通过 `api_key` 直接提供API密钥，或通过 `api_key_env` 指定环境变量名
   - 系统会自动在请求中添加 `Authorization: Bearer <api_key>` 头
   - 适用于OpenAI、DeepSeek等在线API服务

#### API密钥配置

对于在线API服务器，提供两种API密钥配置方式：

##### 方式一：环境变量方式（推荐）

这种方式更安全，不会将密钥直接暴露在配置文件中。

1. **在配置文件中指定环境变量名**：
   ```yaml
   - name: "openai-api"
     type: "online_api"
     base_url: "https://api.openai.com"
     api_key_env: "OPENAI_API_KEY"  # 从环境变量读取API密钥
   ```

2. **在系统中设置环境变量**：
   
   Linux/Mac:
   ```bash
   export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
   # 或者将此行添加到 ~/.bashrc 或 ~/.zshrc 文件中使其永久生效
   ```
   
   Windows (PowerShell):
   ```powershell
   $env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
   # 或者使用以下命令使其永久生效
   [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxxxxxxxxxxxxxxxxxxxxxxx", "User")
   ```
   
   Windows (CMD):
   ```cmd
   set OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
   ```

##### 方式二：直接指定方式（不推荐，存在安全风险）

这种方式会将密钥直接暴露在配置文件中，仅建议在开发环境或测试环境中使用。

```yaml
- name: "openai-api"
  type: "online_api"
  base_url: "https://api.openai.com"
  api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxx"  # 直接在配置文件中指定
```

##### 两种方式的对比

| 特性 | 环境变量方式 | 直接指定方式 |
|------|-------------|-------------|
| 安全性 | 高（密钥不存储在配置文件中） | 低（密钥明文存储在配置文件中） |
| 易用性 | 需要额外设置环境变量 | 直接配置，无需额外步骤 |
| 灵活性 | 支持不同环境使用不同密钥 | 所有环境使用相同密钥 |
| 推荐场景 | 生产环境、多环境部署 | 开发环境、快速测试 |

### 旧版配置格式（兼容）

系统仍然支持旧版配置格式，会自动迁移到新格式：

```yaml
lmdeploy:
  base_url: "http://192.168.3.95:8000"
  timeout: 30
  model: "gpt-oss-120b"
logging:
  level: INFO
```

## API 密钥支持功能

本项目现在支持两种类型的服务器：自托管服务器和在线API服务器。在线API服务器可以使用API密钥进行身份验证。

### 服务器类型

1. **自托管服务器 (self_hosted)**
   - 适用于本地或内网部署的模型服务
   - 通过 `host` 和 `port` 参数指定服务器地址
   - 无需API密钥认证

2. **在线API服务器 (online_api)**
   - 适用于OpenAI、DeepSeek等在线API服务
   - 通过 `base_url` 参数指定API端点
   - 支持API密钥认证

### API密钥配置方式

对于在线API服务器，提供两种API密钥配置方式：

1. **环境变量方式（推荐）**
   ```yaml
   - name: "openai-api"
     type: "online_api"
     base_url: "https://api.openai.com"
     api_key_env: "OPENAI_API_KEY"  # 从环境变量读取API密钥
   ```
   然后在系统环境中设置：
   ```bash
   export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
   # 或在Windows中
   set OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
   ```

2. **直接指定方式（不推荐，存在安全风险）**
   ```yaml
   - name: "openai-api"
     type: "online_api"
     base_url: "https://api.openai.com"
     api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxx"  # 直接在配置文件中指定
   ```

### 常见在线API服务配置示例

#### OpenAI API
```yaml
- name: "openai"
  type: "online_api"
  base_url: "https://api.openai.com"
  api_key_env: "OPENAI_API_KEY"
  timeout: 30
  weight: 1
  models:
    - name: "gpt-3.5-turbo"
    - name: "gpt-4"
```

#### DeepSeek API
```yaml
- name: "deepseek"
  type: "online_api"
  base_url: "https://api.deepseek.com"
  api_key_env: "DEEPSEEK_API_KEY"
  timeout: 30
  weight: 1
  models:
    - name: "deepseek-chat"
    - name: "deepseek-coder"
```

#### Claude API
```yaml
- name: "claude"
  type: "online_api"
  base_url: "https://api.anthropic.com"
  api_key_env: "ANTHROPIC_API_KEY"
  timeout: 30
  weight: 1
  models:
    - name: "claude-3-opus"
    - name: "claude-3-sonnet"
    - name: "claude-3-haiku"
```

### 混合部署示例

您可以同时使用自托管服务器和在线API服务器：

```yaml
global:
  default_model: "gpt-3.5-turbo"
  load_balancing: "weighted"
  enable_load_balancing: true  # 是否启用负载均衡功能
  health_check_interval: 60
  max_retries: 2

servers:
  # 自托管服务器
  - name: "local-server"
    type: "self_hosted"
    host: "192.168.1.100"
    port: 8000
    timeout: 30
    weight: 2  # 更高权重，优先使用本地服务器
    models:
      - name: "gpt-3.5-turbo"
      - name: "gpt-4"

  # 在线API服务器作为备用
  - name: "openai-api"
    type: "online_api"
    base_url: "https://api.openai.com"
    api_key_env: "OPENAI_API_KEY"
    timeout: 30
    weight: 1  # 较低权重，作为备用
    models:
      - name: "gpt-3.5-turbo"
      - name: "gpt-4"
```

### API密钥安全最佳实践

1. **使用环境变量**：避免在配置文件中直接写入API密钥
2. **定期轮换密钥**：定期更新API密钥以提高安全性
3. **最小权限原则**：为API密钥分配最小必要权限
4. **监控使用情况**：定期检查API密钥的使用记录

## 添加模型和服务器实用小贴士

### 服务器类型选择指南

1. **self_hosted**：不需要API密钥的服务器
   - 适用于vLLM、LMDeploy、llamacpp等自托管模型服务
   - 只要host地址相同，可以合并在一个服务器配置中，也可以分开
   - 所有LMDeploy部署的模型都支持相同的请求格式，包括reasoning effort: high模式

2. **online_api**：需要API密钥的在线API服务

### 快速添加新模型步骤

每个模型作为一个整体添加，包含三个必要字段：
```yaml
- name: "模型名称"           # 模型的标识符
  created: Unix时间戳        # 创建时间，可以是任意Unix时间戳
  owned_by: "所有者"         # 模型的提供者/所有者
```

### 实际添加示例

在现有服务器下添加新模型：
```yaml
servers:
  - name: "local-lmdeploy"
    type: "self_hosted"
    host: "192.168.3.95"
    port: 8000
    timeout: 400
    weight: 2                 # 权重，值越大接收请求越多
    models:
      - name: "gpt-3.5-turbo"
        created: 1677610602
        owned_by: "openai"
      - name: "gpt-4"
        created: 1687882410
        owned_by: "openai"
      - name: "gpt-3.5-turbo-16k"  # 新增模型
        created: 1677610602        # Unix时间戳，不同模型可以使用相同值
        owned_by: "openai"
```

### 配置注意事项

1. **缩进一致性**：YAML文件对缩进敏感，确保新模型的缩进与现有模型一致
2. **Unix时间戳**：可以使用任意Unix时间戳，不同模型可以使用相同值
3. **模型名称**：应与服务器实际支持的模型名称一致
4. **权重设置**：通过weight参数控制服务器接收请求的比例，值越大接收请求越多

### 服务器合并与分离策略

对于同一host地址的多个模型服务，您可以选择：

1. **合并配置**（推荐）：
   ```yaml
   - name: "local-server"
     type: "self_hosted"
     host: "192.168.3.95"
     port: 8000
     models:
       - name: "model-1"
       - name: "model-2"
       - name: "model-3"
   ```

2. **分离配置**：
   ```yaml
   - name: "vllm-server"
     type: "self_hosted"
     host: "192.168.3.95"
     port: 8000
     models:
       - name: "model-1"
   
   - name: "lmdeploy-server"
     type: "self_hosted"
     host: "192.168.3.95"
     port: 8000
     models:
       - name: "model-2"
   ```

合并配置更简洁，分离配置便于为不同模型设置不同权重和超时参数。

## API 示例

```bash
curl -X POST http://127.0.0.1:8008/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-3.5-turbo",
        "messages": [{"role":"user","content":"你好"}],
        "stream": false
      }'
```

返回示例：

```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮助你的？"
      }
    }
  ]
}
```

## 项目结构

```
simpleapi/
├── src/
│   ├── __init__.py
│   └── app.py          # FastAPI 实现
├── tests/
│   ├── test_app.py     # 基础测试
│   └── test_proxy.py   # 代理路由测试
├── config.yaml
├── Dockerfile
├── .github/workflows/ci.yml
├── README.md
├── requirements.txt
└── setup.py
## Docker 部署

构建镜像：

```bash
docker build -t simpleapi .
```

使用 Docker Compose：

```bash
docker-compose up -d
```

直接运行容器：

```bash
docker run -d -p 8008:8008 simpleapi
```

## CI/CD

项目已配置 GitHub Actions 工作流，自动执行以下步骤：

1. **代码检查**：使用 `flake8` 检查代码风格。
2. **单元测试**：运行 `pytest`（包括异步测试）。
3. **镜像构建**：在每次推送或 PR 时构建 Docker 镜像。

工作流文件位于 `.github/workflows/ci.yml`，如需自定义可直接编辑该文件。

## 错误映射

`src/proxy.py` 中的 `forward_to_lmdeploy` 已实现将 lmdeploy 返回的 HTTP 错误转换为 OpenAI 兼容的错误结构：

```json
{
  "error": {
    "message": "错误详情",
    "type": "lmdeploy_error",
    "code": 500
  }
}
```

未捕获的异常会返回：

```json
{
  "error": {
    "message": "异常信息",
    "type": "internal_error"
  }
}
```

这样，调用方可以统一处理错误响应，保持与官方 OpenAI API 的兼容性。
```

## 运行测试

```bash
pytest -q
```
## Docker

构建镜像：

```bash
docker build -t simpleapi .
```

运行容器：

```bash
docker run -d -p 8008:8008 simpleapi
```

使用 `docker-compose.yml`：

```bash
docker-compose up -d
```

## 许可证

MIT License