SQL Copilot — 基于大模型的 Text2SQL 自助式数据报表开发

SQL Copilot 是一个 Text2SQL（自然语言转 SQL） 实战案例：面向保险（寿险）业务数据，让业务人员用一句中文自然语言描述需求，大模型自动生成可执行的 SQL 查询，从而实现「自助式数据报表开发」，降低数据查询门槛。

本项目对比了 对话模型 与 代码模型 两种生成 SQL 的方案，并提供了一套将生成结果在真实数据库上执行、自动评测「能否运行」的闭环流程。

---

项目背景

在企业里，业务人员经常需要从数据库中查询数据、制作报表，但他们往往不熟悉 SQL，只能依赖数据分析师/工程师。Text2SQL 的目标就是把「自然语言需求」直接翻译成「SQL 语句」，让不懂 SQL 的人也能自助取数。

本案例以一个虚构的 寿险公司数据库（life_insurance） 为场景，包含客户、保单、理赔、产品、代理人等 7 张业务表，覆盖了从简单单表查询到多表关联、聚合分析等不同难度的查询需求。

---

核心功能

• 自然语言转 SQL：输入中文业务问题（如「查询所有未支付保费的保单号和客户姓名」），自动生成对应 SQL。
• 两种技术方案对比：
  • 对话模型方案：向模型提供「数据表字段中文说明 + 问题」，引导其先分析需要哪些表/字段再写 SQL。
  • 代码模型方案：向模型提供「建表语句 DDL + 问题」，以代码补全的方式生成 SQL。
• 结果自动评测：把生成的 SQL 在真实 MySQL 数据库上逐条执行，标记「能否运行」，并将查询结果渲染为 Markdown 表格，量化对比不同模型的准确率与耗时。
• 本地代码大模型演示：附带 CodeGeeX4、Qwen2.5-Coder 两个本地部署的代码生成模型示例，作为 Coder 类模型的能力补充。

---

目录结构

SQL Copilot/
├── README.md                     # 项目说明（本文件）
├── codegeex-1.ipynb              # CodeGeeX4-all-9b 本地模型代码生成演示
├── qwen-coder1.ipynb             # Qwen2.5-Coder-7B-Instruct 本地模型代码生成演示
└── insurance/                    # Text2SQL 主案例（寿险数据）
    ├── SQL查询-Chat.ipynb        # 方案一：用对话模型（qwen-turbo）生成 SQL
    ├── SQL查询-Coder.ipynb       # 方案二：用代码模型（qwen-coder-plus）生成 SQL
    ├── SQL结果评测.ipynb          # 将生成的 SQL 连接真实数据库执行、自动评测
    ├── qa_list-1.txt             # 自然语言问题集（简单查询为主）
    ├── qa_list-2.txt             # 自然语言问题集（含多表关联/聚合）
    ├── requirements.txt          # Python 依赖
    ├── sql_result_qwen_turbo.xlsx# 生成 + 评测结果示例
    └── data/
        ├── create_sql.txt        # 7 张表的建表语句（CREATE TABLE DDL）
        ├── 数据表字段说明-精简1.txt  # 表/字段的中文说明
        ├── CustomerInfo.xlsx     # 客户信息表 样例数据
        ├── PolicyInfo.xlsx       # 保单信息表 样例数据
        ├── ClaimInfo.xlsx        # 理赔信息表 样例数据
        ├── BeneficiaryInfo.xlsx  # 受益人信息表 样例数据
        ├── AgentInfo.xlsx        # 代理人信息表 样例数据
        ├── ProductInfo.xlsx      # 保险产品信息表 样例数据
        └── EmployeeInfo.xlsx     # 内部员工信息表 样例数据

---

数据库结构

数据库 life_insurance 共包含 7 张表：

表名	中文名称	说明
CustomerInfo	客户信息表	客户的基本资料、婚姻/职业/健康状况、注册与来源等
PolicyInfo	保单信息表	保单号、所属客户/产品/代理人、保单状态、保费支付情况
ClaimInfo	理赔信息表	理赔号、对应保单、理赔金额/类型/状态、审核与支付信息
BeneficiaryInfo	受益人信息表	受益人基本资料
AgentInfo	代理人信息表	代理人资料、证书/执照信息、佣金结构
ProductInfo	保险产品信息表	产品名称/类型、保额范围、保费、投保要求、销售区域等
EmployeeInfo	保险公司内部员工表	员工资料、职位/部门、薪资、工作地点等

完整的建表语句见 insurance/data/create_sql.txt，字段的中文说明见 insurance/data/数据表字段说明-精简1.txt。

---

两种 Text2SQL 方案

方案一：对话模型（SQL查询-Chat.ipynb）

• 模型：qwen-turbo-latest（通过阿里云 DashScope 调用）
• 提示词思路：把「数据表字段的中文说明」作为上下文，引导模型先思考「这个查询需要哪些表和字段」，再编写 SQL；若有多条查询则尝试合并为一条。
• 适用：表结构以业务语义描述为主、需要模型做语义理解和推理的场景。

方案二：代码模型（SQL查询-Coder.ipynb）

• 模型：qwen-coder-plus（通过阿里云 DashScope 调用）
• 提示词思路：采用代码补全风格，提供建表语句（DDL）+ 问题，让模型直接续写 ```sql 代码块。
• 适用：以精确表结构（DDL）为输入、追求生成稳定性的场景。

两种方案均通过正则从模型输出中提取 ```sql 代码块，并将「问题 / 生成的 SQL / 耗时」保存到 Excel。

评测：SQL结果评测.ipynb

读取上一步生成的 SQL，逐条连接真实 MySQL 数据库执行：

• 执行成功：标记 Yes，并把查询结果渲染成 Markdown 表格；
• 执行失败：标记 No，并记录报错信息；

由此可以量化对比不同模型 / 不同提示策略在「可执行率」和「响应耗时」上的表现。

---

快速开始

1. 环境准备

# 建议使用 Python 3.10+
pip install -r insurance/requirements.txt

主要依赖：dashscope、openai、langchain、pandas、SQLAlchemy、transformers 等（详见 insurance/requirements.txt）。

2. 配置 API Key

调用 Qwen 系列模型需要 DashScope 的 API Key，通过环境变量提供：

# Linux / macOS
export DASHSCOPE_API_KEY="你的_API_Key"

# Windows PowerShell
$env:DASHSCOPE_API_KEY="你的_API_Key"

3. 运行流程

1. 打开 insurance/SQL查询-Chat.ipynb 或 insurance/SQL查询-Coder.ipynb，运行生成 SQL；
2. 打开 insurance/SQL结果评测.ipynb，连接数据库执行并评测结果。

评测 notebook 中的数据库连接信息为课程提供的共享教学库，可按需替换为自己的数据库。

---

技术栈

• 大模型 / API：通义千问 Qwen（qwen-turbo / qwen-coder-plus，DashScope）、CodeGeeX4、Qwen2.5-Coder
• 模型推理：transformers、modelscope（本地模型演示）
• 数据与数据库：pandas、SQLAlchemy、MySQL

---