Wang Defa
9098c61c6c
All checks were successful
Build and Push OCI GenAI Gateway Docker Image / docker-build-push (push) Successful in 31s
364 lines
8.1 KiB
Markdown
364 lines
8.1 KiB
Markdown
# OCI Generative AI 访问配置指南
|
||
|
||
## 📖 概述
|
||
|
||
本指南将帮助您快速配置 Oracle Cloud Infrastructure (OCI) 以使用 Generative AI 服务。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方法一：使用自动化脚本（推荐）
|
||
|
||
#### 1. 在 Oracle Cloud Shell 中运行脚本
|
||
|
||
```bash
|
||
bash <(curl -sL https://gitea.bcde.io/wangdefa/oracle-openai/raw/branch/main/script/setup-oci-genai-access.sh)
|
||
```
|
||
|
||
#### 2. 按提示输入信息
|
||
|
||
脚本会询问您：
|
||
- **用户组名称**（默认: `GenAI-Users`）
|
||
- **用户名**（默认: `genai-api-user`）
|
||
- **策略名称**（默认: `GenAI-Access-Policy`）
|
||
|
||
您可以直接按回车使用默认值，或输入自定义名称。
|
||
|
||
#### 3. 脚本将自动完成以下操作
|
||
|
||
✅ 检查 OCI CLI 环境
|
||
✅ 创建 IAM 用户组
|
||
✅ 创建并配置策略
|
||
✅ 创建新用户
|
||
✅ 将用户添加到组
|
||
✅ 生成配置信息文件
|
||
|
||
#### 4. 完成配置
|
||
|
||
脚本执行完成后，会生成一个配置文件（如 `oci-genai-setup-20241209-143022.txt`），其中包含：
|
||
|
||
- 所有创建的资源 OCID
|
||
- 策略语句
|
||
- 详细的后续步骤说明
|
||
|
||
### 方法二：手动配置
|
||
|
||
#### 1. 创建用户组
|
||
|
||
```bash
|
||
oci iam group create \
|
||
--compartment-id <tenancy-ocid> \
|
||
--name "GenAI-Users" \
|
||
--description "用于访问 OCI Generative AI 服务的用户组"
|
||
```
|
||
|
||
#### 2. 创建策略
|
||
|
||
```bash
|
||
oci iam policy create \
|
||
--compartment-id <tenancy-ocid> \
|
||
--name "GenAI-Access-Policy" \
|
||
--description "允许 GenAI-Users 组访问 Generative AI 服务" \
|
||
--statements '["ALLOW GROUP GenAI-Users to manage generative-ai-family IN TENANCY"]'
|
||
```
|
||
|
||
#### 3. 创建用户
|
||
|
||
```bash
|
||
oci iam user create \
|
||
--compartment-id <tenancy-ocid> \
|
||
--name "genai-api-user" \
|
||
--description "用于通过 API 访问 OCI Generative AI 服务的用户"
|
||
```
|
||
|
||
#### 4. 添加用户到组
|
||
|
||
```bash
|
||
oci iam group add-user \
|
||
--user-id <user-ocid> \
|
||
--group-id <group-ocid>
|
||
```
|
||
|
||
## 🔑 创建 API Key
|
||
|
||
### 通过 OCI 控制台
|
||
|
||
1. 登录 [OCI 控制台](https://cloud.oracle.com)
|
||
|
||
2. 导航到：**Identity & Security** → **Users** → 选择您创建的用户
|
||
|
||
3. 点击左侧 **API Keys**
|
||
|
||
4. 点击 **Add API Key** 按钮
|
||
|
||
5. 选择 **Generate API Key Pair**
|
||
|
||
6. **下载私钥文件**（`oci_api_key.pem`）并妥善保管
|
||
|
||
7. **复制并保存公钥指纹**（fingerprint）
|
||
|
||
### 通过 OCI CLI（高级用户）
|
||
|
||
```bash
|
||
# 生成 API Key 对
|
||
mkdir -p ~/.oci
|
||
openssl genrsa -out ~/.oci/oci_api_key.pem 2048
|
||
chmod 600 ~/.oci/oci_api_key.pem
|
||
|
||
# 生成公钥
|
||
openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem
|
||
|
||
# 上传公钥到 OCI
|
||
oci iam user api-key upload \
|
||
--user-id <user-ocid> \
|
||
--key-file ~/.oci/oci_api_key_public.pem
|
||
```
|
||
|
||
## ⚙️ 配置 OCI CLI
|
||
|
||
### 1. 创建配置文件
|
||
|
||
创建或编辑 `~/.oci/config` 文件：
|
||
|
||
```ini
|
||
[DEFAULT]
|
||
user=ocid1.user.oc1..aaaaaaaa...
|
||
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
|
||
key_file=~/.oci/oci_api_key.pem
|
||
tenancy=ocid1.tenancy.oc1..aaaaaaaa...
|
||
region=us-chicago-1
|
||
```
|
||
|
||
**参数说明**：
|
||
- `user`: 用户的 OCID（从配置文件或控制台获取）
|
||
- `fingerprint`: API Key 的指纹（创建 API Key 时显示）
|
||
- `key_file`: 私钥文件路径
|
||
- `tenancy`: 租户的 OCID
|
||
- `region`: 您的 OCI 区域（如 `us-chicago-1`, `us-ashburn-1` 等）
|
||
|
||
### 2. 设置文件权限
|
||
|
||
```bash
|
||
chmod 600 ~/.oci/oci_api_key.pem
|
||
chmod 600 ~/.oci/config
|
||
```
|
||
|
||
### 3. 测试配置
|
||
|
||
```bash
|
||
# 测试 OCI CLI 配置
|
||
oci iam region list
|
||
|
||
# 测试 Generative AI 访问
|
||
oci generative-ai model list --compartment-id <tenancy-ocid>
|
||
```
|
||
|
||
如果命令执行成功并返回结果，说明配置正确。
|
||
|
||
## 🌍 支持的 OCI 区域
|
||
|
||
Generative AI 服务目前在以下区域可用：
|
||
|
||
| 区域代码 | 区域名称 | Endpoint |
|
||
|---------|----------|----------|
|
||
| `us-chicago-1` | US East (Chicago) | 推荐 |
|
||
| `us-ashburn-1` | US East (Ashburn) | 可用 |
|
||
| `uk-london-1` | UK South (London) | 可用 |
|
||
| `eu-frankfurt-1` | Germany Central (Frankfurt) | 可用 |
|
||
|
||
**注意**：请选择距离您最近或延迟最低的区域。
|
||
|
||
## 🔧 多区域配置（可选）
|
||
|
||
如果您需要访问多个区域或进行负载均衡，可以配置多个 profile：
|
||
|
||
```ini
|
||
[DEFAULT]
|
||
user=ocid1.user.oc1..aaaaaaaa...
|
||
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
|
||
key_file=~/.oci/oci_api_key.pem
|
||
tenancy=ocid1.tenancy.oc1..aaaaaaaa...
|
||
region=us-chicago-1
|
||
|
||
[CHICAGO]
|
||
user=ocid1.user.oc1..aaaaaaaa...
|
||
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
|
||
key_file=~/.oci/oci_api_key.pem
|
||
tenancy=ocid1.tenancy.oc1..aaaaaaaa...
|
||
region=us-chicago-1
|
||
|
||
[ASHBURN]
|
||
user=ocid1.user.oc1..aaaaaaaa...
|
||
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
|
||
key_file=~/.oci/oci_api_key.pem
|
||
tenancy=ocid1.tenancy.oc1..aaaaaaaa...
|
||
region=us-ashburn-1
|
||
```
|
||
|
||
然后在 Gateway 的 `.env` 文件中配置：
|
||
|
||
```bash
|
||
OCI_CONFIG_PROFILE=DEFAULT,CHICAGO,ASHBURN
|
||
```
|
||
|
||
## 🐳 配置 OCI GenAI Gateway
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd oracle-openai
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
复制并编辑环境变量文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件，设置：
|
||
|
||
```bash
|
||
# API Keys
|
||
API_KEYS=["sk-oci-genai-default-key","sk-your-custom-key"]
|
||
|
||
# OCI 配置
|
||
OCI_CONFIG_FILE=~/.oci/config
|
||
OCI_CONFIG_PROFILE=DEFAULT # 或多个: DEFAULT,CHICAGO,ASHBURN
|
||
OCI_AUTH_TYPE=api_key
|
||
|
||
# 其他配置（可选）
|
||
MAX_TOKENS=4096
|
||
TEMPERATURE=0.7
|
||
ENABLE_STREAMING=true
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
**使用 Python 直接运行**：
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 启动服务
|
||
cd src
|
||
python main.py
|
||
```
|
||
|
||
**使用 Docker**：
|
||
|
||
```bash
|
||
docker-compose up
|
||
```
|
||
|
||
### 4. 测试服务
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:8000/health
|
||
|
||
# 列出可用模型
|
||
curl http://localhost:8000/v1/models \
|
||
-H "Authorization: Bearer sk-oci-genai-default-key"
|
||
|
||
# 测试对话
|
||
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": "你好！"}]
|
||
}'
|
||
```
|
||
|
||
## ❓ 常见问题
|
||
|
||
### 1. 脚本执行失败：权限不足
|
||
|
||
**错误**：
|
||
```
|
||
ServiceError: Authorization failed or requested resource not found
|
||
```
|
||
|
||
**解决方案**：
|
||
- 确保您使用的账号具有管理员权限
|
||
- 或至少具有以下权限：
|
||
- `MANAGE groups IN TENANCY`
|
||
- `MANAGE users IN TENANCY`
|
||
- `MANAGE policies IN TENANCY`
|
||
|
||
### 2. 无法创建 API Key
|
||
|
||
**错误**：
|
||
```
|
||
The user already has the maximum allowed number of API keys (3)
|
||
```
|
||
|
||
**解决方案**：
|
||
- 删除不再使用的旧 API Key
|
||
- 或使用现有的 API Key
|
||
|
||
### 3. 策略不生效
|
||
|
||
**问题**：创建了策略但用户仍无法访问 Generative AI
|
||
|
||
**解决方案**：
|
||
- 等待 1-2 分钟让策略生效
|
||
- 确认用户已添加到正确的用户组
|
||
- 检查策略语句是否正确：
|
||
```
|
||
ALLOW GROUP GenAI-Users to manage generative-ai-family IN TENANCY
|
||
```
|
||
|
||
### 4. Region 不支持 Generative AI
|
||
|
||
**错误**：
|
||
```
|
||
Service generativeai is not available in region us-sanjose-1
|
||
```
|
||
|
||
**解决方案**：
|
||
- 切换到支持的区域（如 `us-chicago-1`, `us-ashburn-1`）
|
||
- 更新 `~/.oci/config` 中的 `region` 参数
|
||
|
||
### 5. 模型列表为空
|
||
|
||
**问题**：Gateway 启动时无法获取模型列表
|
||
|
||
**解决方案**：
|
||
- 确认 OCI 配置正确：`oci iam region list`
|
||
- 测试 Generative AI 访问：
|
||
```bash
|
||
oci generative-ai model list --compartment-id <tenancy-ocid>
|
||
```
|
||
- 检查区域是否支持 Generative AI
|
||
- 确认策略已生效
|
||
|
||
## 📚 相关文档
|
||
|
||
- [OCI Generative AI 官方文档](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)
|
||
- [OCI CLI 配置指南](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm)
|
||
- [OCI IAM 策略参考](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/policygetstarted.htm)
|
||
- [项目 README](README.md)
|
||
- [开发文档 CLAUDE.md](CLAUDE.md)
|
||
|
||
## 🆘 获取帮助
|
||
|
||
如果您遇到问题：
|
||
|
||
1. 查看自动生成的配置文件（`oci-genai-setup-*.txt`）
|
||
2. 检查 OCI 控制台中的资源状态
|
||
3. 查看 Gateway 日志：`tail -f logs/app.log`
|
||
4. 提交 GitHub Issue
|
||
|
||
## 📄 许可证
|
||
|
||
本项目基于 UPL (Universal Permissive License) 开源。
|
||
|
||
---
|
||
|
||
**⭐ 如果这个指南对您有帮助，请给项目一个 Star！**
|