第一次提交
All checks were successful
Build and Push OCI GenAI Gateway Docker Image / docker-build-push (push) Successful in 32m3s
All checks were successful
Build and Push OCI GenAI Gateway Docker Image / docker-build-push (push) Successful in 32m3s
This commit is contained in:
240
README.md
Normal file
240
README.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# OCI GenAI to OpenAI API 网关
|
||||
|
||||
> 🚀 为 Oracle Cloud Infrastructure 的 Generative AI Service 提供 OpenAI 兼容的 REST API
|
||||
|
||||
[](LICENSE)
|
||||
[](https://www.python.org/downloads/)
|
||||
[](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）
|
||||
- 🎯 **性能优化**: 客户端连接池机制，显著提升性能
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 前置要求
|
||||
|
||||
- Python 3.8+
|
||||
- OCI 账号和 API 密钥
|
||||
- OCI Generative AI 服务访问权限
|
||||
|
||||
### 安装
|
||||
|
||||
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"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
## 📋 支持的端点
|
||||
|
||||
| 端点 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `/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` |
|
||||
|
||||
完整配置请参考 [.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
|
||||
```
|
||||
|
||||
## 📚 文档
|
||||
|
||||
- [CLAUDE.md](CLAUDE.md) - 完整的开发文档，包含架构说明、开发指南和调试技巧
|
||||
- [.env.example](.env.example) - 环境变量配置示例
|
||||
|
||||
## 🔧 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **模型未找到**
|
||||
- 检查模型 ID 拼写
|
||||
- 确认模型在您的 OCI 区域可用
|
||||
- 查看启动日志确认模型已加载
|
||||
|
||||
2. **认证失败**
|
||||
- 验证 `~/.oci/config` 配置正确
|
||||
- 检查 API 密钥文件权限：`chmod 600 ~/.oci/oci_api_key.pem`
|
||||
- 运行 `oci iam region list` 测试 OCI 配置
|
||||
|
||||
3. **429 速率限制错误**
|
||||
- 使用多个 profile 进行负载均衡
|
||||
- 等待 1-2 分钟后重试
|
||||
|
||||
更多故障排除信息请参考 [CLAUDE.md](CLAUDE.md#调试)
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎贡献！请随时提交 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！**
|
||||
Reference in New Issue
Block a user