# GlmN2SQL

**Repository Path**: aricluo/glm-n2-sql

## Basic Information

- **Project Name**: GlmN2SQL
- **Description**: GlmN2SQL
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智问数 ChatData — 智能问数系统

基于 **Python Flask + MySQL** 的智能问数(ChatBI)系统:用一句自然语言查询数据库,自动完成
**语义解析 → SQL 生成 → 安全护栏校验 → 执行 → 表格与图表呈现**,开箱即用。

![技术栈](https://img.shields.io/badge/Flask-3.1-blue) ![MySQL](https://img.shields.io/badge/MySQL-8.0-orange) ![Python](https://img.shields.io/badge/Python-3.10+-green) ![tests](https://img.shields.io/badge/tests-97%20passed-brightgreen)

## ✨ 核心特性

- **零依赖问数引擎**:内置中文 NL2SQL 解析器(时间/聚合/维度/筛选/排名识别 + 外键自动 JOIN),
  不依赖任何外部大模型服务,离线可用;基于列注释、取样值与同义词词表做语义匹配。
- **三层数据安全**:① SQL 安全护栏(只读校验、危险关键词/系统库/系统变量拦截、LIMIT 钳制);
  ② 会话级只读(`SET SESSION TRANSACTION READ ONLY`);③ 最小权限只读账号(添加数据源自动降权)。
- **图表自动推断**:趋势折线图、占比饼图、对比柱状图、指标大卡、明细表格,按问句语义与结果形态自动选择。
- **完整工作台**:对话式问数、解析过程透明展示、生成 SQL 可查看/复制、CSV 导出、历史记录回放、
  数据源管理(新增/编辑/测试/删除)、元数据浏览、用户/审计管理后台。
- **多数据源**:支持接入任意 MySQL 库(密码加密存储),内置 3 万行零售演示库。

## 🚀 快速开始

```bash
# 1. 安装依赖(首次)
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt

# 2. 初始化数据库(平台库 + 演示库 + 只读账号 + 种子用户,幂等可重复执行)
.venv\Scripts\python scripts\init_db.py

# 3. 启动服务
.venv\Scripts\python run.py
```

访问 <http://127.0.0.1:8000> (工作台) · <http://127.0.0.1:8000/promo> (产品宣传页)

| 账号 | 用户名 | 默认密码 | 说明 |
|------|--------|----------|------|
| 管理员 | `admin` | `Admin@2026` | 可访问管理后台(用户管理/审计日志),**上线前请修改** |
| 演示用户 | `demo` | `Demo@2026` | 普通用户,体验问数 |

> 数据库连接默认 `127.0.0.1:3306 root/root123456`,可通过环境变量
> `N2SQL_DB_HOST / N2SQL_DB_PORT / N2SQL_DB_USER / N2SQL_DB_PASSWORD / N2SQL_PLATFORM_DB` 覆盖。

## 💬 试试这些问题

```
今年每个月的销售额趋势          上个月消费金额最高的前10名客户
各产品类别的销量对比            各支付方式的订单金额占比
北京的客户有多少                库存低于100的商品有哪些
最近30天每天的下单客户数        华东地区金卡会员的订单金额合计
销售额超过100万的城市           2025年各区域的订单金额
```

支持的问法要素:**时间**(今年/上个月/最近N天/2025年3月/今年Q1…)、**聚合**(合计/平均/最大/最小/多少/去重计数)、
**分组**(按X/各X/每月/趋势/排名/占比)、**筛选**(城市/状态等枚举值、大于/低于N、介于、名称包含)、
**TopN**(前10名/Top10)。

## 📁 目录结构

```
GlmN2SQL/
├── app/
│   ├── __init__.py          # 应用工厂:安全头/CSRF/gzip/错误处理
│   ├── config.py            # 配置(密钥自动生成并持久化)
│   ├── db.py                # 连接池(DBUtils)+ 参数安全内联
│   ├── models.py            # 数据访问层(用户/数据源/历史/审计)
│   ├── security.py          # 口令散列/Fernet 加密/CSRF/登录锁定/限流
│   ├── api/                 # REST 接口(auth/datasources/query/history/admin)
│   ├── nl2sql/              # 问数引擎
│   │   ├── parser.py        #   中文语义解析(意图识别)
│   │   ├── generator.py     #   SQL 生成(自动 JOIN/分组/排序)
│   │   ├── guard.py         #   SQL 安全护栏
│   │   └── schema_extractor.py  # 元数据内省与缓存
│   ├── templates/           # 页面(index/login/error)
│   └── static/              # 样式/脚本/ECharts(本地化,无外网依赖)
├── scripts/
│   ├── init_db.py           # 数据库初始化(幂等)
│   ├── smoke_nl2sql.py      # 引擎冒烟脚本
│   └── benchmark.py         # 性能基准
├── tests/                   # pytest 测试(87 项)
├── docs/                    # 需求/设计/安全审查文档
├── promo/                   # 产品宣传网页
├── instance/                # 密钥与口令(自动生成,勿提交)
└── run.py                   # 生产启动入口(waitress)
```

## 🧪 测试

```bash
.venv\Scripts\python -m pytest          # 97 项:护栏/解析/认证/问数/历史/权限隔离/大模型开关
.venv\Scripts\python scripts\benchmark.py  # 性能基准(P50 ≈ 5ms)
```

## 🔒 安全要点(详见 docs/安全审查与测试报告.md)

- 所有查询经**只读护栏 + 只读会话 + 只读账号**三重防护,写操作在 SQL 层、会话层、权限层均被拒绝;
- 平台元数据库与业务库物理隔离,业务问数无法触及 `mysql / information_schema` 等系统库;
- 登录防爆破(5 次失败锁定 15 分钟)、CSRF 双提交校验、scrypt 口令散列、Fernet 加密数据源口令;
- 完整审计日志(登录/问数/SQL 执行/数据源变更/管理操作)。

## 🤖 配置大模型(可选,v1.1)

系统默认使用**纯规则引擎**,不依赖任何大模型服务。v1.1 起支持"规则引擎优先 + 大模型兜底"双引擎:
开启后,仅当规则引擎无法理解某个问法时,才把库结构与问题交给大模型生成 SQL——生成的 SQL **仍会经过
安全护栏(只读/限行/限时)校验后才执行**。

**配置入口**:以管理员登录 → 左下角「🤖 大模型设置」→ 填写并保存:

| 参数 | 说明 |
|------|------|
| 启用大模型兜底引擎 | 总开关,关闭时行为与 v1.0 完全一致 |
| API 地址 | OpenAI 兼容根路径,如 `https://open.bigmodel.cn/api/paas/v4`、`https://api.deepseek.com/v1`、`http://localhost:11434/v1`(Ollama) |
| 模型名称 | 如 `glm-4-flash`、`deepseek-chat`、`qwen2.5:7b` |
| API Key | Fernet 加密落库,界面只显示脱敏形式(如 `sk-d****3456`),留空保存表示不修改 |
| 温度 / 超时 | 建议 0~0.3(求稳);超时 5~120 秒 |

「测试连接」按钮会用表单当前值发送真实请求验证连通性。设置变更与测试均写入审计日志。

也可用环境变量提供**初始默认值**(管理后台保存后以后台为准):
`N2SQL_LLM_ENABLED`、`N2SQL_LLM_BASE_URL`、`N2SQL_LLM_MODEL`、`N2SQL_LLM_API_KEY`、
`N2SQL_LLM_TEMPERATURE`、`N2SQL_LLM_TIMEOUT_S`。

## ⚠️ 已知限制(规则引擎边界)

- 复杂问法(多跳关联、同比环比、嵌套子查询)暂不支持,会给出引导提示而非错误结果;
- 语义匹配基于词表与列注释,未覆盖的业务黑话可在 `app/nl2sql/parser.py` 的 `SYNONYMS` 词表中扩充;
- 单机内存限流,多实例部署需替换为 Redis 方案(预留 `SlidingWindowLimiter` 接口)。