SQLCoder：专为 Text-to-SQL 微调的大模型

FreeGuideOnline 最新 2026-06-23

bash pip install torch transformers accelerate bitsandbytes

对于大尺寸模型，建议同时安装 `xformers` 以加速推理。

### 基础推理示例
以下代码演示如何加载 SQLCoder-7B 并生成 SQL 查询：
```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "defog/sqlcoder-7b-2"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,
    device_map="auto",
    trust_remote_code=True
)

# 构造提示词，必须包含 Schema 和问题
prompt = """### Instructions:
Your task is to convert a text question to a SQL query, given a database schema.
Adhere to the following rules:
- Use valid SQL syntax only.
- Only generate the SQL query, no explanations.

### Database Schema:
CREATE TABLE employees (
    id INTEGER PRIMARY KEY,
    name TEXT,
    department TEXT,
    salary INTEGER,
    hire_date DATE
);

### Question:
列出薪资高于80000的所有员工姓名和部门，按入职日期降序排列。

### SQL:
"""
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=200, do_sample=False, num_beams=4)
generated_sql = tokenizer.decode(outputs[0], skip_special_tokens=True)

# 提取 SQL 部分
sql_part = generated_sql.split("### SQL:")[-1].strip()
print(sql_part)

注意：提示词格式对结果影响巨大。务必清晰给出任务指令、数据库 DDL 语句以及自然语言问题。

针对不同数据源定制提示

你可以替换 DB Schema 部分来查询自己的数据库。例如，对于 PostgreSQL，可以包含标准的 DDL；对于 BigQuery 可能需要指定分区过滤等，也可以通过提示词中的“Additional Rules”指导模型生成方言语法。

微调属于你自己的 SQLCoder 模型

数据集构建

准备一个 JSON 格式的数据集，每行包含 schema（CREATE TABLE 语句）和 question-query 对。示例：

{
  "schema": "CREATE TABLE products (product_id INT, name TEXT, price DECIMAL);",
  "question": "价格最低的商品叫什么？",
  "query": "SELECT name FROM products ORDER BY price ASC LIMIT 1"
}

建议收集至少几百条高质量样本，涵盖你业务中常见的查询模式。可在公开数据基础上增加私有 Schema 样本。

使用 LoRA 进行高效微调

利用 peft 库可以快速完成微调：

from peft import LoraConfig, get_peft_model, TaskType

# 配置 LoRA 参数
lora_config = LoraConfig(
    r=8,
    lora_alpha=16,
    target_modules=["c_attn", "c_proj", "w1", "w2"],  # 根据模型架构调整
    lora_dropout=0.05,
    bias="none",
    task_type=TaskType.CAUSAL_LM,
)
model = get_peft_model(model, lora_config)

随后使用 Trainer 进行常规的训练循环，监督信号为 query 部分的交叉熵损失。微调后的模型会显著提升在私有 Schema 上的准确率。

微调经验与最佳实践

小步快跑：先用少量数据（如 100 条）验证流程，再逐步扩大。
保留原始能力：混合少量通用 SQL 数据，避免模型完全只记住私有 Schema 而失去泛化能力。
评估指标：使用执行准确率（Execution Accuracy）作为终极指标，而非仅匹配 SQL 文本。
显存优化：使用 4bit 量化加载基础模型，并结合 gradient_checkpointing 减少显存占用。

常见问题与优化技巧

模型生成的 SQL 语法错误怎么办？

在提示词中进一步明确数据库类型（如 -- Use PostgreSQL syntax）。
增加后处理步骤，使用 SQL 解析器（如 sqlglot）进行语法检查和自动修正。
在微调数据中专门加入带语法错误的修正样本。

如何让模型更好地遵循 Schema？

确保 DDL 语句完整，包含主键、外键约束和列注释（作为内联注释）：

CREATE TABLE orders (
    order_id INT PRIMARY KEY,        -- 订单唯一ID
    customer_id INT REFERENCES customers(id),
    order_date TIMESTAMP,            -- 下单时间
    total DECIMAL(10,2)              -- 总金额
);