python-services/Retrieve/README_ENV.md

# 混合配置说明

## 概述

本项目采用混合配置方式：
- **大部分配置**：从YAML配置文件加载（`app_config_dev.yaml` 或 `app_config_prod.yaml`）
- **敏感配置**：API密钥和base_url从环境变量加载，覆盖YAML文件中的值

## 环境变量列表

### 基础配置
- `ENVIRONMENT`: 环境类型，可选值：`dev`（开发环境）或 `prod`（生产环境），默认为 `dev`

### API密钥和Base URL配置（从环境变量加载）

#### QA LLM 主模型
- `QA_LLM_MAIN_API_KEY`: API密钥
- `QA_LLM_MAIN_BASE_URL`: API基础URL

#### QA LLM 备用模型
- `QA_LLM_BACKUP_API_KEY`: API密钥
- `QA_LLM_BACKUP_BASE_URL`: API基础URL

#### Rewrite LLM 备用模型 (GPT-4o)
- `REWRITE_LLM_BACKUP_API_KEY`: API密钥
- `REWRITE_LLM_BACKUP_BASE_URL`: API基础URL

#### Rewrite LLM 主模型
- `REWRITE_LLM_MAIN_API_KEY`: API密钥
- `REWRITE_LLM_MAIN_BASE_URL`: API基础URL

#### Web搜索服务
- `SERPER_API_KEY`: Serper API密钥（用于网络搜索）

## 其他配置（从YAML文件加载）

以下配置仍然从YAML文件加载，包括：
- 模型名称
- max_tokens
- temperature
- recall配置
- qa-topk配置
- qa-prompt-max-token配置
- chat配置

## 使用方法

### 1. 设置环境变量

```bash
# 设置环境
export ENVIRONMENT=prod

# 设置API密钥和base_url
export QA_LLM_MAIN_API_KEY=your-actual-api-key
export QA_LLM_MAIN_BASE_URL=https://your-api-endpoint.com

export REWRITE_LLM_BACKUP_API_KEY=your-gpt4o-api-key
export REWRITE_LLM_BACKUP_BASE_URL=https://api.openai.com/v1

# 设置Web搜索API密钥
export SERPER_API_KEY=your-serper-api-key

# ... 其他API配置
```

### 2. 在代码中使用

```python
from config.global_storage import get_model_config

# 获取配置
config = get_model_config()

# 使用配置（API密钥和base_url来自环境变量，其他来自YAML）
model_name = config['qa-llm']['main']['model']  # 来自YAML
api_key = config['qa-llm']['main']['api_key']   # 来自环境变量
base_url = config['qa-llm']['main']['base_url'] # 来自环境变量
```

## 配置优先级

1. **环境变量**：API密钥和base_url（最高优先级）
2. **YAML文件**：其他所有配置（基础配置）

## 优势

1. **安全性**: 敏感信息（API密钥）从环境变量加载，不会出现在代码或配置文件中
2. **灵活性**: 可以轻松切换不同环境的API端点
3. **维护性**: 大部分配置仍在YAML文件中，便于管理和版本控制
4. **部署友好**: 生产环境只需要设置环境变量即可

## 注意事项

1. 如果环境变量未设置，将使用YAML文件中的默认值
2. 确保 `.env` 文件已添加到 `.gitignore` 中
3. 生产环境建议使用环境变量而不是 `.env` 文件
4. YAML文件中的API密钥和base_url值会被环境变量覆盖
5. 对于Web搜索服务，如果未设置 `SERPER_API_KEY`，将使用代码中的默认密钥（不推荐用于生产环境）