Complete AI Data Analysis Agent implementation with 95.7% test coverage
This commit is contained in:
212
docs/configuration_guide.md
Normal file
212
docs/configuration_guide.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 配置管理指南
|
||||
|
||||
## 概述
|
||||
|
||||
本系统提供了灵活的配置管理机制，支持通过环境变量、配置文件和代码三种方式进行配置。
|
||||
|
||||
## 配置方式
|
||||
|
||||
### 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`
|
||||
Reference in New Issue
Block a user