# sql-agent-rl

**Repository Path**: kill-life/sql-agent-rl

## Basic Information

- **Project Name**: sql-agent-rl
- **Description**: 使用 Agent-Lightning + verl（GRPO）对小模型（Qwen3-1.7B）进行 Agentic 强化学习（RL），在 Spider 文本转 SQL 任务上显著提升 SQL 生成准确率。运行模块基于 LangGraph 构建的多轮 SQL-Agent（write → execute → check → rewrite）。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent-Lightning SQL-Agent 强化学习训练

使用 [Agent-Lightning](https://github.com/microsoft/agent-lightning) + [verl](https://github.com/volcengine/verl)（GRPO）对**小模型（Qwen3-1.7B）**进行 Agentic 强化学习（RL），在 **Spider 文本转 SQL** 任务上显著提升 SQL 生成准确率。运行模块基于 **LangGraph** 构建的多轮 SQL-Agent（write → execute → check → rewrite）。

本仓库为一次真实完成的开源实验：从环境部署、训练配置、快速验证到正式训练，再到结果分析与正式评测，全部基于 4×NVIDIA A800 80GB 的实际运行数据。

## 特性

- **Agentic RL 训练小模型**：用 GRPO 直接从小模型（Qwen3-1.7B）的执行反馈中学习，低成本提升文本转 SQL 能力
- **工业级架构**：LangGraph（Agent 执行）＋ verl（RL 训练）＋ Agent-Lightning（封装桥接），运行与训练分离
- **可复现**：4 篇脱敏文档覆盖环境搭建、配置说明、命令流程、踩坑记录与结果分析
- **多模式配置**：`fast`（冒烟）/ `qwen` / `llama` 一键切换

## 效果一览

- 验证集 SQL 正确率：**0.534 → 0.712**（相对提升 **+33.3%**，n=4 采样）
- 正式评测单次贪心准确率：**61.8%**（n=1，更保守的真实单次能力）
- 全程 **436 步 / ~17.8 小时**稳定运行，无 OOM、无崩溃

> 详细分析见 [docs/训练实验分析报告.md](docs/训练实验分析报告.md)。

## 仓库结构

```
.
├── README.md                              # 本文件
├── LICENSE                                # 开源协议
├── .gitignore                             # 忽略数据/模型/产物/密钥
├── docs/                                  # 文档（4 篇，均已脱敏）
│   ├── 4卡A800训练配置与命令指南.md        # 硬件/配置/完整命令/踩坑
│   ├── Agent-Lightning环境部署指南.md       # 从零搭建环境的可复现步骤
│   ├── Agent-Lightning实战技术博客.md       # 从原理到落地的完整技术博客
│   └── 训练实验分析报告.md                 # 训练与评测结果的数据分析
└── SQL-Agent-RL/spider/                   # 源码（来自官方 Spider 示例 + 定制）
    ├── sql_agent.py                       # LangGraph SQL-Agent + LitSQLAgent
    ├── train_sql_agent.py                 # 训练脚本 + 全部配置（fast/qwen/llama）
    ├── consolidate_checkpoint.py          # FSDP 分片 checkpoint 合并
    ├── evaluate_model.py                  # 训练后并行评测
    ├── spider_eval/                       # Spider 官方评估（exec_eval）
    └── README.md                          # 官方示例说明
```

> `SQL-Agent-RL/data/`、`models/`、`checkpoints/`、`model_rl/`、`swanlog/` 等**大文件与数据/产物均未纳入仓库**（见 `.gitignore`），需按文档自行准备。

## 快速开始

环境安装见 [docs/Agent-Lightning环境部署指南.md](docs/Agent-Lightning环境部署指南.md)。

```bash
conda activate agent_lighting
cd SQL-Agent-RL

# ① fast 冒烟实验（约 15 分钟，验证配置可用）
CUDA_VISIBLE_DEVICES=0,1,2,3 SWANLAB_API_KEY=<YOUR_SWANLAB_API_KEY> \
  python spider/train_sql_agent.py fast

# ② 正式训练
nohup env CUDA_VISIBLE_DEVICES=0,1,2,3 SWANLAB_API_KEY=<YOUR_SWANLAB_API_KEY> \
  python spider/train_sql_agent.py qwen > train.log 2>&1 &
```

- ⚠️ **务必替换** `SWANLAB_API_KEY` 占位符为你自己的云端凭据（未注册时也可省略，走本地日志）。
- 数据与模型路径均为**相对路径**，请从 `SQL-Agent-RL/` 目录运行。
- 训练 GPU 利用率 ~35% 是 Agentic RL 串行多轮执行的固有特性，属正常现象，详见文档。

## 核心要点（踩坑精华）

| 主题 | 经验 |
|---|---|
| flash-attn | 用官方预编译 wheel **零编译**，不要从源码装 |
| libstdc++ | `LD_LIBRARY_PATH` 前置 conda lib |
| fastapi / transformers | 锁 `0.136.3` / `<5` |
| Qwen3 thinking | 修改 `tokenizer_config.json` 默认关闭 |
| 训练 OOM 死锁 | `gpu_memory_utilization=0.6` |
| LoRA | verl 0.5.0 + vllm 0.10.2 不兼容，坚持全参微调 |
| 断点续训 | `save_freq=10` + `resume_mode=auto` |

## 关键依赖版本

```
torch 2.8.0+cu128 · flash-attn 2.8.3.post1 · vllm 0.10.2 · verl 0.5.0
agentlightning 0.3.0 · transformers 4.57.6 · numpy 1.26.4 · swanlab 0.9.2
```

## 免责声明

- 数据与模型权重不随仓库分发，请遵守各自许可证（Spider / Qwen 等）。
- 文档中涉及的命令与配置均基于一次真实环境验证，不同硬件/驱动/版本结果可能略有差异。

## 致谢

- [Agent-Lightning（微软）](https://github.com/microsoft/agent-lightning)
- [verl（火山引擎）](https://github.com/volcengine/verl)
- [Spider 数据集（耶鲁大学）](https://yale-lily.github.io/spider)
- [SwanLab](https://swanlab.cn)