238 lines
7.2 KiB
Markdown
238 lines
7.2 KiB
Markdown
# GaussDB SQL Expert 7B
|
||
|
||
**[English README](README.md)**
|
||
|
||
基于 Qwen2.5-Coder-7B-Instruct 微调的企业级数据库智能助手，专精 SQL 生成、调优、迁移、诊断等数据库领域任务。
|
||
|
||
## 模型概述
|
||
|
||
| 项目 | 详情 |
|
||
|------|------|
|
||
| 基座模型 | [Qwen/Qwen2.5-Coder-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct) |
|
||
| 参数量 | 7.6B (Dense) |
|
||
| 微调方法 | LoRA (rank=64, alpha=128, target=all linear layers) |
|
||
| 可训参数 | 161M (2.08%) |
|
||
| 训练数据 | 29,863 条 ShareGPT 多轮对话 + 1,571 条验证 |
|
||
| 训练硬件 | 1x NVIDIA H100 80GB |
|
||
| 训练耗时 | 3.5 小时 |
|
||
| 训练框架 | [LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory) v0.9.4 |
|
||
| 精度 | BF16 |
|
||
|
||
## 核心能力
|
||
|
||
- **Text2SQL**: 自然语言转 SQL，支持窗口函数、递归 CTE、MERGE、子查询等复杂语法
|
||
- **SQL 调优**: 索引失效分析、执行计划解读、参数配置优化建议
|
||
- **SQL 迁移**: Oracle / MySQL / SQL Server → GaussDB 语法自动转换 (50+ 差异点)
|
||
- **错误诊断**: 死锁、WAL 膨胀、连接耗尽、OOM 等 20+ 常见故障场景
|
||
- **SQL 解释**: 复杂查询的逻辑拆解与可读性分析
|
||
- **边界安全**: 危险操作拦截、信息不足追问、超范围拒绝
|
||
|
||
**支持 9 种主流数据库**: GaussDB, Oracle, MySQL, PostgreSQL, SQL Server, PolarDB, 达梦(DM), 金仓(KingBase), Sybase
|
||
|
||
## 评测结果
|
||
|
||
使用 100 道自动化评测题（每类 20 道），关键词匹配评分：
|
||
|
||
| 维度 | 得分 | 说明 |
|
||
|------|------|------|
|
||
| Text2SQL | 20/20 (100%) | 窗口函数、CTE、MERGE、分页等全部正确 |
|
||
| SQL 调优 | 18/20 (90%) | 索引失效、隐式转换、参数调优等 |
|
||
| SQL 迁移 | 20/20 (100%) | Oracle/MySQL/SQL Server → GaussDB 转换 |
|
||
| 错误诊断 | 20/20 (100%) | 死锁、WAL、OOM、连接耗尽等 |
|
||
| 边界安全 | 16/20 (80%) | 危险操作告警、超范围拒绝 |
|
||
| **综合** | **94/100 (94%)** | |
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Python >= 3.9
|
||
- PyTorch >= 2.0
|
||
- GPU 显存 >= 16GB（推荐）或 CPU（较慢）
|
||
- 磁盘空间 ~15GB（存放模型权重）
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
# 1. 安装基础依赖
|
||
pip install torch transformers accelerate
|
||
|
||
# 2.（可选）安装 Flash Attention 2，在 NVIDIA GPU 上加速推理
|
||
pip install flash-attn --no-build-isolation
|
||
```
|
||
|
||
### 下载模型
|
||
|
||
首次使用 `from_pretrained()` 时会自动下载模型，也可以手动提前下载：
|
||
|
||
```bash
|
||
# 方式一：huggingface-cli（推荐）
|
||
pip install huggingface_hub
|
||
huggingface-cli download lanfers/gaussdb-sql-expert-7b --local-dir ./gaussdb-sql-expert-7b
|
||
|
||
# 方式二：git-lfs
|
||
git lfs install
|
||
git clone https://huggingface.co/lanfers/gaussdb-sql-expert-7b
|
||
|
||
# 方式三：Python 脚本
|
||
python -c "
|
||
from huggingface_hub import snapshot_download
|
||
snapshot_download('lanfers/gaussdb-sql-expert-7b', local_dir='./gaussdb-sql-expert-7b')
|
||
"
|
||
```
|
||
|
||
> **国内用户加速下载**：如果 HuggingFace 下载较慢，可使用镜像站：
|
||
> ```bash
|
||
> HF_ENDPOINT=https://hf-mirror.com huggingface-cli download lanfers/gaussdb-sql-expert-7b --local-dir ./gaussdb-sql-expert-7b
|
||
> ```
|
||
|
||
### 使用本地模型推理
|
||
|
||
如果已手动下载到本地，将代码中的 `model_path` 改为本地路径即可：
|
||
|
||
```python
|
||
model_path = "./gaussdb-sql-expert-7b" # 本地路径
|
||
# model_path = "lanfers/gaussdb-sql-expert-7b" # 或直接从 HuggingFace 加载
|
||
```
|
||
|
||
### Python 推理
|
||
|
||
```python
|
||
import torch
|
||
from transformers import AutoModelForCausalLM, AutoTokenizer
|
||
|
||
model_path = "lanfers/gaussdb-sql-expert-7b"
|
||
device = "cuda" # 或 "mps" (Mac) / "cpu"
|
||
|
||
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
|
||
model = AutoModelForCausalLM.from_pretrained(
|
||
model_path,
|
||
torch_dtype=torch.float16,
|
||
device_map=device,
|
||
trust_remote_code=True,
|
||
)
|
||
model.eval()
|
||
|
||
messages = [
|
||
{"role": "system", "content": "你是一个专业的数据库专家助手，精通 Oracle, MySQL, PostgreSQL, GaussDB, PolarDB, 达梦(DM), 金仓(KingBase), Sybase, SQL Server。"},
|
||
{"role": "user", "content": "数据库类型: GaussDB 505 集中式\n\n查询每个部门工资最高的前3名员工，显示部门名、员工名、工资和排名。"},
|
||
]
|
||
|
||
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
|
||
inputs = tokenizer(text, return_tensors="pt").to(device)
|
||
|
||
with torch.no_grad():
|
||
outputs = model.generate(
|
||
**inputs,
|
||
max_new_tokens=1024,
|
||
temperature=0.7,
|
||
do_sample=True,
|
||
top_p=0.8,
|
||
repetition_penalty=1.05,
|
||
)
|
||
|
||
response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
|
||
print(response)
|
||
```
|
||
|
||
### 示例输出
|
||
|
||
**输入**: 查询每个部门工资最高的前3名员工
|
||
|
||
**输出**:
|
||
```sql
|
||
SELECT dept_name, emp_name, salary, rk
|
||
FROM (
|
||
SELECT d.dept_name, e.emp_name, e.salary,
|
||
DENSE_RANK() OVER(PARTITION BY e.dept_id ORDER BY e.salary DESC) AS rk
|
||
FROM employees e
|
||
JOIN departments d ON e.dept_id = d.dept_id
|
||
) t
|
||
WHERE rk <= 3;
|
||
```
|
||
|
||
**输入**: Oracle → GaussDB 迁移: `SELECT NVL(name, '未知') FROM users WHERE ROWNUM <= 10`
|
||
|
||
**输出**:
|
||
```sql
|
||
SELECT COALESCE(name, '未知') FROM users LIMIT 10;
|
||
-- NVL → COALESCE, ROWNUM → LIMIT
|
||
```
|
||
|
||
## 训练详情
|
||
|
||
### 训练超参数
|
||
|
||
```yaml
|
||
# LoRA 配置
|
||
lora_rank: 64
|
||
lora_alpha: 128
|
||
lora_dropout: 0.05
|
||
lora_target: all # q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
|
||
|
||
# 训练参数
|
||
learning_rate: 2.0e-5
|
||
lr_scheduler_type: cosine
|
||
warmup_ratio: 0.1
|
||
num_train_epochs: 3
|
||
per_device_train_batch_size: 8
|
||
gradient_accumulation_steps: 4 # 等效 batch_size = 32
|
||
cutoff_len: 2048
|
||
optim: adamw_torch
|
||
bf16: true
|
||
gradient_checkpointing: true
|
||
```
|
||
|
||
### 训练 Loss 曲线
|
||
|
||
```
|
||
训练过程：2,799 步，3 小时 29 分钟
|
||
|
||
Step Epoch Train Loss Eval Loss
|
||
200 0.21 1.217 1.216
|
||
600 0.64 1.038 1.104
|
||
1000 1.07 1.035 1.076
|
||
1400 1.50 1.062 1.058
|
||
1800 1.93 1.062 1.045
|
||
2200 2.36 0.966 1.044
|
||
2600 2.79 0.959 1.042 ← 最优检查点
|
||
```
|
||
|
||
最终 train_loss=1.039, eval_loss=1.042，两者接近，无过拟合。
|
||
|
||
### 训练数据分布
|
||
|
||
| 场景 | 占比 | 说明 |
|
||
|------|------|------|
|
||
| Text2SQL | ~30% | 自然语言 → SQL 生成 |
|
||
| SQL 调优 | ~20% | 慢查询分析、索引优化 |
|
||
| SQL 迁移 | ~15% | 跨数据库语法转换 |
|
||
| 错误诊断 | ~15% | 生产故障排查 |
|
||
| 运维知识 | ~10% | 参数调优、备份恢复 |
|
||
| 边界安全 | ~10% | 危险操作告警、超范围拒绝 |
|
||
|
||
## 局限性
|
||
|
||
- 边界安全能力还有提升空间：对 DELETE 全表、DROP DATABASE 等操作可能直接执行而不告警
|
||
- 对 GaussDB 505 特有的高级功能（如列存表、分布式特性）覆盖有限
|
||
- 仅支持文本输入，不支持图片（如执行计划截图）
|
||
- 建议在生产环境中增加推理侧安全规则兜底
|
||
|
||
## 引用
|
||
|
||
如果本模型对你有帮助，欢迎引用：
|
||
|
||
```bibtex
|
||
@misc{gaussdb-sql-expert-7b,
|
||
title={GaussDB SQL Expert 7B},
|
||
author={lanfers},
|
||
year={2026},
|
||
publisher={HuggingFace},
|
||
url={https://huggingface.co/lanfers/gaussdb-sql-expert-7b}
|
||
}
|
||
```
|
||
|
||
## 许可证
|
||
|
||
本模型基于 [Qwen2.5-Coder-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct) 微调，遵循 Apache 2.0 许可证。
|