# ai-pro

**Repository Path**: johnucle/ai-pro

## Basic Information

- **Project Name**: ai-pro
- **Description**: 用于生成文本到sql的生成
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Text-to-SQL Agent

基于自然语言的数据库查询工具。用户用中文描述问题，AI 自动生成 SQL 并查询数据库，返回结果。

## 功能特性

- **自然语言查询** - 用中文提问，无需编写 SQL
- **多种 SQL 生成方案** - 规则匹配 / 大模型 / Vanna AI (RAG)
- **多 LLM 支持** - OpenAI、DeepSeek、智谱 AI
- **SQL 安全检查** - 自动阻止 DELETE、DROP 等危险操作
- **可视化配置** - 前端界面配置 API Key 和数据库连接
- **实时日志** - 显示每个步骤的耗时

## 技术栈

- **后端**: Python 3.10+ / FastAPI / PyMySQL
- **前端**: React 18 / TypeScript / Vite / TailwindCSS
- **数据库**: MySQL 8.0+
- **LLM**: OpenAI / DeepSeek / 智谱 AI

## 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/johnucle/txt-sql-demo.git
cd txt-sql-demo
```

### 2. 配置环境变量

```bash
# 复制配置模板
cp backend/.env.example backend/.env

# 编辑配置文件
# 填入你的 API Key 和数据库配置
```

### 3. 安装依赖

**后端:**
```bash
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

**前端:**
```bash
cd frontend
npm install
```

### 4. 初始化数据库

```bash
# 导入示例数据库
mysql -u root -p < sample_data/ecommerce.sql

# 或使用 Python 脚本
python init_db.py
```

### 5. 启动服务

**方式一：使用脚本 (Windows)**
```bash
setup.bat      # 安装依赖
start.bat      # 启动服务
stop.bat       # 停止服务
```

**方式二：手动启动**
```bash
# 后端
cd backend
python main.py

# 前端（新终端）
cd frontend
npm run dev
```

### 6. 访问应用

- 前端: http://localhost:5173
- 后端: http://localhost:8000
- API 文档: http://localhost:8000/docs

## 配置说明

### 环境变量 (backend/.env)

```env
# LLM 配置
LLM_PROVIDER=openai          # openai / deepseek / zhipu
LLM_API_KEY=your-api-key     # 你的 API Key
LLM_BASE_URL=                 # 可选，自定义 API 地址
LLM_MODEL=gpt-3.5-turbo      # 模型名称

# SQL 生成方案
SQL_GENERATOR=auto            # rules / llm / vanna / auto

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your-password
DB_NAME=ecommerce
```

### SQL 生成方案对比

| 方案 | 速度 | 准确性 | 特点 |
|------|------|--------|------|
| `rules` | 毫秒级 | 中等 | 规则匹配，无依赖 |
| `llm` | 30-60秒 | 高 | 大模型生成，灵活 |
| `vanna` | 1-5秒 | 很高 | RAG 学习，越用越准 |
| `auto` | 自适应 | 高 | 先规则，失败用 LLM |

## 示例查询

- 查询所有用户
- 销量最高的商品是什么
- 价格最低的3个商品
- 统计每个分类有多少商品
- 查找金额超过10000元的订单
- 最近7天的订单
- 哪个用户消费最多
- 计算总销售额

## 项目结构

```
txt-sql-demo/
├── backend/                  # 后端代码
│   ├── main.py              # FastAPI 入口
│   ├── config.py            # 配置管理
│   ├── llm/                 # LLM 服务
│   │   ├── base.py          # 基础接口
│   │   ├── openai_provider.py
│   │   ├── deepseek_provider.py
│   │   ├── zhipu_provider.py
│   │   └── vanna_provider.py  # Vanna AI 支持
│   ├── sql/                 # SQL 处理
│   │   ├── safety.py        # 安全检查
│   │   ├── generator.py     # SQL 生成
│   │   ├── executor.py      # SQL 执行
│   │   └── rule_engine.py   # 规则引擎
│   ├── db/                  # 数据库
│   │   ├── mysql.py         # MySQL 连接
│   │   └── schema.py        # Schema 解析
│   ├── requirements.txt
│   └── .env.example         # 配置模板
├── frontend/                 # 前端代码
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/
│   │   │   ├── Chat.tsx
│   │   │   ├── ConfigPanel.tsx
│   │   │   ├── ResultTable.tsx
│   │   │   └── SqlPreview.tsx
│   │   ├── api/
│   │   └── types/
│   └── package.json
├── sample_data/
│   └── ecommerce.sql        # 示例数据库
├── setup.bat                # 安装脚本 (Windows)
├── start.bat                # 启动脚本 (Windows)
├── stop.bat                 # 停止脚本 (Windows)
├── init_db.py               # 数据库初始化脚本
└── README.md
```

## API 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/chat` | POST | 发送自然语言问题 |
| `/api/config` | GET | 获取当前配置 |
| `/api/config` | POST | 更新配置 |
| `/api/schema` | GET | 获取数据库结构 |
| `/api/databases` | GET | 获取数据库列表 |
| `/api/health` | GET | 健康检查 |

## Vanna AI 使用

Vanna 使用 RAG 技术，从历史查询中学习，越用越准确。

```bash
# 安装 Vanna
pip install vanna

# 配置
SQL_GENERATOR=vanna
```

训练数据位置: `backend/llm/vanna_provider.py`

## 安全说明

- 仅允许执行 SELECT 查询
- 自动阻止 DELETE、DROP、UPDATE 等危险操作
- 敏感配置不会提交到仓库

## License

MIT