oracle-openai/docs/ENVIRONMENT_VARIABLES.md

环境变量配置说明

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

📋 目录

• 快速配置
• API 设置
• 认证设置
• OCI 配置
• 模型设置
• 嵌入设置
• 流式响应设置
• 日志设置
• 配置示例
• 常见配置场景

快速配置

1. 复制示例配置文件：

   cp .env.example .env
   

2. 编辑 .env 文件，至少配置以下必需项：

   API_KEYS=["sk-your-secret-key"]
   OCI_CONFIG_PROFILE=DEFAULT
   

3. 确保 OCI 配置文件存在：

   cat ~/.oci/config
   

API 设置

API_TITLE

• 说明：API 服务的标题，显示在 OpenAPI 文档中
• 类型：字符串
• 默认值：OCI GenAI to OpenAI API Gateway
• 示例：

  API_TITLE=My AI Gateway
  

API_VERSION

• 说明：API 服务的版本号
• 类型：字符串
• 默认值：0.0.1
• 示例：

  API_VERSION=1.0.0
  

API_PREFIX

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

  API_PREFIX=/v1
  

API_PORT

• 说明：服务监听端口
• 类型：整数
• 默认值：8000
• 范围：1-65535
• 示例：

  API_PORT=8080
  

API_HOST

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

  API_HOST=127.0.0.1
  

DEBUG

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

  DEBUG=true
  

认证设置

API_KEYS

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

  # 单个密钥
  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 使用的配置文件位置
• 配置文件格式：

  [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
  

• 示例：

  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 字段
• 示例：

  # 单配置
  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
• 示例：

  OCI_AUTH_TYPE=api_key
  OCI_AUTH_TYPE=instance_principal
  

OCI_CONNECT_TIMEOUT

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

  OCI_CONNECT_TIMEOUT=10
  OCI_CONNECT_TIMEOUT=30  # 网络较慢时
  

OCI_READ_TIMEOUT

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

  OCI_READ_TIMEOUT=360
  OCI_READ_TIMEOUT=600  # 处理长文档时
  

GENAI_ENDPOINT

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

  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
• 注意：实际限制取决于具体模型
• 示例：

  MAX_TOKENS=4096
  MAX_TOKENS=8192  # 长对话场景
  

TEMPERATURE

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

  TEMPERATURE=0.7
  TEMPERATURE=0.0  # 事实性问答
  TEMPERATURE=1.2  # 创意写作
  

嵌入设置

EMBED_TRUNCATE

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

  EMBED_TRUNCATE=END
  EMBED_TRUNCATE=START
  

流式响应设置

ENABLE_STREAMING

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

  ENABLE_STREAMING=true
  ENABLE_STREAMING=false  # 调试或批处理时
  

STREAM_CHUNK_SIZE

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

  STREAM_CHUNK_SIZE=1024
  STREAM_CHUNK_SIZE=512  # 更频繁的更新
  

日志设置

LOG_LEVEL

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

  LOG_LEVEL=INFO
  LOG_LEVEL=DEBUG  # 开发调试
  

LOG_REQUESTS

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

  LOG_REQUESTS=false
  LOG_REQUESTS=true  # 调试 API 集成时
  

LOG_RESPONSES

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

  LOG_RESPONSES=false
  LOG_RESPONSES=true  # 调试响应格式时
  

LOG_FILE

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

  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
• 示例：

  LOG_FILE_MAX_SIZE=10
  LOG_FILE_MAX_SIZE=50  # 高流量场景
  

LOG_FILE_BACKUP_COUNT

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

  LOG_FILE_BACKUP_COUNT=5
  LOG_FILE_BACKUP_COUNT=10  # 需要更长的历史记录
  

配置示例

开发环境配置

# 开发环境 - 本地调试
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

生产环境配置

# 生产环境 - 多区域负载均衡
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 容器配置

# 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 实例配置

# 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: 单区域简单部署

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

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

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: 调试和开发

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

场景 4: 高性能生产环境

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

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）

示例：

# .env 文件中
LOG_LEVEL=INFO

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

配置验证

检查配置是否生效

启动服务后查看日志：

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 格式错误

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

2. 布尔值格式错误

   # 错误
   DEBUG=True
   ENABLE_STREAMING=yes
   
   # 正确
   DEBUG=true
   ENABLE_STREAMING=true
   

3. 路径错误

   # 错误（相对路径不明确）
   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. 查看启动日志确认配置加载

连接超时

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

日志文件无法创建

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

# 检查权限
chmod 755 logs

参考资料

• .env.example - 完整的配置示例文件
• OCI SDK 配置 - OCI 配置文件格式
• FastAPI Settings - FastAPI 设置管理