--- 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 /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 ```

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