vibe_data_ana/docs/configuration_guide.md

配置管理指南

概述

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

配置方式

1. 环境变量（推荐）

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

# .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 格式的配置文件：

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

配置文件示例（config.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. 代码配置

在代码中直接配置：

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：使用默认配置

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

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

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

示例 3：覆盖环境变量

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

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

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