oracle-openai/script/OCI-SETUP-GUIDE.md

OCI Generative AI 访问配置指南

📖 概述

本指南将帮助您快速配置 Oracle Cloud Infrastructure (OCI) 以使用 Generative AI 服务。

🚀 快速开始

方法一：使用自动化脚本（推荐）

1. 在 Oracle Cloud Shell 中运行脚本

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. 创建用户组

oci iam group create \
  --compartment-id <tenancy-ocid> \
  --name "GenAI-Users" \
  --description "用于访问 OCI Generative AI 服务的用户组"

2. 创建策略

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. 创建用户

oci iam user create \
  --compartment-id <tenancy-ocid> \
  --name "genai-api-user" \
  --description "用于通过 API 访问 OCI Generative AI 服务的用户"

4. 添加用户到组

oci iam group add-user \
  --user-id <user-ocid> \
  --group-id <group-ocid>

🔑 创建 API Key

通过 OCI 控制台

1. 登录 OCI 控制台

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（高级用户）

# 生成 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 文件：

[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. 设置文件权限

chmod 600 ~/.oci/oci_api_key.pem
chmod 600 ~/.oci/config

3. 测试配置

# 测试 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：

[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 文件中配置：

OCI_CONFIG_PROFILE=DEFAULT,CHICAGO,ASHBURN

🐳 配置 OCI GenAI Gateway

1. 克隆项目

git clone <repository-url>
cd oracle-openai

2. 配置环境变量

复制并编辑环境变量文件：

cp .env.example .env

编辑 .env 文件，设置：

# 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 直接运行：

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

# 启动服务
cd src
python main.py

使用 Docker：

docker-compose up

4. 测试服务

# 健康检查
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 访问：

  oci generative-ai model list --compartment-id <tenancy-ocid>
  

• 检查区域是否支持 Generative AI
• 确认策略已生效

📚 相关文档

• OCI Generative AI 官方文档
• OCI CLI 配置指南
• OCI IAM 策略参考
• 项目 README
• 开发文档 CLAUDE.md

🆘 获取帮助

如果您遇到问题：

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

📄 许可证

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

---

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