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

21 KiB
Raw Permalink Blame History

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
Qwen/Qwen2.5-Coder-7B-Instruct
nl2sql
text-to-sql
lora
distillation
dpo
qwen2_5_coder
mysql
agent
nlp
code
cn
exact-match
execution-accuracy
finetune
text-generation
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

如果您是本模型的贡献者,我们邀请您根据模型贡献文档,及时完善模型卡片内容。