Files
ModelHub XC 0ddc1bb178 初始化项目,由ModelHub XC社区提供模型
Model: yiku233/qwen2.5-coder-7b-nl2sql
Source: Original Platform
2026-11-11 21:24:13 +08:00

379 lines
21 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
license: apache-2.0
license_link: https://www.modelscope.cn/models/yiku233/qwen2.5-coder-7b-nl2sql/resolve/master/LICENSE
library_name: transformers
pipeline_tag: text-generation
base_model:
- Qwen/Qwen2.5-Coder-7B-Instruct
tags:
- nl2sql
- text-to-sql
- lora
- distillation
- dpo
- qwen2_5_coder
- mysql
- agent
domains:
- nlp
- code
language:
- cn
metrics:
- exact-match
- execution-accuracy
base_model_relation: finetune
tasks:
- text-generation
frameworks: PyTorch
---
# 数据魔方 · NL2SQL 三阶段微调模型
`Qwen2.5-Coder-7B-Instruct` 上做的三阶段 LoRA 微调:SFT 领域适配、Teacher-Student 蒸馏、DPO 偏好对齐。用途是私有星型数仓的自然语言问数,配合 LangGraph agent 链路(元数据召回、`EXPLAIN` 校验、失败回环校正)使用。
仓库根目录是三阶段链式合并后的 bf16 全量权重(15.23 GB / 4 分片),可直接 vLLM 部署。`adapters/` 下是三阶段 LoRA 增量,用于复现流水线和审计。
主要结果:
| 场景 | 指标 | 数值 |
|---|---|---|
| 端到端 agent 链路(200 题,复杂题卷) | 可用率(拿到执行结果) | 99.5% |
| 端到端 agent 链路(同上) | EX(结果与 gold 一致) | 61.5% |
| 单轮裸考(同权重,无 agent 兜底) | EX | 39.0%(同卷基座 34.0%) |
| 单轮裸考 | 输出格式合规率 | 100%(基座 36.0%) |
| 推理服务(vLLM 直连,并发 20) | 生成吞吐 / 成功率 | 345.6 tok/s / 100% |
需要先说明的几点:本模型只对这一套 schema 有效,不是通用 SQL 助手,第 5、6 节记录了失败模式与不适用场景。所有指标都是本项目实测,脚本与结果文件不随本仓库公开。
---
## 1. 基本信息
| 项 | 值 |
|---|---|
| 基座 | [Qwen/Qwen2.5-Coder-7B-Instruct](https://modelscope.cn/models/Qwen/Qwen2.5-Coder-7B-Instruct) |
| 微调方式 | LoRA,rank 16 / alpha 32 / dropout 0.05 / target=all,三阶段链式 |
| 可训练参数 | 约 4.0×10⁷ / 阶段,占 7.6B 基座的 0.53% |
| 交付形态 | 根目录 bf16 全量权重;`adapters/stage{1,2,3}-*` LoRA 增量 |
| 词表与模板 | 继承基座(151,643),对话模板见 `chat_template.jinja` |
| 训练硬件 | 单卡 vGPU-32GB(AutoDL),PyTorch 2.4 + CUDA 12.4 |
| 训练框架 | LLaMA-Factory 0.9.x + PEFT + TRL(DPO) |
| 三阶段总耗时 | 8 h 37 min(SFT 1h46m,蒸馏 3h46m,DPO 3h06m) |
## 2. 三阶段流水线
每一阶段都在上一阶段的合并产物上继续训练,链式依赖是硬约束。
```
Qwen2.5-Coder-7B-Instruct
└─(1) SFT ──adapter──▶ merge ──▶ sft_merged
└─(2) 蒸馏 ──adapter──▶ merge ──▶ distill_merged
└─(3) DPO ──adapter──▶ merge ──▶ dpo_merged
```
| 阶段 | 训练底座 | 数据 | 超参 | 步数 / 时长 | train_loss | eval_loss |
|---|---|---|---|---|---|---|
| 1. SFT | 官方基座 | `sft_train` 1,651 / `sft_val` 182 | lr 1e-4, cosine, warmup 0.1, wd 0.01, 3 ep, 全局 bs 16 | 312 步 / 1h45m40s | 0.0698 | 0.0129 |
| 2. 蒸馏 | `sft_merged` | `sft_train` + `distill_train` 2,503 / `distill_val` 200 | lr 5e-5, 2 ep,其余同上 | 520 步 / 3h45m38s | 0.0920 | 0.0769 |
| 3. DPO | `distill_merged` | `dpo_train` 2,572 / `dpo_val` 200 | lr 5e-6, 1 ep, 全局 bs 16, `pref_beta=0.1`, `pref_loss=sigmoid` | 161 步 / 3h05m48s | 0.4362 | 0.3098 |
两点补充说明:
阶段 2 是混合训练,实际挂载 `nl2sql_sft_train,nl2sql_distill_train`,回放 SFT 存量以抑制遗忘。这就是为什么阶段 2 之后简单题能力仍在(`sft_val` EX 82.4%),而复杂题能力从 2.0% 抬到 20.0%(仍低于同卷基座的 34.0%,原因见 4.1)。
阶段 1 的 `eval_loss` 低到 0.0129,但同一模型在独立考卷 `distill_val` 上 EX 只有 2.0%。`eval_loss` 在这里不能当作能力判据,这也是我们引入独立蒸馏考卷和第三阶段的原因。
DPO 阶段的收敛证据(比 loss 本身信息量更大):
| 指标 | 值 |
|---|---|
| rewards/accuracies | 0.950 |
| rewards/margins | 2.053 |
| rewards/chosen , rewards/rejected | −0.0235 , −2.0763 |
| logps/chosen , logps/rejected | −27.72 , −74.94 |
chosen 侧 reward 几乎不偏移,rejected 侧被显著压低。95% 的偏好判对率说明模型学到的是哪种 SQL 是对的,而不只是输出格式。
## 3. 训练数据
| 数据集 | 条数 | 构建方式 |
|---|---|--------------------------------------------------------------------------------------------------------------------------|
| 种子 SQL | 620 | 人工按难度分层设计:单表聚合、join、指标、时间粒度、组内 TopN、占比、环比、阈值-平均 |
| `sft_train` / `sft_val` | 1,651 / 182 | 种子 SQL 反推自然语言问题,每题多风格变体扩写;过滤模型幻觉出的时间词 |
| `distill_train` / `distill_val` | 2,503 / 200 | Teacher = DeepSeek-v4, 结合 schema 召回上下文同批产出参考SQL作为gold锚点,设计语法/格式解析、表/字段幻觉检查、EXPLAIN 可执行、真实执行结果非空四重校验选金机制。 |
| `dpo_train` / `dpo_val` | 2,572 / 200 | 负例 on-policy:用阶段 2 学生模型真实采样出的错误 SQL。chosen/rejected 均以执行结果是否等于 gold 为准,最后在人工抽样检测 |
两个设计约束:
`distill_val` 是唯一对四个模型都零泄漏的考卷。`sft_val` 的 182 题中有 23 道错题被回灌进 `distill_train`、15 题进入 `dpo_train`,用它做跨阶段对比没有意义。
阶段 2 刻意加重复杂题。阶段 1 的失败模式是复杂语义塌缩成简单 GROUP BY,所以蒸馏增量主要买 join、窗口、CTE、时间粒度。
## 4. 评测
### 4.1 单轮裸考:四模型 × 双验证集
同一条 instruction 一次生成,不经 agent 的任何召回、校验、校正。EX 指在私有 `dw` 库上执行结果与 gold 一致(默认忽略行序,单元格值统一格式化后比对)。
| 模型 | 考卷 | n | 格式合规 | 可执行率 | EX |
|---|---|---|---|-------|-----------|
| 基座 Qwen2.5-Coder-7B | `distill_val` | 200 | 36.00 | 86.50 | 34.00 |
| SFT | `distill_val` | 200 | 100.00 | 36.00 | 2.00 |
| 蒸馏 | `distill_val` | 200 | 100.00 | 32.50 | 20.00 |
| DPO(定稿) | `distill_val` | 200 | 100.00 | 56.50 | **39.00** |
| 基座 | `sft_val` | 182 | 70.88 | 98.90 | 61.54 |
| SFT | `sft_val` | 182 | 100.00 | 93.96 | 87.36 |
| 蒸馏 | `sft_val` | 182 | 100.00 | 90.66 | 82.42 |
| DPO | `sft_val` | 182 | 100.00 | 93.96 | 85.71 |
读这张表有两个前提:
可执行率会奖励保守输出,不能单独引用。基座在复杂题卷上 86.5% 的可执行率高于所有微调模型(定稿 56.5%),但 EX 只有 34.0%:基座倾向输出一条语法正确、能跑、语义错误的简单 SQL。微调模型敢于使用 CTE 和窗口函数,这类 SQL 更容易在 `EXPLAIN` 阶段被判失败,可执行率因此下降。
`sft_val` 不适合做跨阶段基准。除污染问题(见第 3 节),SFT 已把它刷到 87.36%,接近饱和。
蒸馏阶段在 `distill_val` 上的 EX(20.0%)低于同卷基座(34.0%),这是链路上一个真实的倒退。第一层原因是训练容量:阶段 1 过拟合(`eval_loss` 0.0129)把复杂语义塌缩成简单 GROUP BY,阶段 2 只有 2,503 条数据、跑 2 个 epoch,只能部分回补(2.0% 到 20.0%),没追平基座。
第二层是可执行率对 EX 的截断。蒸馏档可执行率只有 32.5%(基座 86.5%):微调模型开始写 CTE 和窗口函数,这类 SQL 只要一处列名或过滤条件错就整条被判失败,相当一部分可能正确的输出进不了 EX 判定。真正把复杂题做过基座是在阶段 3,DPO 针对不可执行和语义错误做惩罚,把 EX 拉到 39.0%、可执行率恢复到 56.5%。
表里 SFT 那行 2.0% 不是评测失误,它正是引入第三阶段的原因。
### 4.2 端到端 agent 链路:200 题
模型放进完整链路(关键词扩展、列/值/指标召回、表/指标筛选、生成、`EXPLAIN` 校验、必要时校正、执行)后的成绩。
| 指标 | 数值 |
|---|----------------|
| 端到端可用率 | 99.50% |
| 端到端 EX | 61.50% |
| 链路崩溃率 | 0.50%(1/200) |
| 首过率(未触发校正) | 57.00% |
| 首过 EX | 66.67% |
| 首过且执行成功 | 99.12% |
| 触发校正比例 | 43.00%(86/200) |
| 校正后可执行 | 100.00% |
| 校正后 EX | 54.65% |
链路拓扑:生成结果先过 `EXPLAIN` 校验,通过则执行;不通过进校正节点,校正后回到校验,由 `correct_count` 与 `MAX_CORRECT_TIMES=2` 限次,构成有界回环。线上节点与离线评测脚本共用同一个 `clean_sql`,送进校验的 SQL 形态与训练目标保持一致。链路崩溃只剩 1/200(200 题里 199 题拿到了执行结果),原因就在这里:没有任何一条 SQL 能绕过 `EXPLAIN` 直接进入执行环节。
两个读法:
端到端 EX 61.5% 与单轮裸考的 39.0% 不是同一件事,差值来自 agent 的召回与校验节点,不能记在模型头上。反过来说,把同一份权重挂到不做 schema 召回的通用 agent 上,拿不到 61.5%。
表里的数字是闭合的:首过的 114 题里 76 题答对(66.67%),触发校正的 86 题里 47 题答对(54.65%),76 加 47 就是 123/200,即端到端 EX 61.5%。校正节点的价值体现在把语法错误救回可执行(校正后可执行率 100%),而不是把语义错题做对;会被判失败的题目本身也更难,两个因素叠加形成首过与校正后这 12 pt 的差距。
延迟口径:本轮评测短路了链路节点内用于限流的 `asyncio.sleep(1)`,`avg = 14.93 s` 是纯链路计算耗时,不代表线上延迟。
### 4.3 推理服务压测(EvalScope,vLLM 直连)
对 `/v1/chat/completions` 直连压测,不含 agent 其余节点,与 4.2 的端到端耗时是两个口径。输入均 1,697 tokens,输出 214–218 tokens(p50 约 131,max 512),5 档并发各 100 请求、流式调用,成功率全部 100%。分位数取自 EvalScope 输出的 `benchmark_percentile.json`。
| 并发 | RPS | 生成吞吐 (tok/s) | TTFT avg / p50 / p99 (ms) | TPOT avg (ms) | 单流解码 (tok/s) | 单请求耗时 avg / p50 / p99 (s) |
|---|---|---|---|---|---|---|
| 1 | 0.20 | 43.0 | 268.8 / 270.1 / 310.6 | 22.09 | 45.3 | 5.06 / 3.12 / 11.65 |
| 10 | 1.19 | 258.4 | 465.7 / 282.4 / 2441.3 | 33.96 | 29.5 | 7.77 / 4.85 / 19.93 |
| 20 | 1.59 | 345.6 | 902.0 / 286.4 / 4738.5 | 49.45 | 20.2 | 11.03 / 6.90 / 28.11 |
| 30 | 1.87 | 407.7 | 1738.2 / 312.2 / 7182.5 | 59.07 | 16.9 | 13.82 / 8.93 / 36.20 |
| 40 | 2.03 | 434.5 | 2496.8 / 456.1 / 9864.1 | 79.50 | 12.6 | 16.64 / 13.69 / 41.33 |
生产建议并发 20。30 到 40 吞吐只涨 6.6%,但 TTFT 均值从 1.74 s 涨到 2.50 s、p99 从 7.18 s 涨到 9.86 s,单请求耗时 p99 已到 41 s。并发 20 的中位 TTFT 仍是 286 ms,但 p99 已经到 4.74 s:到这一档只有少数长输出请求(512 tokens 那一档)开始受排队影响,尚未普泛化。
退化来自 batching 排队而不是解码本身:单流(并发 1)首 token 269 ms、逐 token 22 ms,p99 也只有 311 ms;并发拉到 40 后逐 token 从 22 ms 涨到 80 ms,单流解码速率相应从 45.3 tok/s 掉到 12.6 tok/s。
### 4.4 推理示例
以下四条都是端到端 200 题中首过即 EX 正确的真实样本。
简单聚合加 join:
```sql
-- 2025年第一季度,各大区的成交总额分别是多少?
SELECT r.region_name, SUM(f.order_amount) AS gmv
FROM fact_order f JOIN dim_region r ON f.region_id = r.region_id
WHERE f.date_id BETWEEN 20250101 AND 20250331
GROUP BY r.region_name
```
标量子查询做阈值比较,内外两次过滤对齐同一时间窗:
```sql
-- 能不能帮我查一下2025年上半年单笔金额高于平均值的订单有哪些?
SELECT order_id, order_amount FROM fact_order
WHERE date_id BETWEEN 20250101 AND 20250630
AND order_amount > (SELECT AVG(order_amount) FROM fact_order
WHERE date_id BETWEEN 20250101 AND 20250630)
```
组内 TopN 用窗口函数,而不是全局 `ORDER BY ... LIMIT`:
```sql
-- 2025年第三季度,每个大区中成交总额最高的品牌是哪个?
SELECT region_name, brand, gmv FROM (
SELECT r.region_name, p.brand, SUM(f.order_amount) AS gmv,
ROW_NUMBER() OVER (PARTITION BY r.region_name ORDER BY SUM(f.order_amount) DESC) AS rn
FROM fact_order f
JOIN dim_region r ON f.region_id = r.region_id
JOIN dim_product p ON f.product_id = p.product_id
WHERE f.date_id BETWEEN 20250701 AND 20250930
GROUP BY r.region_name, p.brand) t
WHERE rn = 1
```
CTE 与平均值比较,基座与 SFT 阶段在此类题上 EX 接近 0:
```sql
-- 哪些客户的累计下单金额超过了所有客户的平均累计下单金额?
WITH customer_gmv AS (
SELECT f.customer_id, SUM(f.order_amount) AS total_gmv FROM fact_order f GROUP BY f.customer_id),
avg_gmv AS (SELECT AVG(total_gmv) AS avg_total FROM customer_gmv)
SELECT c.customer_name, c.member_level, cg.total_gmv
FROM customer_gmv cg
JOIN dim_customer c ON cg.customer_id = c.customer_id
CROSS JOIN avg_gmv
WHERE cg.total_gmv > avg_gmv.avg_total
ORDER BY cg.total_gmv DESC
```
## 5. 已知失败模式
端到端评测中,“能执行但结果错”的题目集中在下面六类,按出现频度从高到低排列:
| 类型 | 典型表现 |
|---|---|
| 环比 / 同比 | 多输出一列上一期金额;把比值写成百分数(单位口径不一致);多数校正后仍错 |
| 组内 TopN | 限定语作用域丢失,“每个大区最高”塌缩成全局最高;相当比例首过即错 |
| 阈值 vs 平均 | `WHERE gmv > 平均` 的平均未按同一过滤条件计算 |
| 占比 | 分母漏掉时间过滤;百分比与小数混用 |
| 多维并列 | 该按两维分组只按一维 |
| 其他 | — |
共性集中在限定语作用域和单位口径,不是语法能力。下一版的改进方向因此是把这两类作为 DPO 负例的定向扰动重点,而不是继续堆格式类数据。
## 6. 适用边界与限制
- 本模型只对配套的私有星型 schema 有效。训练中出现过的表名列名不代表能泛化到别的库,换 schema 需要重做数据构建与训练。
- 库内金额列采用浮点类型,聚合结果存在尾差,结果比对需要统一的格式化口径。
- 可执行不等于正确,见 4.1,请勿用可执行率作为上线判据。
- 单轮裸考 EX 39.0% 是保守下限,端到端 61.5% 依赖链路加成。两者都建立在 agent 的召回与校验节点之上,把权重单独挂到通用 SQL agent 上复现不了后者。
## 7. 使用方式
### 7.1 下载
```bash
pip install modelscope
modelscope download --model yiku233/qwen2.5-coder-7b-nl2sql --local_dir ./qwen25-coder-7b-nl2sql
```
```python
from modelscope import snapshot_download
model_dir = snapshot_download('yiku233/qwen2.5-coder-7b-nl2sql')
```
只要最终效果时下载根目录全量权重即可。`adapters/` 下另有约 485 MB(462 MiB)的 LoRA 增量,只有复现三阶段链路时才用得到,可以用 `--exclude` 跳过(注意参数名是 `--exclude` / `--include`,不是 `--ignore`):
```bash
modelscope download --model yiku233/qwen2.5-coder-7b-nl2sql --local_dir ./qwen25-coder-7b-nl2sql --exclude "adapters/*"
```
### 7.2 vLLM 部署
```bash
python -m vllm.entrypoints.openai.api_server \
--model ./qwen25-coder-7b-nl2sql \
--served-model-name qwen25-coder-7b-nl2sql \
--chat-template ./qwen25-coder-7b-nl2sql/chat_template.jinja \
--port 8000
```
`chat_template.jinja` 随权重一同导出,必须与训练时的 qwen 模板一致。模板不一致会直接破坏训练推理分布一致性,表现为格式合规率坍塌,这类问题很难从 loss 之外的现象倒推,建议部署后先用一条已知样本核对输出格式。
### 7.3 三阶段 adapter 复现
`adapters/` 下三个 LoRA 增量,每个 `adapter_model.safetensors` 为 161,533,192 字节(fp32 存储,加载时按基座精度转换):
| 路径 | 挂载底座 |
|---|---|
| `adapters/stage1-sft` | 官方基座 `Qwen/Qwen2.5-Coder-7B-Instruct` |
| `adapters/stage2-distill` | `sft_merged`(stage1 合并产物) |
| `adapters/stage3-dpo` | `distill_merged`(stage2 合并产物) |
stage2 与 stage3 不能直接挂官方基座。挂错底座不会报错,但得到的模型与训练时的模型不等价,本卡片所有数字都失去意义。
在 LLaMA-Factory 下用 `llamafactory-cli export` 逐段合并(`template: qwen`、`export_size: 4`、`export_legacy_format: false`):
| 配置 | `model_name_or_path` | `adapter_name_or_path` | `export_dir` |
|---|---|---|---|
| merge_stage1 | `Qwen/Qwen2.5-Coder-7B-Instruct` | `adapters/stage1-sft` | `sft_merged` |
| merge_stage2 | `sft_merged` | `adapters/stage2-distill` | `distill_merged` |
| merge_stage3 | `distill_merged` | `adapters/stage3-dpo` | `dpo_merged`,与本仓库根目录权重等价 |
三个 `adapter_config.json` 里的 `base_model_name_or_path` 保留的是训练时的云端绝对路径,未做修改,以保证发布产物与训练产物逐字节相同。加载时请显式传入基座模型:
```python
from peft import PeftModel
from transformers import AutoModelForCausalLM
base = "Qwen/Qwen2.5-Coder-7B-Instruct"
model = PeftModel.from_pretrained(
AutoModelForCausalLM.from_pretrained(base, torch_dtype="bfloat16"),
"adapters/stage1-sft",
)
```
### 7.4 分词器与模板
仓库带 `tokenizer.json`(fast tokenizer,内嵌完整词表与 merges)、`tokenizer_config.json`、`chat_template.jinja`、`vocab.json`、`merges.txt`,以及从上游继承的 `LICENSE`。其中 `vocab.json` 与 `merges.txt` 与上游基座逐字节相同,供 `use_fast=False` 和模型转换工具使用;`chat_template.jinja` 是合并时从 `tokenizer_config.json` 里拆出来的对话模板,上游基座目录中并没有这个文件,它的内容对齐训练时使用的 qwen 模板。
上游基座不含 `special_tokens_map.json`,本仓库同样不提供。Qwen2.5-Coder 的特殊 token(对话边界、FIM 与仓库级分隔一类 `|>` 形式标记)都声明在 `tokenizer_config.json` 与 `tokenizer.json` 内,不需要额外映射文件。
`tokenizer_config.json` 只有 718 字节而基座是 7,305 字节,原因是 LLaMA-Factory 合并时把对话模板搬到了独立的 `chat_template.jinja`,不是文件缺损。
## 8. 评测复现
评测脚本与结果文件在代码仓 `finetune/` 下,不随本仓库公开,需要的话可联系作者。
```bash
# 单轮裸考(四模型 × 双验证集):可执行率 / EX / 格式合规率
python -m finetune.eval.eval_sql_quality --endpoint <vllm>/v1 --model qwen25-coder-7b-nl2sql
# 端到端 agent 链路(200 题,需本地起 MySQL/ES/Qdrant 与 embedding 服务)
python -m finetune.eval.run_e2e_eval --sql-model qwen25-coder-7b-nl2sql --out <结果文件>
```
口径约定:
- 可执行率的分母包含崩溃题,且该指标奖励保守输出,不可单独引用。
- 首过率是未触发校正节点的题目占比,与“首过且执行成功”是两个指标,不要混用。
- 跨阶段对比只用 `distill_val`。
- 端到端结果必须带 `--out` 区分版本;评测脚本的默认输出路径是固定的,不加参数会覆盖上一轮结果。
- `run_e2e_eval` 的 `--no-sleep` 开关短路节点内限流等待,加与不加得到的是两种延迟口径,不要写进同一张表。
## 9. 许可与声明
本模型是 `Qwen/Qwen2.5-Coder-7B-Instruct` 的衍生作品,继承上游 Apache License 2.0。
训练数据与评测数仓为私有业务数据。公开的只有方法、超参和完整指标,包括失败案例。
所有数字均为单卡 vGPU-32GB 环境下的实测值,未做多 seed 平均。样本量为 1561 / 2503 / 2,572 这个量级,±2 pt 以内应视为噪声,本卡片的对比结论都按这一原则表述。
SDK下载
```bash
#安装ModelScope
pip install modelscope
```
```python
#SDK模型下载
from modelscope import snapshot_download
model_dir = snapshot_download('yiku233/qwen2.5-coder-7b-nl2sql')
```
Git下载
```
#Git模型下载
git clone https://www.modelscope.cn/yiku233/qwen2.5-coder-7b-nl2sql.git
```
<p style="color: lightgrey;">如果您是本模型的贡献者,我们邀请您根据<a href="https://modelscope.cn/docs/ModelScope%E6%A8%A1%E5%9E%8B%E6%8E%A5%E5%85%A5%E6%B5%81%E7%A8%8B%E6%A6%82%E8%A7%88" style="color: lightgrey; text-decoration: underline;">模型贡献文档</a>,及时完善模型卡片内容。</p>