# RAG系统重构指南

## 概述

本项目已完成组件化重构，将原先单一的大型脚本文件拆分为多个功能模块，提高了代码的可维护性和可扩展性。

## 新的目录结构

```
src/
├── __init__.py                  # 包初始化
├── config/                      # 配置模块
│   ├── __init__.py
│   └── config.py               # 系统配置类
├── core/                        # 核心业务逻辑
│   ├── __init__.py
│   └── rag_system.py           # RAG系统核心实现
├── embeddings/                  # 嵌入模型
│   ├── __init__.py
│   └── siliconflow_embedding.py
├── tokenizers/                  # 分词器
│   ├── __init__.py
│   └── jieba_tokenizer.py
├── storage/                     # 存储管理
│   ├── __init__.py
│   ├── vector_store.py         # 向量存储管理
│   └── bm25_store.py           # BM25存储管理
├── utils/                       # 工具函数
│   ├── __init__.py
│   ├── logger.py               # 日志配置
│   └── patches.py              # 猴子补丁
└── mcp/                         # MCP服务器相关
    ├── __init__.py
    └── handlers/                # MCP处理器
        ├── __init__.py
        ├── tools_handler.py    # 工具处理器
        ├── resources_handler.py # 资源处理器
        └── prompts_handler.py  # 提示词处理器
```

## 模块说明

### 1. 配置模块 (`src/config/`)
- **config.py**: 集中管理所有系统配置参数
- 包含API密钥、模型配置、检索参数等

### 2. 核心模块 (`src/core/`)
- **rag_system.py**: RAG系统的核心实现
- 提供索引构建、查询、管理等功能
- 整合向量存储和BM25存储管理器

### 3. 嵌入模块 (`src/embeddings/`)
- **siliconflow_embedding.py**: SiliconFlow API的嵌入实现
- 支持批量和单个文本的向量化

### 4. 分词模块 (`src/tokenizers/`)
- **jieba_tokenizer.py**: 中文分词器实现
- 支持中英文混合文本分词
- 提供停用词过滤和词干提取

### 5. 存储模块 (`src/storage/`)
- **vector_store.py**: 向量存储管理器
  - 支持本地存储和Qdrant云存储
  - 提供统一的向量存储接口
- **bm25_store.py**: BM25存储管理器
  - 管理BM25检索器的创建、加载和持久化

### 6. 工具模块 (`src/utils/`)
- **logger.py**: 日志系统配置
- **patches.py**: 第三方库的补丁修复

### 7. MCP模块 (`src/mcp/`)
- **handlers/**: MCP协议处理器
  - **tools_handler.py**: 工具调用处理
  - **resources_handler.py**: 资源读取处理
  - **prompts_handler.py**: 提示词处理

## 新旧文件对照

| 原文件 | 新实现 | 说明 |
|--------|--------|------|
| `config.py` | `src/config/config.py` | 配置模块独立 |
| `rag_system.py` | `src/core/rag_system.py` | 核心逻辑拆分 |
| `siliconflow_embedding.py` | `src/embeddings/siliconflow_embedding.py` | 嵌入模块独立 |
| `jieba_tokenizer.py` | `src/tokenizers/jieba_tokenizer.py` | 分词器独立 |
| `cli.py` | `cli_new.py` | CLI使用新架构 |
| `mcp_server.py` | `mcp_server_new.py` | MCP服务器使用模块化处理器 |
| `mcp_http_server.py` | `mcp_http_server_new.py` | HTTP服务器使用模块化处理器 |

## 使用方法

### 使用新版本CLI

```bash
# 使用组件化版本的CLI
python cli_new.py index --dir ./my_knowledge_base
python cli_new.py query --question "你的问题"
python cli_new.py status
```

### 使用新版本MCP服务器

```bash
# 启动stdio MCP服务器
python mcp_server_new.py

# 启动HTTP MCP服务器
python mcp_http_server_new.py
```

### 在代码中使用

```python
# 方式1: 通过兼容层
from rag_system_new import RAGSystem, Config

rag = RAGSystem()
rag.build_index("./data")
result = rag.query("问题")

# 方式2: 直接导入模块
from src.core import RAGSystem
from src.config import Config

rag = RAGSystem(config=Config)
```

## 优势

### 1. 降低单一文件行数
- **原 rag_system.py**: 744行 → **新 src/core/rag_system.py**: 约500行
- **原 mcp_server.py**: 452行 → **新 mcp_server_new.py**: 约100行
- **原 cli.py**: 462行 → **新 cli_new.py**: 约460行（功能相同，导入更清晰）

### 2. 提高可维护性
- 每个模块职责单一，易于理解和修改
- 代码组织清晰，快速定位问题

### 3. 增强可扩展性
- 新增功能只需添加对应模块
- 易于替换组件（如更换embedding模型）

### 4. 便于测试
- 每个模块可独立测试
- 减少模块间耦合

### 5. 更好的代码复用
- 通用功能抽取到utils
- 存储逻辑独立管理

## 迁移建议

### 渐进式迁移

1. **测试阶段**: 使用 `*_new.py` 文件进行测试
2. **验证阶段**: 确保所有功能正常工作
3. **切换阶段**: 
   - 备份原文件
   - 将新版本文件重命名为原文件名
   - 删除旧文件

### 完全迁移步骤

```bash
# 1. 备份原文件
mkdir backup
cp config.py rag_system.py cli.py mcp_server.py mcp_http_server.py backup/

# 2. 使用新版本
mv cli_new.py cli.py
mv mcp_server_new.py mcp_server.py
mv mcp_http_server_new.py mcp_http_server.py
mv rag_system_new.py rag_system.py

# 3. 更新导入引用（如果需要）
# 所有使用原文件的代码将自动使用新的模块化实现
```

## 向后兼容性

新版本通过兼容层保持向后兼容：

- `rag_system_new.py` 提供与原 `rag_system.py` 相同的接口
- 现有代码无需修改即可使用新架构
- 所有公开API保持不变

## 测试建议

```bash
# 1. 测试CLI功能
python cli_new.py status
python cli_new.py index --dir ./test_data
python cli_new.py query -i

# 2. 测试MCP服务器
python mcp_server_new.py

# 3. 测试HTTP服务器
python mcp_http_server_new.py
```

## 未来改进方向

1. **添加单元测试**: 为每个模块编写测试用例
2. **依赖注入**: 使用依赖注入提高灵活性
3. **异步优化**: 进一步优化异步处理
4. **插件系统**: 支持插件式扩展功能
5. **配置验证**: 增强配置验证和错误提示

## 总结

组件化重构使代码更加模块化、可维护和可扩展。新架构保持了完整的向后兼容性，您可以安全地进行迁移测试和逐步切换。
