Cherry Studio 客户端优化
All checks were successful
Build and Push OCI GenAI Gateway Docker Image / docker-build-push (push) Successful in 35s
All checks were successful
Build and Push OCI GenAI Gateway Docker Image / docker-build-push (push) Successful in 35s
This commit is contained in:
362
docs/OCI-SETUP-GUIDE.md
Normal file
362
docs/OCI-SETUP-GUIDE.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# 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！**
|
||||
Reference in New Issue
Block a user