Cherry Studio 客户端优化

2025-12-10 17:40:43 +08:00
parent 0840f35408
commit 95722c97e4
10 changed files with 1515 additions and 69 deletions
--- a/docs/ENVIRONMENT_VARIABLES.md
+++ b/docs/ENVIRONMENT_VARIABLES.md
@@ -0,0 +1,750 @@
+# 环境变量配置说明
+
+本文档详细说明 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 设置管理