Model: yiku233/qwen2.5-coder-7b-nl2sql Source: Original Platform
license, license_link, library_name, pipeline_tag, base_model, tags, domains, language, metrics, base_model_relation, tasks, frameworks
| license | license_link | library_name | pipeline_tag | base_model | tags | domains | language | metrics | base_model_relation | tasks | frameworks | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| apache-2.0 | https://www.modelscope.cn/models/yiku233/qwen2.5-coder-7b-nl2sql/resolve/master/LICENSE | transformers | text-generation |
|
|
|
|
|
finetune |
|
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 |
| 微调方式 | 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:
-- 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
标量子查询做阈值比较,内外两次过滤对齐同一时间窗:
-- 能不能帮我查一下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:
-- 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:
-- 哪些客户的累计下单金额超过了所有客户的平均累计下单金额?
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 下载
pip install modelscope
modelscope download --model yiku233/qwen2.5-coder-7b-nl2sql --local_dir ./qwen25-coder-7b-nl2sql
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):
modelscope download --model yiku233/qwen2.5-coder-7b-nl2sql --local_dir ./qwen25-coder-7b-nl2sql --exclude "adapters/*"
7.2 vLLM 部署
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 保留的是训练时的云端绝对路径,未做修改,以保证发布产物与训练产物逐字节相同。加载时请显式传入基座模型:
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/ 下,不随本仓库公开,需要的话可联系作者。
# 单轮裸考(四模型 × 双验证集):可执行率 / 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下载
#安装ModelScope
pip install modelscope
#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
如果您是本模型的贡献者,我们邀请您根据模型贡献文档,及时完善模型卡片内容。