# 配置管理系统

## 概述

本项目使用基于 Pydantic 的配置管理系统，提供：

- **配置分组**：按功能模块组织配置项
- **类型验证**：使用 Pydantic 进行配置验证
- **热重载**：运行时更新配置
- **环境变量支持**：从 .env 文件加载配置

## 配置分组

配置按功能模块分组：

| 分组 | 类名 | 说明 |
|------|------|------|
| 路径 | `PathConfig` | 文件路径配置 |
| LLM | `LLMConfig` | 大语言模型配置 |
| Embedding | `EmbeddingConfig` | 嵌入模型配置 |
| 检索 | `RetrievalConfig` | 检索参数配置 |
| 向量存储 | `VectorStoreConfig` | 向量数据库配置 |
| 日志 | `LogConfig` | 日志配置 |
| 系统 | `SystemConfig` | 系统提示词等 |

## 使用方式

### 基本用法

```python
from src.config import get_config_manager

# 获取配置管理器实例
config = get_config_manager()

# 分组访问
print(config.llm.model)              # deepseek-chat
print(config.retrieval.mode)         # hybrid
print(config.retrieval.top_k)        # 5
print(config.paths.knowledge_dir)    # 知识库目录
print(config.paths.vector_storage_dir)  # 向量存储目录

# API Key 获取（使用 get_api_key() 方法）
print(config.llm.get_api_key())        # 获取 LLM API Key
print(config.embedding.get_api_key())  # 获取 Embedding API Key
print(config.vector_store.get_api_key())  # 获取 Qdrant API Key

# 便捷属性
print(config.paths.log_file)         # 日志文件路径
print(config.vector_store.use_qdrant)  # 是否使用 Qdrant
```

### 配置热重载

```python
from src.config import reload_config

# 修改 .env 文件后，热重载配置
reload_config()
```

### 配置验证

```python
config = get_config_manager()

# 验证配置
errors = config.validate()
if errors:
    for error in errors:
        print(f"配置错误: {error}")
```

### 显示配置

```python
config = get_config_manager()

# 获取配置信息（隐藏敏感信息）
info = config.display()
for key, value in info.items():
    print(f"{key}: {value}")

# 显示敏感信息
info = config.display(show_secrets=True)
```

## 配置项说明

### LLM 配置

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| api_key | DEEPSEEK_API_KEY | "" | DeepSeek API Key |
| base_url | DEEPSEEK_BASE_URL | https://api.deepseek.com/v1 | API 基础 URL |
| model | DEEPSEEK_MODEL | deepseek-chat | 模型名称 |
| temperature | LLM_TEMPERATURE | 0.1 | 温度参数 (0.0-2.0) |

### Embedding 配置

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| api_key | SILICONFLOW_API_KEY | "" | SiliconFlow API Key |
| base_url | SILICONFLOW_BASE_URL | https://api.siliconflow.cn/v1 | API 基础 URL |
| model | EMBEDDING_MODEL | Qwen/Qwen3-Embedding-8B | 模型名称 |

### 检索配置

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| mode | RETRIEVAL_MODE | hybrid | 检索模式 (vector/bm25/hybrid) |
| top_k | DEFAULT_TOP_K | 5 | 检索文档数量 |
| bm25_top_k | BM25_TOP_K | 5 | BM25 检索数量 |
| chunk_size | CHUNK_SIZE | 1024 | 文本分块大小 |
| chunk_overlap | CHUNK_OVERLAP | 200 | 分块重叠大小 |
| bm25_language | BM25_LANGUAGE | chinese | BM25 分词语言 |

### 向量存储配置

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| type | USE_QDRANT | qdrant | 存储类型 (simple/qdrant) |
| qdrant_url | QDRANT_URL | "" | Qdrant 云服务 URL |
| qdrant_api_key | QDRANT_API_KEY | "" | Qdrant API Key |
| qdrant_collection_name | QDRANT_COLLECTION_NAME | knowledge_base | 集合名称 |

## 环境变量配置

创建 `.env` 文件：

```env
# LLM 配置
DEEPSEEK_API_KEY=sk-xxx
DEEPSEEK_MODEL=deepseek-chat
LLM_TEMPERATURE=0.1

# Embedding 配置
SILICONFLOW_API_KEY=sk-xxx
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-8B

# 检索配置
RETRIEVAL_MODE=hybrid
DEFAULT_TOP_K=5
CHUNK_SIZE=1024
CHUNK_OVERLAP=200

# Qdrant 配置
USE_QDRANT=true
QDRANT_URL=https://xxx.qdrant.io
QDRANT_API_KEY=xxx
QDRANT_COLLECTION_NAME=knowledge_base

# 日志配置
LOG_LEVEL=INFO
```

## 配置验证规则

1. **温度参数**：必须在 0.0 到 2.0 之间
2. **分块重叠**：必须小于分块大小
3. **检索模式**：必须是 vector、bm25 或 hybrid
4. **端口号**：必须在 1 到 65535 之间

## 最佳实践

1. **使用分组访问**：使用 `config.llm.model`、`config.retrieval.mode` 等分组方式访问配置
2. **API Key 获取**：使用 `config.llm.get_api_key()` 等方法获取敏感信息
3. **敏感信息**：API Key 等敏感信息使用环境变量配置，不要硬编码
4. **配置验证**：启动时调用 `config.validate()` 检查配置
5. **热重载**：修改配置后使用 `reload_config()` 而非重启服务
6. **路径访问**：使用 `config.paths.xxx` 访问各种路径配置
