# 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 许可证。