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

## 🆘 获取帮助

如果您遇到问题：

1. 查看自动生成的配置文件（`oci-genai-setup-*.txt`）
2. 检查 OCI 控制台中的资源状态
3. 查看 Gateway 日志：`tail -f logs/app.log`
4. 提交 GitHub Issue

## 📄 许可证

本项目基于 UPL (Universal Permissive License) 开源。

---

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