oracle-openai/docs/ENVIRONMENT_VARIABLES.md

# 环境变量配置说明

本文档详细说明 OCI GenAI 网关支持的所有环境变量及其配置方法。

## 📋 目录

- [快速配置](#快速配置)
- [API 设置](#api-设置)
- [认证设置](#认证设置)
- [OCI 配置](#oci-配置)
- [模型设置](#模型设置)
- [嵌入设置](#嵌入设置)
- [流式响应设置](#流式响应设置)
- [日志设置](#日志设置)
- [配置示例](#配置示例)
- [常见配置场景](#常见配置场景)

## 快速配置

1. 复制示例配置文件：
   ```bash
   cp .env.example .env
   ```

2. 编辑 `.env` 文件，至少配置以下必需项：
   ```bash
   API_KEYS=["sk-your-secret-key"]
   OCI_CONFIG_PROFILE=DEFAULT
   ```

3. 确保 OCI 配置文件存在：
   ```bash
   cat ~/.oci/config
   ```

## API 设置

### API_TITLE

- **说明**：API 服务的标题，显示在 OpenAPI 文档中
- **类型**：字符串
- **默认值**：`OCI GenAI to OpenAI API Gateway`
- **示例**：
  ```bash
  API_TITLE=My AI Gateway
  ```

### API_VERSION

- **说明**：API 服务的版本号
- **类型**：字符串
- **默认值**：`0.0.1`
- **示例**：
  ```bash
  API_VERSION=1.0.0
  ```

### API_PREFIX

- **说明**：API 路由前缀，符合 OpenAI API 规范
- **类型**：字符串
- **默认值**：`/v1`
- **可选值**：任何有效的 URL 路径
- **注意**：不建议修改，以保持与 OpenAI SDK 的兼容性
- **示例**：
  ```bash
  API_PREFIX=/v1
  ```

### API_PORT

- **说明**：服务监听端口
- **类型**：整数
- **默认值**：`8000`
- **范围**：1-65535
- **示例**：
  ```bash
  API_PORT=8080
  ```

### API_HOST

- **说明**：服务监听地址
- **类型**：字符串
- **默认值**：`0.0.0.0`（监听所有网络接口）
- **可选值**：
  - `0.0.0.0` - 监听所有接口（生产环境）
  - `127.0.0.1` - 仅本地访问（开发环境）
  - 特定 IP 地址
- **示例**：
  ```bash
  API_HOST=127.0.0.1
  ```

### DEBUG

- **说明**：启用调试模式
- **类型**：布尔值
- **默认值**：`false`
- **可选值**：`true` / `false`
- **影响**：
  - 启用时会显示详细的错误堆栈
  - 自动重载代码变更
  - 启用 FastAPI 的交互式文档
- **注意**：生产环境应设置为 `false`
- **示例**：
  ```bash
  DEBUG=true
  ```

## 认证设置

### API_KEYS

- **说明**：API 密钥列表，用于客户端认证
- **类型**：JSON 数组
- **默认值**：`["sk-oci-genai-default-key"]`
- **格式**：JSON 数组字符串
- **用途**：客户端通过 `Authorization: Bearer <key>` 头进行认证
- **安全建议**：
  - 使用强密钥（至少 32 个字符）
  - 定期轮换密钥
  - 不同环境使用不同的密钥
  - 不要将密钥提交到版本控制系统
- **示例**：
  ```bash
  # 单个密钥
  API_KEYS=["sk-prod-a1b2c3d4e5f6g7h8"]

  # 多个密钥（支持不同的客户端）
  API_KEYS=["sk-admin-key123","sk-user-key456","sk-app-key789"]
  ```

## OCI 配置

### OCI_CONFIG_FILE

- **说明**：OCI 配置文件路径
- **类型**：字符串（文件路径）
- **默认值**：`~/.oci/config`
- **用途**：指定 OCI SDK 使用的配置文件位置
- **配置文件格式**：
  ```ini
  [DEFAULT]
  user=ocid1.user.oc1...
  fingerprint=aa:bb:cc:dd...
  key_file=~/.oci/oci_api_key.pem
  tenancy=ocid1.tenancy.oc1...
  region=us-chicago-1
  ```
- **示例**：
  ```bash
  OCI_CONFIG_FILE=~/.oci/config
  OCI_CONFIG_FILE=/custom/path/to/oci_config
  ```

### OCI_CONFIG_PROFILE

- **说明**：OCI 配置文件中的 profile 名称
- **类型**：字符串（支持逗号分隔的多个值）
- **默认值**：`DEFAULT`
- **用途**：
  - 单个 profile：使用指定的 OCI 配置
  - 多个 profiles：自动 round-robin 负载均衡
- **要求**：每个 profile 必须包含 `region` 和 `tenancy` 字段
- **示例**：
  ```bash
  # 单配置
  OCI_CONFIG_PROFILE=DEFAULT

  # 多配置（负载均衡）
  OCI_CONFIG_PROFILE=DEFAULT,CHICAGO,ASHBURN

  # 跨区域配置
  OCI_CONFIG_PROFILE=US_WEST,US_EAST,EU_FRANKFURT
  ```

### OCI_AUTH_TYPE

- **说明**：OCI 认证类型
- **类型**：字符串
- **默认值**：`api_key`
- **可选值**：
  - `api_key` - 使用 API 密钥认证（推荐用于本地开发）
  - `instance_principal` - 使用实例主体认证（推荐用于 OCI 实例）
- **使用场景**：
  - **api_key**：本地开发、Docker 容器、非 OCI 环境
  - **instance_principal**：OCI Compute 实例、Container Engine、Functions
- **示例**：
  ```bash
  OCI_AUTH_TYPE=api_key
  OCI_AUTH_TYPE=instance_principal
  ```

### OCI_CONNECT_TIMEOUT

- **说明**：OCI API 连接超时时间（秒）
- **类型**：整数
- **默认值**：`10`
- **范围**：1-300
- **用途**：限制建立与 OCI API 连接的最大时间
- **调优建议**：
  - 网络稳定：保持默认值（10 秒）
  - 网络不稳定：增加到 20-30 秒
  - 快速失败：减少到 5 秒
- **示例**：
  ```bash
  OCI_CONNECT_TIMEOUT=10
  OCI_CONNECT_TIMEOUT=30  # 网络较慢时
  ```

### OCI_READ_TIMEOUT

- **说明**：OCI API 读取超时时间（秒）
- **类型**：整数
- **默认值**：`360`（6 分钟）
- **范围**：30-600
- **用途**：限制等待 OCI API 响应的最大时间
- **调优建议**：
  - 简单查询：120 秒
  - 复杂对话：300-360 秒
  - 长文档处理：600 秒
- **注意**：设置过小可能导致长时间运行的请求超时
- **示例**：
  ```bash
  OCI_READ_TIMEOUT=360
  OCI_READ_TIMEOUT=600  # 处理长文档时
  ```

### GENAI_ENDPOINT

- **说明**：专用模型端点（可选）
- **类型**：字符串（URL）
- **默认值**：无（自动根据 region 构建）
- **用途**：指定自定义的 OCI GenAI 端点
- **使用场景**：
  - 使用专用端点
  - 测试环境
  - 企业私有部署
- **注意**：通常不需要设置，系统会自动使用正确的端点
- **示例**：
  ```bash
  GENAI_ENDPOINT=https://your-dedicated-endpoint.oraclecloud.com
  ```

## 模型设置

### MAX_TOKENS

- **说明**：默认最大 token 数
- **类型**：整数
- **默认值**：`4096`
- **范围**：1-模型最大限制
- **用途**：当客户端未指定 `max_tokens` 时使用
- **不同模型的限制**：
  - Cohere Command R+：128k
  - Meta Llama 3.1 405B：128k
  - Google Gemini 2.5 Pro：2M
- **注意**：实际限制取决于具体模型
- **示例**：
  ```bash
  MAX_TOKENS=4096
  MAX_TOKENS=8192  # 长对话场景
  ```

### TEMPERATURE

- **说明**：默认温度参数
- **类型**：浮点数
- **默认值**：`0.7`
- **范围**：0.0-2.0
- **用途**：控制生成文本的随机性
- **效果**：
  - 0.0：确定性输出（适合事实查询）
  - 0.7：平衡创造性和准确性（默认）
  - 1.0-2.0：更有创造性（适合创意写作）
- **示例**：
  ```bash
  TEMPERATURE=0.7
  TEMPERATURE=0.0  # 事实性问答
  TEMPERATURE=1.2  # 创意写作
  ```

## 嵌入设置

### EMBED_TRUNCATE

- **说明**：嵌入文本截断策略
- **类型**：字符串
- **默认值**：`END`
- **可选值**：
  - `END` - 保留文本开头，截断末尾
  - `START` - 保留文本末尾，截断开头
- **用途**：当输入文本超过模型限制时的处理方式
- **使用场景**：
  - **END**：搜索查询、文档摘要（重点在开头）
  - **START**：对话历史、日志分析（重点在结尾）
- **示例**：
  ```bash
  EMBED_TRUNCATE=END
  EMBED_TRUNCATE=START
  ```

## 流式响应设置

### ENABLE_STREAMING

- **说明**：全局流式响应开关
- **类型**：布尔值
- **默认值**：`true`
- **可选值**：`true` / `false`
- **用途**：控制是否允许流式响应
- **行为**：
  - `true`：允许流式响应（客户端需设置 `stream=true`）
  - `false`：强制禁用流式响应（即使客户端设置 `stream=true`）
- **使用场景**：
  - 启用：交互式聊天、实时响应
  - 禁用：批处理、API 集成测试
- **注意**：设置为 `false` 会覆盖客户端的流式请求
- **示例**：
  ```bash
  ENABLE_STREAMING=true
  ENABLE_STREAMING=false  # 调试或批处理时
  ```

### STREAM_CHUNK_SIZE

- **说明**：模拟流式响应的分块大小（字符数）
- **类型**：整数
- **默认值**：`1024`
- **范围**：100-4096
- **用途**：仅在 OCI 返回非流式响应时使用（fallback 模式）
- **调优建议**：
  - 快速网络：1024-2048
  - 慢速网络：512-1024
  - 视觉效果优先：256-512
- **注意**：不影响真实流式响应的性能
- **示例**：
  ```bash
  STREAM_CHUNK_SIZE=1024
  STREAM_CHUNK_SIZE=512  # 更频繁的更新
  ```

## 日志设置

### LOG_LEVEL

- **说明**：日志级别
- **类型**：字符串
- **默认值**：`INFO`
- **可选值**：
  - `DEBUG` - 详细调试信息（包含所有日志）
  - `INFO` - 一般信息（推荐生产环境）
  - `WARNING` - 警告信息
  - `ERROR` - 错误信息
  - `CRITICAL` - 严重错误
- **使用场景**：
  - 开发环境：`DEBUG`
  - 生产环境：`INFO` 或 `WARNING`
  - 最小日志：`ERROR`
- **示例**：
  ```bash
  LOG_LEVEL=INFO
  LOG_LEVEL=DEBUG  # 开发调试
  ```

### LOG_REQUESTS

- **说明**：启用请求详细日志
- **类型**：布尔值
- **默认值**：`false`
- **可选值**：`true` / `false`
- **用途**：记录所有传入请求的详细信息
- **包含内容**：
  - HTTP 方法和 URL
  - 查询参数
  - 请求头（敏感信息自动过滤）
  - 请求体（JSON 格式化）
- **性能影响**：轻微（主要是日志写入）
- **安全性**：自动过滤 API 密钥等敏感信息
- **示例**：
  ```bash
  LOG_REQUESTS=false
  LOG_REQUESTS=true  # 调试 API 集成时
  ```

### LOG_RESPONSES

- **说明**：启用响应详细日志
- **类型**：布尔值
- **默认值**：`false`
- **可选值**：`true` / `false`
- **用途**：记录所有发出响应的详细信息
- **包含内容**：
  - HTTP 状态码
  - 响应处理时间
  - 响应头
  - 响应体（JSON 格式化）
- **注意**：流式响应不会记录完整响应体
- **示例**：
  ```bash
  LOG_RESPONSES=false
  LOG_RESPONSES=true  # 调试响应格式时
  ```

### LOG_FILE

- **说明**：日志文件路径
- **类型**：字符串（文件路径）
- **默认值**：`./logs/app.log`
- **用途**：指定日志文件保存位置
- **行为**：
  - 如果未设置，仅输出到控制台
  - 如果设置，同时输出到文件和控制台
- **注意**：目录必须存在或有创建权限
- **示例**：
  ```bash
  LOG_FILE=./logs/app.log
  LOG_FILE=/var/log/oci-genai/app.log
  ```

### LOG_FILE_MAX_SIZE

- **说明**：单个日志文件最大大小（MB）
- **类型**：整数
- **默认值**：`10`
- **范围**：1-1000
- **用途**：日志文件轮转的大小限制
- **行为**：超过限制时自动创建新文件
- **建议值**：
  - 低流量：10 MB
  - 中等流量：50 MB
  - 高流量：100-200 MB
- **示例**：
  ```bash
  LOG_FILE_MAX_SIZE=10
  LOG_FILE_MAX_SIZE=50  # 高流量场景
  ```

### LOG_FILE_BACKUP_COUNT

- **说明**：保留的备份日志文件数量
- **类型**：整数
- **默认值**：`5`
- **范围**：0-100
- **用途**：控制日志文件轮转时保留的历史文件数
- **存储计算**：总空间 = MAX_SIZE × (BACKUP_COUNT + 1)
- **示例**：
  ```bash
  LOG_FILE_BACKUP_COUNT=5
  LOG_FILE_BACKUP_COUNT=10  # 需要更长的历史记录
  ```

## 配置示例

### 开发环境配置

```bash
# 开发环境 - 本地调试
DEBUG=true
LOG_LEVEL=DEBUG
LOG_REQUESTS=true
LOG_RESPONSES=true

API_PORT=8000
API_HOST=127.0.0.1

API_KEYS=["sk-dev-key-123"]
OCI_CONFIG_PROFILE=DEFAULT
OCI_AUTH_TYPE=api_key

MAX_TOKENS=4096
TEMPERATURE=0.7

ENABLE_STREAMING=true
STREAM_CHUNK_SIZE=512

LOG_FILE=./logs/dev.log
LOG_FILE_MAX_SIZE=10
LOG_FILE_BACKUP_COUNT=3
```

### 生产环境配置

```bash
# 生产环境 - 多区域负载均衡
DEBUG=false
LOG_LEVEL=INFO
LOG_REQUESTS=false
LOG_RESPONSES=false

API_PORT=8000
API_HOST=0.0.0.0

# 使用强密钥
API_KEYS=["sk-prod-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"]

# 多区域配置
OCI_CONFIG_PROFILE=DEFAULT,CHICAGO,ASHBURN
OCI_AUTH_TYPE=api_key

# 超时配置
OCI_CONNECT_TIMEOUT=15
OCI_READ_TIMEOUT=360

# 模型配置
MAX_TOKENS=4096
TEMPERATURE=0.7

# 流式配置
ENABLE_STREAMING=true
STREAM_CHUNK_SIZE=1024

# 日志配置
LOG_FILE=/var/log/oci-genai/app.log
LOG_FILE_MAX_SIZE=50
LOG_FILE_BACKUP_COUNT=10
```

### Docker 容器配置

```bash
# Docker 环境
DEBUG=false
LOG_LEVEL=INFO

API_PORT=8000
API_HOST=0.0.0.0

API_KEYS=["sk-docker-key-abc123"]
OCI_CONFIG_FILE=/app/.oci/config
OCI_CONFIG_PROFILE=DEFAULT
OCI_AUTH_TYPE=api_key

# 适当的超时设置
OCI_CONNECT_TIMEOUT=20
OCI_READ_TIMEOUT=360

ENABLE_STREAMING=true

# 容器内日志路径
LOG_FILE=/app/logs/app.log
LOG_FILE_MAX_SIZE=20
LOG_FILE_BACKUP_COUNT=5
```

### OCI 实例配置

```bash
# OCI Compute 实例 - 使用实例主体认证
DEBUG=false
LOG_LEVEL=INFO

API_PORT=8000
API_HOST=0.0.0.0

API_KEYS=["sk-instance-key-xyz789"]

# 使用实例主体认证
OCI_AUTH_TYPE=instance_principal
# 注意：使用实例主体时不需要 OCI_CONFIG_FILE

ENABLE_STREAMING=true

LOG_FILE=/var/log/oci-genai/app.log
LOG_FILE_MAX_SIZE=50
LOG_FILE_BACKUP_COUNT=10
```

## 常见配置场景

### 场景 1: 单区域简单部署

```bash
API_KEYS=["sk-simple-key"]
OCI_CONFIG_PROFILE=DEFAULT
OCI_AUTH_TYPE=api_key
LOG_LEVEL=INFO
```

### 场景 2: 多区域高可用部署

```bash
API_KEYS=["sk-ha-key-primary","sk-ha-key-backup"]
OCI_CONFIG_PROFILE=US_EAST,US_WEST,EU_FRANKFURT
OCI_AUTH_TYPE=api_key
OCI_CONNECT_TIMEOUT=20
OCI_READ_TIMEOUT=360
LOG_LEVEL=WARNING
```

### 场景 3: 调试和开发

```bash
DEBUG=true
LOG_LEVEL=DEBUG
LOG_REQUESTS=true
LOG_RESPONSES=true
API_HOST=127.0.0.1
STREAM_CHUNK_SIZE=256
```

### 场景 4: 高性能生产环境

```bash
DEBUG=false
LOG_LEVEL=WARNING
LOG_REQUESTS=false
LOG_RESPONSES=false
OCI_CONFIG_PROFILE=DEFAULT,REGION2,REGION3
ENABLE_STREAMING=true
MAX_TOKENS=8192
OCI_READ_TIMEOUT=600
LOG_FILE_MAX_SIZE=100
LOG_FILE_BACKUP_COUNT=20
```

### 场景 5: 批处理/API 测试

```bash
ENABLE_STREAMING=false
MAX_TOKENS=2048
TEMPERATURE=0.0
LOG_LEVEL=INFO
LOG_REQUESTS=true
LOG_RESPONSES=true
```

## 环境变量优先级

配置加载顺序（后者覆盖前者）：

1. 应用默认值（代码中定义）
2. `.env` 文件
3. 系统环境变量
4. OCI 配置文件（`~/.oci/config`）

**示例**：

```bash
# .env 文件中
LOG_LEVEL=INFO

# 命令行覆盖
LOG_LEVEL=DEBUG python main.py
```

## 配置验证

### 检查配置是否生效

启动服务后查看日志：

```bash
cd src
python main.py
```

查看启动日志确认配置：

```
2025-12-10 10:00:00 - INFO - Starting OCI GenAI Gateway
2025-12-10 10:00:00 - INFO - API Port: 8000
2025-12-10 10:00:00 - INFO - OCI Profiles: DEFAULT, CHICAGO
2025-12-10 10:00:00 - INFO - Streaming: Enabled
2025-12-10 10:00:00 - INFO - Log Level: INFO
```

### 常见配置错误

1. **API_KEYS 格式错误**
   ```bash
   # 错误
   API_KEYS=sk-key-123

   # 正确
   API_KEYS=["sk-key-123"]
   ```

2. **布尔值格式错误**
   ```bash
   # 错误
   DEBUG=True
   ENABLE_STREAMING=yes

   # 正确
   DEBUG=true
   ENABLE_STREAMING=true
   ```

3. **路径错误**
   ```bash
   # 错误（相对路径不明确）
   OCI_CONFIG_FILE=oci/config

   # 正确
   OCI_CONFIG_FILE=~/.oci/config
   OCI_CONFIG_FILE=/absolute/path/to/config
   ```

## 安全建议

1. **保护 API 密钥**
   - 使用强密钥（至少 32 个字符）
   - 不要将 `.env` 文件提交到版本控制
   - 定期轮换密钥

2. **生产环境设置**
   - `DEBUG=false`
   - `LOG_LEVEL=INFO` 或 `WARNING`
   - `LOG_REQUESTS=false`
   - `LOG_RESPONSES=false`

3. **日志管理**
   - 定期清理旧日志
   - 限制日志文件大小
   - 确保日志不包含敏感信息

## 故障排除

### 配置未生效

1. 检查 `.env` 文件是否在正确位置
2. 确认环境变量名称拼写正确
3. 检查值的格式（JSON、布尔值等）
4. 查看启动日志确认配置加载

### 连接超时

```bash
# 增加超时时间
OCI_CONNECT_TIMEOUT=30
OCI_READ_TIMEOUT=600
```

### 日志文件无法创建

```bash
# 检查目录是否存在
mkdir -p logs

# 检查权限
chmod 755 logs
```

## 参考资料

- [.env.example](../.env.example) - 完整的配置示例文件
- [OCI SDK 配置](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm) - OCI 配置文件格式
- [FastAPI Settings](https://fastapi.tiangolo.com/advanced/settings/) - FastAPI 设置管理