# 配置管理指南

## 概述

本系统提供了灵活的配置管理机制，支持通过环境变量、配置文件和代码三种方式进行配置。

## 配置方式

### 1. 环境变量（推荐）

最简单的配置方式是使用 `.env` 文件：

```bash
# .env 文件示例
LLM_PROVIDER=openai
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4

AGENT_MAX_ROUNDS=20
AGENT_OUTPUT_DIR=output
TOOL_MAX_QUERY_ROWS=10000
```

系统会自动加载 `.env` 文件中的配置。

### 2. 配置文件

使用 JSON 格式的配置文件：

```bash
python -m src.cli data.csv -c config.json
```

配置文件示例（`config.json`）：

```json
{
  "llm": {
    "provider": "openai",
    "api_key": "your_api_key_here",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-4",
    "timeout": 120,
    "max_retries": 3,
    "temperature": 0.7
  },
  "performance": {
    "agent_max_rounds": 20,
    "tool_max_query_rows": 10000
  },
  "output": {
    "output_dir": "output",
    "log_level": "INFO"
  }
}
```

### 3. 代码配置

在代码中直接配置：

```python
from src.config import Config, LLMConfig, set_config

config = Config(
    llm=LLMConfig(
        api_key="your_api_key",
        model="gpt-4"
    )
)

set_config(config)
```

## 配置优先级

配置的优先级从高到低：

1. 代码中直接设置的配置
2. 命令行指定的配置文件（`-c config.json`）
3. 环境变量
4. `.env.local` 文件（本地开发，不提交到版本控制）
5. `.env` 文件
6. 默认值

## 配置项说明

### LLM 配置

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| provider | LLM_PROVIDER | openai | LLM 提供商（openai 或 gemini） |
| api_key | OPENAI_API_KEY / GEMINI_API_KEY | - | API 密钥（必需） |
| base_url | OPENAI_BASE_URL / GEMINI_BASE_URL | https://api.openai.com/v1 | API 基础 URL |
| model | OPENAI_MODEL / GEMINI_MODEL | gpt-4 | 模型名称 |
| timeout | LLM_TIMEOUT | 120 | 请求超时时间（秒） |
| max_retries | LLM_MAX_RETRIES | 3 | 最大重试次数 |
| temperature | LLM_TEMPERATURE | 0.7 | 温度参数 |
| max_tokens | LLM_MAX_TOKENS | null | 最大 token 数 |

### 性能配置

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| agent_max_rounds | AGENT_MAX_ROUNDS | 20 | ReAct 最大迭代次数 |
| agent_timeout | AGENT_TIMEOUT | 300 | Agent 执行超时（秒） |
| tool_max_query_rows | TOOL_MAX_QUERY_ROWS | 10000 | 工具查询最大行数 |
| tool_execution_timeout | TOOL_EXECUTION_TIMEOUT | 60 | 工具执行超时（秒） |
| data_max_rows | DATA_MAX_ROWS | 1000000 | 最大数据行数 |
| data_sample_threshold | DATA_SAMPLE_THRESHOLD | 1000000 | 数据采样阈值 |

### 输出配置

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| output_dir | AGENT_OUTPUT_DIR | output | 输出目录 |
| log_dir | LOG_DIR | output | 日志目录 |
| chart_dir | CHART_DIR | output/charts | 图表目录 |
| report_filename | REPORT_FILENAME | analysis_report.md | 报告文件名 |
| log_level | LOG_LEVEL | INFO | 日志级别 |
| log_to_file | LOG_TO_FILE | true | 是否记录到文件 |
| log_to_console | LOG_TO_CONSOLE | true | 是否输出到控制台 |

## 使用示例

### 示例 1：使用默认配置

```bash
# 确保 .env 文件中设置了 OPENAI_API_KEY
python -m src.cli data.csv
```

### 示例 2：使用自定义配置文件

```bash
python -m src.cli data.csv -c my_config.json
```

### 示例 3：覆盖环境变量

```bash
# 临时覆盖环境变量
OPENAI_MODEL=gpt-3.5-turbo python -m src.cli data.csv
```

### 示例 4：在代码中使用配置

```python
from src.config import get_config

# 获取全局配置
config = get_config()

# 访问配置项
print(f"使用模型: {config.llm.model}")
print(f"输出目录: {config.output.output_dir}")
```

## 配置验证

系统会在启动时自动验证配置：

- 检查必需的配置项（如 API key）
- 验证配置值的有效性
- 检查输出目录是否可写

如果配置无效，系统会报错并退出。

## 安全建议

1. **不要提交 API 密钥到版本控制**
   - 将 `.env` 添加到 `.gitignore`
   - 使用 `.env.example` 作为模板

2. **使用环境变量存储敏感信息**
   - 在生产环境中使用环境变量而不是配置文件
   - 使用密钥管理服务（如 AWS Secrets Manager）

3. **限制配置文件权限**
   - 确保配置文件只有必要的用户可以读取
   - 在 Unix 系统上使用 `chmod 600 config.json`

## 故障排查

### 问题：配置未生效

**解决方案**：
1. 检查配置优先级，确保没有被更高优先级的配置覆盖
2. 使用 `-v` 参数查看详细日志
3. 检查环境变量是否正确设置：`echo $OPENAI_API_KEY`

### 问题：API 密钥无效

**解决方案**：
1. 确认 API 密钥正确无误
2. 检查 API 密钥是否有足够的权限
3. 验证 base_url 是否正确

### 问题：配置文件加载失败

**解决方案**：
1. 检查 JSON 格式是否正确
2. 确认文件路径是否正确
3. 检查文件权限

## 参考

- 配置模块源码：`src/config.py`
- 环境变量加载器：`src/env_loader.py`
- 配置示例：`config.example.json`
- 环境变量示例：`.env.example`