citu_vanna/docs/llm_refactor_migration_guide.md

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

导入路径变更

旧的导入方式：

from customqianwen.Custom_QianwenAI_chat import QianWenAI_Chat
from customdeepseek.custom_deepseek_chat import DeepSeekChat
from customollama.ollama_chat import OllamaChat

新的导入方式：

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. 测试验证

运行测试确保功能正常：

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 可以验证重构是否成功。