# NL2SQL-Agent

**Repository Path**: da-qing-oh/nl2-sql-agent

## Basic Information

- **Project Name**: NL2SQL-Agent
- **Description**: Conversational data agent that transforms questions into SQL queries with quality validation
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-09
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NL2SQL-Agent

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-green)](https://fastapi.tiangolo.com/)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.0.8%2B-orange)](https://langchain-ai.github.io/langgraph/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

> **基于RAG与AI Agent的自然语言数据查询平台，对话驱动SQL生成与智能洞察。**
>
> AI-powered data query platform leveraging RAG and Agent for natural language SQL generation and intelligent insights.

***

## 项目亮点（技术角度）

| 亮点              | 说明                                                    |
| --------------- | ----------------------------------------------------- |
| **AI Agent 架构** | 基于 LangGraph 构建工作流，实现意图理解→SQL生成→执行→校验的完整闭环            |
| **RAG 增强检索**    | 使用 HuggingFace 中文 Embedding + Chroma 向量库，让 AI 理解数据库结构 |
| **性能优化实战**      | 通过单例缓存、LLM调用合并等策略，将查询耗时从 48s 优化至 20s（提速 58%）          |
| **安全设计**        | SQL 语法校验、参数化查询、禁止危险操作（DROP/DELETE），生产级安全考量            |
| **全栈交付**        | 独立完成后端（FastAPI）、前端（Gradio）、数据库、Docker 部署配置            |

***

## 系统架构图

```mermaid
flowchart TB
    subgraph TOP["🌳 智能数据管道AI平台"]
        direction TB

        subgraph L1["💬 用户交互层"]
            direction LR
            UI1["📱 Gradio对话界面<br/>自然语言输入"]
            UI2["📋 表结构展示<br/>Schema可视化"]
            UI3["🧪 预设测试用例<br/>一键验证"]
        end

        subgraph L2["⚡ FastAPI服务层"]
            direction TB
            API1["/health<br/>健康检查"]
            API2["/api/schema<br/>表结构获取"]
            API3["/api/query<br/>自然语言查询"]
            API4["/api/tables<br/>表名列表"]
        end

        subgraph L3["🤖 LangGraph Agent工作流"]
            direction TB
            NODE1["📝 单次LLM调用<br/>意图解析+SQL生成"]
            NODE2["🔍 SQL语法校验<br/>参数化查询执行"]
            NODE3["✅ 数据质量校验<br/>评分+建议报告"]
            NODE1 --> NODE2 --> NODE3
        end

        subgraph L4["🛠️ 工具引擎层"]
            direction LR
            TOOL1["sql_executor<br/>SQL执行器"]
            TOOL2["data_validator<br/>数据校验器"]
            TOOL3["metadata_store<br/>RAG向量检索"]
        end

        subgraph L5["💾 数据存储层"]
            direction LR
            DB1["🗄️ SQLite测试库<br/>orders/users/products"]
            DB2["🔍 Chroma向量库<br/>表结构Embedding"]
            DB3["🧠 text2vec模型<br/>中文语义编码"]
        end

        L1 -->|"HTTP/JSON<br/>POST /api/query"| L2
        L2 -->|"路由分发"| L3
        L3 -->|"调用"| L4
        L4 -->|"读写"| L5
    end

    style TOP fill:#fffbe6,stroke:#d9d9d9,stroke-width:2px
    style L1 fill:#e6f7ff,stroke:#1890ff,stroke-width:2px
    style L2 fill:#f6ffed,stroke:#52c41a,stroke-width:2px
    style L3 fill:#fff2f0,stroke:#ff4d4f,stroke-width:2px
    style L4 fill:#f9f0ff,stroke:#722ed1,stroke-width:2px
    style L5 fill:#fff7e6,stroke:#fa8c16,stroke-width:2px
```

**架构说明**：系统采用经典的分层架构，从上到下依次为：

- **用户交互层**：基于 Gradio 的 Web 界面，支持自然语言输入、表结构展示和测试用例验证
- **API 服务层**：FastAPI 提供 RESTful 接口，包含健康检查、表结构获取、自然语言查询等端点
- **Agent 工作流层**：LangGraph 编排 LLM 调用流程，将"意图解析+SQL生成"合并为单次调用，减少网络往返
- **工具引擎层**：三大核心工具——SQL 执行器（含语法校验）、数据校验器（质量评分）、RAG 检索器（向量语义检索）
- **数据存储层**：SQLite 数据库存储业务数据，Chroma 向量库存储表结构 Embedding，本地加载 HuggingFace 中文模型

***

## 数据流向图

```mermaid
flowchart LR
    subgraph INPUT["📥 输入层"]
        Q1["用户提问:<br/>'按省份统计用户数量'"]
    end

    subgraph PROCESS["⚙️ 处理层"]
        direction TB
        P1["🧠 LLM理解意图<br/>识别聚合需求"]
        P2["📊 加载全量Schema<br/>内存缓存(0ms)"]
        P3["📝 生成SQL<br/>SELECT province, COUNT(*)..."]
        P4["🔒 语法校验<br/>禁止DROP/DELETE"]
        P5["⚡ 参数化执行<br/>SQLite查询"]
    end

    subgraph OUTPUT["📤 输出层"]
        direction TB
        O1["📋 执行结果<br/>表格数据"]
        O2["📈 质量报告<br/>评分100/异常检测"]
        O3["💡 优化建议<br/>索引推荐"]
    end

    Q1 --> P1
    P1 --> P2
    P2 --> P3
    P3 --> P4
    P4 --> P5
    P5 --> O1
    P5 --> O2
    P5 --> O3

    style INPUT fill:#e6f7ff,stroke:#1890ff
    style PROCESS fill:#fff7e6,stroke:#fa8c16
    style OUTPUT fill:#f6ffed,stroke:#52c41a
```

**流程说明**：当用户输入"按省份统计用户数量"时，系统会：

1. **意图理解**：LLM 识别出这是一个聚合统计需求，需要 GROUP BY
2. **Schema 加载**：从内存缓存中获取数据库表结构（优化后 0ms）
3. **SQL 生成**：自动生成 `SELECT province, COUNT(*) FROM users GROUP BY province`
4. **安全校验**：检查 SQL 是否包含 DROP/DELETE 等危险操作
5. **参数化执行**：使用预编译语句防止 SQL 注入
6. **结果返回**：包含查询结果表格、数据质量评分（100分制）、优化建议

***

## 性能优化对比图

```mermaid
flowchart TB
    subgraph BEFORE["❌ 优化前 (v0.0.x)"]
        direction TB
        B1["请求到达"] --> B2["加载Embedding模型<br/>⏱️ 5-15s"]
        B2 --> B3["RAG向量检索<br/>⏱️ 2-5s"]
        B3 --> B4["LLM意图解析<br/>⏱️ 8-12s"]
        B4 --> B5["LLM SQL生成<br/>⏱️ 8-12s"]
        B5 --> B6["数据库查询<br/>⏱️ <1s"]
        B6 --> B7["总计: 48s+<br/>❌ 超时"]
    end

    subgraph AFTER["✅ 优化后 (v0.1.0)"]
        direction TB
        A1["请求到达"] --> A2["复用单例Embedding<br/>⏱️ 0s"]
        A2 --> A3["内存Schema缓存<br/>⏱️ 0s"]
        A3 --> A4["单次LLM调用<br/>⏱️ 15-20s"]
        A4 --> A5["数据库查询<br/>⏱️ <1s"]
        A5 --> A6["总计: ~20s<br/>✅ 可接受"]
    end

    style BEFORE fill:#fff2f0,stroke:#ff4d4f
    style AFTER fill:#f6ffed,stroke:#52c41a
```

**优化策略说明**：

| 优化项          | 优化前                     | 优化后            | 收益         |
| ------------ | ----------------------- | -------------- | ---------- |
| Embedding 加载 | 每次请求加载 1.94GB 模型（5-15s） | 启动时单例加载，后续复用   | 节省 5-15s   |
| RAG 向量检索     | 每次请求检索相关表（2-5s）         | 全量 Schema 内存缓存 | 节省 2-5s    |
| LLM 调用次数     | 2 次（意图解析 + SQL生成）       | 1 次（合并调用）      | 节省 8-12s   |
| **总耗时**      | **48s+（超时）**            | **\~20s**      | **提速 58%** |

***

## 模块依赖关系图

```mermaid
flowchart TD
    MAIN["app/main.py<br/>FastAPI入口"] --> WORKFLOW["app/agent/workflow.py<br/>Agent工作流"]
    MAIN --> API["API路由层"]

    WORKFLOW --> SQL_EXEC["app/tools/sql_executor.py<br/>SQL执行器"]
    WORKFLOW --> DATA_VAL["app/tools/data_validator.py<br/>数据校验器"]
    WORKFLOW --> META["app/rag/metadata_store.py<br/>元数据存储"]

    META --> EMBED["HuggingFaceEmbeddings<br/>text2vec-base-chinese"]
    META --> CHROMA["Chroma向量库<br/>data/chroma_db/"]

    SQL_EXEC --> SQLITE["SQLite<br/>data/test_db.sqlite"]

    GRADIO["gradio_app.py<br/>前端界面"] -.->|"HTTP请求"| MAIN

    style MAIN fill:#e6f7ff,stroke:#1890ff
    style WORKFLOW fill:#fff2f0,stroke:#ff4d4f
    style GRADIO fill:#f9f0ff,stroke:#722ed1
    style SQL_EXEC fill:#f6ffed,stroke:#52c41a
    style DATA_VAL fill:#f6ffed,stroke:#52c41a
    style META fill:#fff7e6,stroke:#fa8c16
```

**代码结构说明**：

- `main.py` 作为 FastAPI 入口，负责路由注册和依赖注入
- `workflow.py` 是核心 Agent 工作流，协调各工具模块
- `sql_executor.py` 和 `data_validator.py` 是独立工具模块，可单独测试复用
- `metadata_store.py` 封装 RAG 逻辑，对外隐藏 Embedding 和向量库细节
- `gradio_app.py` 作为独立前端，通过 HTTP 调用后端 API，前后端解耦

***

## 快速启动

### 1. 环境准备

```bash
# 检查环境兼容性（Python 3.10+ 必须）
python scripts/env_check.py

# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate

# 安装依赖
pip install -e ".[dev]"
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，配置 LLM 参数：

```env
# LLM配置（支持OpenAI兼容接口）
LLM_MODEL=mimo-v2.5-pro
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

# 数据库配置
DB_PATH=data/test_db.sqlite

# API配置
API_BASE_URL=http://localhost:8001
```

### 3. 启动服务

```bash
# 终端1：启动后端
$env:HF_HOME="$PWD\.hf_cache"
.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8001

# 终端2：启动前端
.venv\Scripts\python.exe gradio_app.py
```

访问 <http://localhost:7865> 使用界面。

***

## API 接口

| 方法   | 路径            | 说明           |
| ---- | ------------- | ------------ |
| GET  | `/health`     | 健康检查         |
| GET  | `/api/schema` | 获取数据库表结构     |
| GET  | `/api/tables` | 获取所有表名       |
| POST | `/api/query`  | 自然语言查询（核心接口） |

### POST /api/query 示例

```bash
curl -X POST http://localhost:8001/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "查询2026年1月的订单总金额"}'
```

响应：

```json
{
  "success": true,
  "response": "查询执行成功\n\n**执行SQL**：...",
  "sql": "SELECT SUM(pay_amount) FROM orders WHERE order_time >= ? AND order_time <= ?",
  "validation_report": {"quality_score": 100, ...}
}
```

***

## 项目结构

```
.
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 入口
│   ├── agent/
│   │   ├── __init__.py
│   │   └── workflow.py         # LangGraph Agent 工作流
│   ├── rag/
│   │   ├── __init__.py
│   │   └── metadata_store.py   # RAG 向量存储（单例模式）
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── sql_executor.py     # SQL 执行器（含语法校验）
│   │   └── data_validator.py   # 数据质量校验
│   └── tests/                  # pytest 测试
├── data/
│   ├── data_generator.py       # 测试数据生成
│   ├── test_db.sqlite          # SQLite 测试数据库
│   └── chroma_db/              # Chroma 向量库
├── scripts/
│   └── env_check.py            # 环境兼容性检查
├── .trae/                      # Trae 配置
│   ├── rules/                  # 编码规范/兼容性/决策规则
│   ├── skills/                 # Agent Skills
│   ├── agents/                 # Agent 配置
│   └── prompts/                # 提示词模板
├── gradio_app.py               # Gradio 前端
├── pyproject.toml              # 项目配置
├── Dockerfile                  # Docker 部署
└── README.md                   # 本文档
```

***

## 版本记录

### v0.1.0 (2025-05-08)

**初始版本** — 完成 MVP 最小可用闭环

#### 核心功能

- [x] 自然语言 → SQL 自动生成（基于 LLM）
- [x] SQL 语法校验与参数化执行
- [x] 数据质量校验（空值、值域、评分）
- [x] Gradio 极简前端对话界面
- [x] FastAPI RESTful API
- [x] SQLite 测试数据库（4张表，模拟电商数据）
- [x] RAG 元数据检索（HuggingFace + Chroma）

#### Bug 修复

| # | 问题                         | 修复文件                                                      |
| - | -------------------------- | --------------------------------------------------------- |
| 1 | Python 3.8 与 langgraph 不兼容 | 创建 `.venv`（Python 3.10）                                   |
| 2 | `.env` 文件未被加载              | `main.py`/`gradio_app.py` 添加 `load_dotenv(override=True)` |
| 3 | API\_BASE\_URL 端口不匹配       | `.env` 修正为 `localhost:8001`                               |
| 4 | LLM 模型名错误（mimoV2.5pro）     | `.env` 修正为 `mimo-v2.5-pro`                                |
| 5 | Gradio 6.x Chatbot 消息格式不兼容 | `gradio_app.py` tuple → dict 格式                           |
| 6 | 后端进程异常退出                   | 端口冲突排查，稳定运行在 8001                                         |

#### 性能优化

| # | 优化项                   | 效果                      | 文件                  |
| - | --------------------- | ----------------------- | ------------------- |
| 1 | MetadataStore 全局单例    | Embedding 加载 5-15s → 0s | `metadata_store.py` |
| 2 | 跳过 RAG，全量 schema 内存缓存 | 向量检索 0s                 | `workflow.py`       |
| 3 | 合并 LLM 调用（2次→1次）      | 网络往返 -50%               | `workflow.py`       |
| 4 | 提示词优化（添加 GROUP BY 示例） | SQL 准确率提升               | `workflow.py`       |

**优化结果**：单次查询耗时 **48s+ → 20s**（提速 58%）

***

## Trae 规范

项目遵循 `.trae/rules/` 下的规范文件：

| 文件                  | 说明                                      |
| ------------------- | --------------------------------------- |
| `code_standards.md` | Python 编码规范（PEP8、类型注解、Google Docstring） |
| `compatibility.md`  | 依赖兼容性检查规则                               |
| `decision.md`       | 决策确认规则（关键决策需用户审批）                       |
| `project_rules.md`  | 项目架构约束（禁止C盘存储、安全规范）                     |

***

## 已知限制

1. **LLM 依赖**：需要配置有效的 OpenAI 兼容 API Key
2. **性能瓶颈**：LLM 网络调用仍是主要耗时（约 15-20s/次）
3. **SQL 准确率**：复杂多表 JOIN 场景需进一步优化提示词
4. **数据安全**：当前为 MVP 阶段，生产环境需增加权限控制

## 后续建议

- [ ] 引入 LLM 结果缓存（相同查询直接返回）
- [ ] 支持异步流式响应（SSE）
- [ ] 增加 SQL 执行权限分级（只读/读写）
- [ ] 支持更多数据库方言（MySQL、PostgreSQL）
- [ ] 前端增加 SQL 编辑器和结果导出

## License

MIT