wangdefa/oracle-openai

Fork 0

Files

Wang Defa 218070dc49

Build and Push OCI GenAI Gateway Docker Image / docker-build-push (push) Successful in 31s

Details

修正 README.md 中的文档链接和内容

2025-12-10 17:44:10 +08:00

8.7 KiB

Raw Permalink Blame History

OCI GenAI to OpenAI API 网关

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

📖 简介

这是一个 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 访问权限，可以使用我们提供的自动化脚本快速完成配置：

# 在 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

安装

克隆仓库

git clone <repository-url>
cd oracle-openai

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

配置 OCI

创建或编辑 ~/.oci/config:

[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

配置环境变量

复制 .env.example 到 .env 并编辑:

cp .env.example .env
# 编辑 .env 文件设置 API_KEYS 和其他配置

运行服务
```
cd src
python main.py
```
服务将在 http://localhost:8000 启动

💻 使用示例

使用 cURL

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

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)

流式响应

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 模型（多模态）

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 - 推理深度控制

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

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
)

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

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 请求头识别客户端，便于日志追踪和调试：

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

详细说明请参考 Cherry Studio 客户端优化文档。

📋 支持的端点

端点	方法	说明
`/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 - 环境变量配置示例文件

🌐 多区域负载均衡

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

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

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

🐳 Docker 部署

# 使用 docker-compose
docker-compose up

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

📚 文档

核心文档

环境变量配置说明 - 所有环境变量的详细说明和配置示例
.env.example - 环境变量配置示例文件

功能优化文档

Cherry Studio 客户端优化 - thinking_budget 映射和客户端识别
OCI 访问权限配置 - 自动化配置 OCI GenAI 访问权限

🔧 故障排除

常见问题

模型未找到
- 检查模型 ID 拼写
- 确认模型在您的 OCI 区域可用
- 查看启动日志确认模型已加载
认证失败
- 验证 ~/.oci/config 配置正确
- 检查 API 密钥文件权限：chmod 600 ~/.oci/oci_api_key.pem
- 运行 oci iam region list 测试 OCI 配置
429 速率限制错误
- 使用多个 profile 进行负载均衡
- 等待 1-2 分钟后重试

🤝 贡献

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

📄 许可证

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

🙏 致谢

FastAPI - 现代、快速的 Web 框架
OCI Python SDK - Oracle Cloud Infrastructure SDK
OpenAI - API 设计参考

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

8.7 KiB Raw Permalink Blame History Unescape Escape