# OCI GenAI to OpenAI API 网关

> 🚀 为 Oracle Cloud Infrastructure 的 Generative AI Service 提供 OpenAI 兼容的 REST API

[![License](https://img.shields.io/badge/license-UPL-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.0-green.svg)](https://fastapi.tiangolo.com/)

## 📖 简介

这是一个 FastAPI 服务，作为 OCI Generative AI 和 OpenAI API 之间的转换层，允许 OpenAI SDK 客户端无需修改代码即可与 OCI GenAI 模型交互。

## ✨ 主要特性

- 🔄 **OpenAI API 兼容**: 完全兼容 OpenAI SDK，无需修改现有代码
- 🤖 **动态模型发现**: 启动时自动从 OCI 获取所有可用模型
- 🌐 **多区域负载均衡**: 支持多个 OCI profiles 的 round-robin 负载均衡
- 🖼️ **多模态支持**: 支持文本、图像（Vision 模型）、Base64 编码等多种内容类型
- ⚡ **真实流式传输**: 真正的边缘到边缘流式响应，TTFB < 200ms
- 🔒 **安全性**: 自动过滤敏感信息（OCID、request-id、endpoint URLs）
- 🎯 **性能优化**: 客户端连接池机制，显著提升性能
- 🎨 **高级参数支持**: reasoning_effort 等参数
- 🍒 **Cherry Studio 优化**: 自动映射 thinking_budget，客户端名称识别

## 🚀 快速开始

### 前置要求

- Python 3.8+
- OCI 账号和 API 密钥
- OCI Generative AI 服务访问权限

### 🔧 自动配置 OCI 访问权限（推荐）

如果您还没有配置 OCI Generative AI 访问权限，可以使用我们提供的自动化脚本快速完成配置：

```bash
# 在 Oracle Cloud Shell 中运行
bash <(curl -sL https://gitea.bcde.io/wangdefa/oracle-openai/raw/branch/main/script/setup-oci-genai-access.sh)
```

脚本将自动创建：
- IAM 用户组（用于 Generative AI 访问）
- IAM 策略（授予必要权限）
- IAM 用户（用于 API 调用）

详细配置说明请参考：[OCI-SETUP-GUIDE.md](script/OCI-SETUP-GUIDE.md)

### 安装

1. **克隆仓库**
   ```bash
   git clone <repository-url>
   cd oracle-openai
   ```

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

3. **配置 OCI**

   创建或编辑 `~/.oci/config`:
   ```ini
   [DEFAULT]
   user=ocid1.user.oc1...
   fingerprint=aa:bb:cc:dd...
   key_file=~/.oci/oci_api_key.pem
   tenancy=ocid1.tenancy.oc1...
   region=us-chicago-1
   ```

4. **配置环境变量**

   复制 `.env.example` 到 `.env` 并编辑:
   ```bash
   cp .env.example .env
   # 编辑 .env 文件设置 API_KEYS 和其他配置
   ```

5. **运行服务**
   ```bash
   cd src
   python main.py
   ```

   服务将在 `http://localhost:8000` 启动

## 💻 使用示例

### 使用 cURL

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-oci-genai-default-key" \
  -d '{
    "model": "google.gemini-2.5-pro",
    "messages": [{"role": "user", "content": "你好！"}]
  }'
```

### 使用 Python OpenAI SDK

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-oci-genai-default-key",
    base_url="http://localhost:8000/v1"
)

response = client.chat.completions.create(
    model="google.gemini-2.5-pro",
    messages=[{"role": "user", "content": "你好！"}]
)

print(response.choices[0].message.content)
```

### 流式响应

```python
stream = client.chat.completions.create(
    model="google.gemini-2.5-pro",
    messages=[{"role": "user", "content": "从1数到10"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

### Vision 模型（多模态）

```python
response = client.chat.completions.create(
    model="google.gemini-2.5-pro",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "描述这张图片"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    }
                }
            ]
        }
    ]
)
```

## 🚀 高级功能

### 高级参数支持

网关支持高级参数来增强模型响应能力：

#### reasoning_effort - 推理深度控制

控制模型的推理深度，影响响应质量：

```python
response = client.chat.completions.create(
    model="google.gemini-2.5-pro",
    messages=[{"role": "user", "content": "Solve this complex problem"}],
    extra_body={"reasoning_effort": "high"}  # low, medium, high
)
```

详细说明请参考 [高级参数支持文档](docs/ADVANCED_PARAMETERS.md)。

### Cherry Studio 客户端优化

网关为 Cherry Studio 客户端提供了专属优化功能：

#### 自动映射 thinking_budget

Cherry Studio 的 `thinking_budget` 参数会自动映射到 OCI 的 `reasoning_effort`：

- thinking_budget ≤ 1760 → `reasoning_effort: low`
- 1760 < thinking_budget ≤ 16448 → `reasoning_effort: medium`
- thinking_budget > 16448 → `reasoning_effort: high`

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-oci-genai-default-key" \
  -H "x-title: Cherry Studio" \
  -d '{
    "model": "google.gemini-2.5-pro",
    "messages": [{"role": "user", "content": "Complex problem..."}],
    "extra_body": {
      "google": {
        "thinking_config": {
          "thinking_budget": 10000
        }
      }
    }
  }'
```

#### 客户端名称识别

通过 `x-title` 请求头识别客户端，便于日志追踪和调试：

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "x-title: Cherry Studio" \
  ...
```

详细说明请参考 [Cherry Studio 客户端优化文档](docs/CHERRY_STUDIO_OPTIMIZATION.md)。

## 📋 支持的端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/v1/models` | GET | 列出所有可用模型 |
| `/v1/chat/completions` | POST | 对话补全（支持流式） |
| `/v1/embeddings` | POST | 文本嵌入 |

## 🎨 支持的模型

服务启动时自动从 OCI 发现可用模型，包括：

- **Cohere**: command-r-plus, command-r-16k 等
- **Meta**: llama-3.1-405b, llama-3.1-70b, llama-3.2-90b-vision 等
- **Google**: gemini 系列
- **OpenAI**: gpt 系列
- **xAI**: grok 系列

使用 `GET /v1/models` 查看所有可用模型。

## ⚙️ 配置选项

### 关键环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `API_KEYS` | API 密钥列表（JSON 数组） | - |
| `OCI_CONFIG_PROFILE` | OCI 配置 profile（支持多个，逗号分隔） | `DEFAULT` |
| `OCI_AUTH_TYPE` | 认证类型 | `api_key` |
| `MAX_TOKENS` | 默认最大 token 数 | `4096` |
| `TEMPERATURE` | 默认温度参数 | `0.7` |
| `ENABLE_STREAMING` | 全局流式开关 | `true` |
| `LOG_LEVEL` | 日志级别 | `INFO` |

**📖 完整配置说明**：
- [环境变量配置文档](docs/ENVIRONMENT_VARIABLES.md) - 所有环境变量的详细说明、使用场景和配置示例
- [.env.example](.env.example) - 环境变量配置示例文件

## 🌐 多区域负载均衡

支持配置多个 OCI profiles 实现自动负载均衡：

```bash
# .env 文件
OCI_CONFIG_PROFILE=DEFAULT,CHICAGO,ASHBURN
```

系统将使用 round-robin 策略在不同区域之间分配请求。

## 🐳 Docker 部署

```bash
# 使用 docker-compose
docker-compose up

# 或使用 Docker
docker build -t oci-genai-gateway .
docker run -p 8000:8000 --env-file .env oci-genai-gateway
```

## 📚 文档

### 核心文档

- [环境变量配置说明](docs/ENVIRONMENT_VARIABLES.md) - 所有环境变量的详细说明和配置示例
- [.env.example](.env.example) - 环境变量配置示例文件

### 功能优化文档

- [高级参数支持](docs/ADVANCED_PARAMETERS.md) - reasoning_effort 参数详解
- [Cherry Studio 客户端优化](docs/CHERRY_STUDIO_OPTIMIZATION.md) - thinking_budget 映射和客户端识别
- [OCI 访问权限配置](docs/OCI-SETUP-GUIDE.md) - 自动化配置 OCI GenAI 访问权限

## 🔧 故障排除

### 常见问题

1. **模型未找到**
   - 检查模型 ID 拼写
   - 确认模型在您的 OCI 区域可用
   - 查看启动日志确认模型已加载

2. **认证失败**
   - 验证 `~/.oci/config` 配置正确
   - 检查 API 密钥文件权限：`chmod 600 ~/.oci/oci_api_key.pem`
   - 运行 `oci iam region list` 测试 OCI 配置

3. **429 速率限制错误**
   - 使用多个 profile 进行负载均衡
   - 等待 1-2 分钟后重试

## 🤝 贡献

欢迎贡献！请随时提交 issues 或 pull requests。

## 📄 许可证

本项目基于 UPL (Universal Permissive License) 开源，详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [FastAPI](https://fastapi.tiangolo.com/) - 现代、快速的 Web 框架
- [OCI Python SDK](https://github.com/oracle/oci-python-sdk) - Oracle Cloud Infrastructure SDK
- [OpenAI](https://openai.com/) - API 设计参考

---

**⭐ 如果这个项目对您有帮助，请给我们一个 Star！**