wangdefa/oracle-openai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

新增 OCI 访问配置指南和自动化脚本
All checks were successful
Build and Push OCI GenAI Gateway Docker Image / docker-build-push (push) Successful in 31s
Details

Browse Source
This commit is contained in:
Wang Defa
2025-12-09 15:16:18 +08:00
parent 42222744c7
commit 9098c61c6c
5 changed files with 823 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

363
script/OCI-SETUP-GUIDE.md Normal file
View File

@@ -0,0 +1,363 @@
# 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！**

443
script/setup-oci-genai-access.sh Executable file
View File

@@ -0,0 +1,443 @@
#!/bin/bash
################################################################################
# OCI Generative AI 访问配置脚本
#
# 功能：
# 1. 创建用于 Generative AI 的用户组
# 2. 创建并配置 IAM 策略
# 3. 创建新用户并添加到组
# 4. 提供 API Key 创建指引
#
# 使用方法：
# bash setup-oci-genai-access.sh
#
# 环境要求：
# - Oracle Cloud Shell 或已配置 OCI CLI 的环境
################################################################################
set -e # 遇到错误立即退出
# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# 打印带颜色的消息
print_info() {
echo -e "${BLUE}ℹ️ $1${NC}"
}
print_success() {
echo -e "${GREEN}✅ $1${NC}"
}
print_warning() {
echo -e "${YELLOW}⚠️ $1${NC}"
}
print_error() {
echo -e "${RED}❌ $1${NC}"
}
print_header() {
echo ""
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${BLUE} $1${NC}"
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo ""
}
################################################################################
# 检查 OCI CLI 是否可用
################################################################################
check_oci_cli() {
print_header "检查环境"
if ! command -v oci &> /dev/null; then
print_error "未找到 OCI CLI，请确保您在 Oracle Cloud Shell 中运行此脚本"
exit 1
fi
print_success "OCI CLI 已安装"
# 检查 OCI CLI 配置
if ! oci iam region list &> /dev/null; then
print_error "OCI CLI 配置有误，请检查您的认证设置"
exit 1
fi
print_success "OCI CLI 配置正常"
}
################################################################################
# 获取租户信息
################################################################################
get_tenancy_info() {
print_header "获取租户信息"
TENANCY_OCID=$(oci iam availability-domain list --query 'data[0]."compartment-id"' --raw-output)
if [ -z "$TENANCY_OCID" ]; then
print_error "无法获取租户 OCID"
exit 1
fi
TENANCY_NAME=$(oci iam tenancy get --tenancy-id "$TENANCY_OCID" --query "data.name" --raw-output)
print_success "租户名称: $TENANCY_NAME"
print_info "租户 OCID: $TENANCY_OCID"
}
################################################################################
# 获取用户输入
################################################################################
get_user_input() {
print_header "配置信息"
# 默认值
DEFAULT_GROUP_NAME="GenAI-Users"
DEFAULT_USER_NAME="genai-api-user"
DEFAULT_POLICY_NAME="GenAI-Access-Policy"
echo ""
read -p "请输入用户组名称 (默认: $DEFAULT_GROUP_NAME): " GROUP_NAME
GROUP_NAME=${GROUP_NAME:-$DEFAULT_GROUP_NAME}
read -p "请输入用户名 (默认: $DEFAULT_USER_NAME): " USER_NAME
USER_NAME=${USER_NAME:-$DEFAULT_USER_NAME}
read -p "请输入策略名称 (默认: $DEFAULT_POLICY_NAME): " POLICY_NAME
POLICY_NAME=${POLICY_NAME:-$DEFAULT_POLICY_NAME}
echo ""
print_info "配置摘要："
echo " • 用户组: $GROUP_NAME"
echo " • 用户名: $USER_NAME"
echo " • 策略名: $POLICY_NAME"
echo ""
read -p "确认继续? (y/N): " CONFIRM
if [[ ! $CONFIRM =~ ^[Yy]$ ]]; then
print_warning "已取消操作"
exit 0
fi
}
################################################################################
# 创建用户组
################################################################################
create_group() {
print_header "创建用户组"
# 检查组是否已存在
EXISTING_GROUP=$(oci iam group list --all --query "data[?name=='$GROUP_NAME'].id | [0]" --raw-output 2>/dev/null || echo "")
if [ -n "$EXISTING_GROUP" ] && [ "$EXISTING_GROUP" != "null" ]; then
print_warning "用户组 '$GROUP_NAME' 已存在"
GROUP_OCID=$EXISTING_GROUP
print_info "使用现有用户组 OCID: $GROUP_OCID"
else
print_info "正在创建用户组 '$GROUP_NAME'..."
GROUP_OCID=$(oci iam group create \
--compartment-id "$TENANCY_OCID" \
--name "$GROUP_NAME" \
--description "OCI Generative AI Users Group" \
--query "data.id" \
--raw-output)
if [ -z "$GROUP_OCID" ]; then
print_error "创建用户组失败"
exit 1
fi
print_success "用户组创建成功"
print_info "用户组 OCID: $GROUP_OCID"
fi
}
################################################################################
# 创建策略
################################################################################
create_policy() {
print_header "创建 IAM 策略"
# 检查策略是否已存在
EXISTING_POLICY=$(oci iam policy list --compartment-id "$TENANCY_OCID" --all --query "data[?name=='$POLICY_NAME'].id | [0]" --raw-output 2>/dev/null || echo "")
if [ -n "$EXISTING_POLICY" ] && [ "$EXISTING_POLICY" != "null" ]; then
print_warning "策略 '$POLICY_NAME' 已存在"
POLICY_OCID=$EXISTING_POLICY
print_info "使用现有策略 OCID: $POLICY_OCID"
# 询问是否更新策略
read -p "是否更新现有策略? (y/N): " UPDATE_POLICY
if [[ $UPDATE_POLICY =~ ^[Yy]$ ]]; then
print_info "正在更新策略..."
oci iam policy update \
--policy-id "$POLICY_OCID" \
--statements "[\"ALLOW GROUP $GROUP_NAME to manage generative-ai-family IN TENANCY\"]" \
--force > /dev/null
print_success "策略更新成功"
fi
else
print_info "正在创建策略 '$POLICY_NAME'..."
POLICY_OCID=$(oci iam policy create \
--compartment-id "$TENANCY_OCID" \
--name "$POLICY_NAME" \
--description "Allow $GROUP_NAME group to manage Generative AI services" \
--statements "[\"ALLOW GROUP $GROUP_NAME to manage generative-ai-family IN TENANCY\"]" \
--query "data.id" \
--raw-output)
if [ -z "$POLICY_OCID" ]; then
print_error "创建策略失败"
exit 1
fi
print_success "策略创建成功"
print_info "策略 OCID: $POLICY_OCID"
fi
echo ""
print_info "策略语句："
echo " ALLOW GROUP $GROUP_NAME to manage generative-ai-family IN TENANCY"
}
################################################################################
# 创建用户
################################################################################
create_user() {
print_header "创建用户"
# 检查用户是否已存在
EXISTING_USER=$(oci iam user list --all --query "data[?name=='$USER_NAME'].id | [0]" --raw-output 2>/dev/null || echo "")
if [ -n "$EXISTING_USER" ] && [ "$EXISTING_USER" != "null" ]; then
print_warning "用户 '$USER_NAME' 已存在"
USER_OCID=$EXISTING_USER
print_info "使用现有用户 OCID: $USER_OCID"
else
print_info "正在创建用户 '$USER_NAME'..."
USER_OCID=$(oci iam user create \
--compartment-id "$TENANCY_OCID" \
--name "$USER_NAME" \
--description "User for accessing OCI Generative AI services via API" \
--query "data.id" \
--raw-output)
if [ -z "$USER_OCID" ]; then
print_error "创建用户失败"
exit 1
fi
print_success "用户创建成功"
print_info "用户 OCID: $USER_OCID"
fi
}
################################################################################
# 将用户添加到组
################################################################################
add_user_to_group() {
print_header "添加用户到组"
# 检查用户是否已在组中
IS_MEMBER=$(oci iam group list-users --group-id "$GROUP_OCID" --query "data[?\"user-id\"=='$USER_OCID'].\"user-id\" | [0]" --raw-output 2>/dev/null || echo "")
if [ -n "$IS_MEMBER" ] && [ "$IS_MEMBER" != "null" ]; then
print_warning "用户 '$USER_NAME' 已在组 '$GROUP_NAME' 中"
else
print_info "正在将用户 '$USER_NAME' 添加到组 '$GROUP_NAME'..."
oci iam group add-user \
--user-id "$USER_OCID" \
--group-id "$GROUP_OCID" > /dev/null
print_success "用户已成功添加到组"
fi
}
################################################################################
# 保存配置信息
################################################################################
save_config() {
CONFIG_FILE="oci-genai-setup-$(date +%Y%m%d-%H%M%S).txt"
cat > "$CONFIG_FILE" << EOF
═══════════════════════════════════════════════════════════════
OCI Generative AI 访问配置信息
═══════════════════════════════════════════════════════════════
创建时间: $(date '+%Y-%m-%d %H:%M:%S')
租户信息
──────────────────────────────────────────────────────────────
名称: $TENANCY_NAME
OCID: $TENANCY_OCID
用户组信息
──────────────────────────────────────────────────────────────
名称: $GROUP_NAME
OCID: $GROUP_OCID
策略信息
──────────────────────────────────────────────────────────────
名称: $POLICY_NAME
OCID: $POLICY_OCID
语句: ALLOW GROUP $GROUP_NAME to manage generative-ai-family IN TENANCY
用户信息
──────────────────────────────────────────────────────────────
名称: $USER_NAME
OCID: $USER_OCID
下一步操作
──────────────────────────────────────────────────────────────
1. 为用户创建 API Key:
- 登录 OCI 控制台
- 导航到: Identity & Security > Users > $USER_NAME
- 点击 "API Keys" > "Add API Key"
- 下载私钥文件并保存公钥指纹
2. 配置 OCI CLI:
- 创建或编辑 ~/.oci/config 文件
- 添加以下配置:
[DEFAULT]
user=$USER_OCID
fingerprint=<从控制台获取>
key_file=~/.oci/oci_api_key.pem
tenancy=$TENANCY_OCID
region=<您的区域，例如: us-chicago-1>
3. 测试配置:
oci iam region list
4. 使用 OCI GenAI Gateway:
- 克隆项目: git clone <repository-url>
- 配置环境变量 (参考 .env.example)
- 启动服务: cd src && python main.py
═══════════════════════════════════════════════════════════════
EOF
print_success "配置信息已保存到: $CONFIG_FILE"
}
################################################################################
# 显示后续步骤
################################################################################
show_next_steps() {
print_header "配置完成"
print_success "所有资源创建成功！"
echo ""
print_info "📋 后续步骤："
echo ""
echo "1️⃣ 创建 API Key"
echo " ┌─────────────────────────────────────────────────────────┐"
echo " │ • 登录 OCI 控制台: │"
echo " │ https://cloud.oracle.com │"
echo " │ │"
echo " │ • 导航到: │"
echo " │ Identity & Security > Users > $USER_NAME"
echo " │ │"
echo " │ • 点击左侧 \"API Keys\" │"
echo " │ │"
echo " │ • 点击 \"Add API Key\" 按钮 │"
echo " │ │"
echo " │ • 选择 \"Generate API Key Pair\" │"
echo " │ │"
echo " │ • 下载私钥文件 (oci_api_key.pem) │"
echo " │ │"
echo " │ • 复制并保存公钥指纹 (fingerprint) │"
echo " └─────────────────────────────────────────────────────────┘"
echo ""
echo "2️⃣ 配置 OCI CLI"
echo " ┌─────────────────────────────────────────────────────────┐"
echo " │ 创建或编辑 ~/.oci/config 文件: │"
echo " │ │"
echo " │ [DEFAULT] │"
echo " │ user=$USER_OCID"
echo " │ fingerprint=<从控制台复制的指纹> │"
echo " │ key_file=~/.oci/oci_api_key.pem │"
echo " │ tenancy=$TENANCY_OCID"
echo " │ region=us-chicago-1 # 根据实际区域修改 │"
echo " │ │"
echo " │ 设置私钥文件权限: │"
echo " │ chmod 600 ~/.oci/oci_api_key.pem │"
echo " └─────────────────────────────────────────────────────────┘"
echo ""
echo "3️⃣ 测试配置"
echo " ┌─────────────────────────────────────────────────────────┐"
echo " │ 运行以下命令验证配置: │"
echo " │ │"
echo " │ oci iam region list │"
echo " │ │"
echo " │ 如果配置正确，将显示可用区域列表 │"
echo " └─────────────────────────────────────────────────────────┘"
echo ""
echo "4️⃣ 部署 OCI GenAI Gateway"
echo " ┌─────────────────────────────────────────────────────────┐"
echo " │ • 克隆项目仓库 │"
echo " │ • 配置 .env 文件 (参考 .env.example) │"
echo " │ • 启动服务: │"
echo " │ cd src && python main.py │"
echo " │ │"
echo " │ 或使用 Docker: │"
echo " │ docker-compose up │"
echo " └─────────────────────────────────────────────────────────┘"
echo ""
print_info "📄 详细配置信息已保存到文件中，请妥善保管"
echo ""
}
################################################################################
# 主函数
################################################################################
main() {
clear
cat << "EOF"
╔═══════════════════════════════════════════════════════════════════════╗
║ ║
║ 🚀 OCI Generative AI 访问配置自动化脚本 ║
║ ║
║ 此脚本将自动创建以下资源: ║
║ • IAM 用户组 (Group) ║
║ • IAM 策略 (Policy) ║
║ • IAM 用户 (User) ║
║ ║
╚═══════════════════════════════════════════════════════════════════════╝
EOF
echo ""
# 执行配置步骤
check_oci_cli
get_tenancy_info
get_user_input
create_group
create_policy
create_user
add_user_to_group
save_config
show_next_steps
print_success "脚本执行完成！"
echo ""
}
# 执行主函数
main