# LLM重构迁移指南

## 概述

本次重构将原本分散在不同目录的LLM实现（千问、DeepSeek、Ollama）重构为统一的架构，通过提取公共基类来减少代码重复，提高可维护性。

## 重构内容

### 新的目录结构

```
customllm/
├── __init__.py
├── base_llm_chat.py          # 公共基类
├── qianwen_chat.py           # 千问实现
├── deepseek_chat.py          # DeepSeek实现
└── ollama_chat.py            # Ollama实现
```

### 类名变更

| 原类名 | 新类名 | 位置 |
|--------|--------|------|
| `QianWenAI_Chat` | `QianWenChat` | `customllm.qianwen_chat` |
| `DeepSeekChat` | `DeepSeekChat` | `customllm.deepseek_chat` |
| `OllamaChat` | `OllamaChat` | `customllm.ollama_chat` |

### 导入路径变更

#### 旧的导入方式：
```python
from customqianwen.Custom_QianwenAI_chat import QianWenAI_Chat
from customdeepseek.custom_deepseek_chat import DeepSeekChat
from customollama.ollama_chat import OllamaChat
```

#### 新的导入方式：
```python
from customllm.qianwen_chat import QianWenChat
from customllm.deepseek_chat import DeepSeekChat
from customllm.ollama_chat import OllamaChat
```

## 重构优势

### 1. 代码复用
- 提取了公共方法到 `BaseLLMChat` 基类
- 消除了大量重复代码
- 统一了接口和行为

### 2. 维护性提升
- 公共逻辑修改只需要在一个地方
- 新增LLM实现只需要继承基类并实现少量方法
- 代码结构更清晰

### 3. 功能完整性
所有LLM实现现在都包含完整的功能：
- SQL生成和验证
- 中文问题生成
- 图表代码生成
- 问题合并功能
- 错误SQL提示功能

## 公共方法列表

`BaseLLMChat` 基类包含以下公共方法：

### 消息格式化
- `system_message(message: str) -> dict`
- `user_message(message: str) -> dict`
- `assistant_message(message: str) -> dict`

### SQL相关
- `generate_sql(question: str, **kwargs) -> str`
- `generate_question(sql: str, **kwargs) -> str`
- `get_sql_prompt(...) -> list`

### 图表相关
- `generate_plotly_code(...) -> str`
- `should_generate_chart(df) -> bool`

### 对话相关
- `chat_with_llm(question: str, **kwargs) -> str`
- `generate_rewritten_question(...) -> str`

### 配置相关
- `_load_error_sql_prompt_config() -> bool`

## 子类特有功能

### QianWenChat
- 支持 `enable_thinking` 功能
- 流式处理支持
- 千问特定的模型选择逻辑

### DeepSeekChat
- DeepSeek API集成
- 简化的模型选择

### OllamaChat
- 本地Ollama服务集成
- `test_connection()` 方法
- HTTP请求处理

## 迁移步骤

### 1. 更新导入语句
将所有使用旧LLM类的文件中的导入语句更新为新的路径。

### 2. 更新类名引用
如果代码中直接引用了类名，需要更新为新的类名。

### 3. 测试验证
运行测试确保功能正常：
```bash
python test_refactor.py
```

## 向后兼容性

- `common/vanna_combinations.py` 已更新使用新的LLM实现
- 所有Vanna组合类保持相同的接口
- 配置参数保持不变

## 注意事项

1. **配置兼容性**：所有原有的配置参数都保持兼容
2. **功能完整性**：所有原有功能都已迁移到新架构
3. **性能影响**：重构不会影响性能，反而可能因为代码优化而提升
4. **扩展性**：新架构更容易添加新的LLM提供商

## 故障排除

### 导入错误
如果遇到导入错误，检查：
1. 是否使用了正确的导入路径
2. 是否更新了类名引用
3. 是否有循环导入问题

### 功能缺失
如果发现某些功能缺失：
1. 检查是否在基类中实现
2. 检查子类是否正确继承
3. 查看是否需要特定的配置

## 测试验证

重构包含完整的测试验证：
- 导入测试
- 继承关系测试
- 方法存在性测试
- Vanna组合类测试

运行 `python test_refactor.py` 可以验证重构是否成功。