# llm_gen_sql

**Repository Path**: ets3355/llm_gen_sql

## Basic Information

- **Project Name**: llm_gen_sql
- **Description**: 利用大模型实现智能问数，txt2sql，本地私有化部署
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-08
- **Last Updated**: 2025-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 问数, txt2sql, 大模型问数, 智能问数, Postgresql

## README



# 基于LangChain + SQLChain + PostgreSQL + Gradio + Ubuntu的离线部署方案

## 一、项目背景与目标
在企业数据分析场景中，业务人员往往面临SQL查询技术门槛高的问题。本方案旨在Ubuntu环境下，构建一套基于LangChain框架、SQLChain组件、PostgreSQL数据库和Gradio前端的离线文本转SQL系统，实现以下目标：
- 提供直观的Web交互界面，支持业务人员通过自然语言查询PostgreSQL数据
- 全流程离线部署，确保敏感数据不出本地环境
- 兼容PostgreSQL特有语法（JSONB操作、窗口函数等）
- 系统轻量易部署，适合中小企业快速落地

## 二、技术架构设计
### 2.1 整体架构图
```
┌─────────────────────────────────────────────────────────────┐
│                      客户端层 (浏览器)                       │
└───────────────────────────────┬─────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────┐
│                     应用层 (Gradio界面)                      │
│  (自然语言输入、SQL展示、结果可视化、历史记录、配置管理)       │
└───────────────────────────────┬─────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────┐
│                     核心层 (LangChain)                       │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐    │
│  │  SQLChain     │  │ 表结构管理模块 │  │  Prompt优化   │    │
│  │ (文本转SQL)   │  │ (元数据处理)   │  │ (定制模板)    │    │
│  └───────────────┘  └───────────────┘  └───────────────┘    │
└───────────────────────────────┬─────────────────────────────┘
                                │
           ┌────────────────────┴────────────────────┐
           │                                         │
┌──────────▼──────────┐                ┌────────────▼───────────┐
│   模型层            │                │   数据层               │
│ (Ollama + Qwen3)    │                │ (PostgreSQL数据库)     │
│ (本地LLM服务)       │                │                        │
└─────────────────────┘                └────────────────────────┘
```

### 2.2 核心组件说明
1. **客户端层**：用户通过浏览器访问Gradio界面进行交互
2. **应用层**：基于Gradio构建的Web界面，提供：
   - 自然语言输入框（带💬图标）
   - SQL查询结果展示区（带📊图标）
   - 生成的SQL语句显示（带💻图标）
   - 历史查询记录（带📋图标）
   - 简单的配置选项（如查询结果数量）
3. **核心层**：
   - LangChain框架：提供组件集成和流程管理
   - SQLChain：实现文本到SQL的核心转换逻辑
   - 表结构管理：自动获取和缓存PostgreSQL表结构
4. **模型层**：Ollama运行时环境加载Qwen3模型，负责自然语言理解和SQL生成
5. **数据层**：PostgreSQL数据库，存储业务数据

## 三、环境配置与部署方案
### 3.1 硬件要求
- CPU：4核及以上（推荐8核）
- 内存：16GB及以上（Qwen3:0.6B模型最低8GB）
- 磁盘：至少50GB可用空间（含系统、数据库、模型和应用）

### 3.2 软件环境
| 组件         | 版本要求                | 说明                     |
|--------------|-------------------------|--------------------------|
| Ubuntu       | 20.04 LTS / 22.04 LTS   | 操作系统                 |
| Python       | 3.10                    | 运行环境                 |
| PostgreSQL   | 14.18                   | 目标数据库               |
| Ollama       | 最新稳定版               | LLM运行时                |
| Qwen3模型    | qwen3:0.6b / qwen3:1.8b | 文本转SQL模型            |
| Gradio       | 3.48+                   | 前端交互框架             |
| LangChain    | 0.1.0+                  | LLM应用框架              |

### 3.3 部署步骤
#### 3.3.1 创建并激活虚拟环境
```bash
# 创建虚拟环境
python3 -m venv venv-sql

# 激活虚拟环境
source venv-sql/bin/activate
```

#### 3.3.2 系统依赖安装
```bash
# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装必要的系统库
sudo apt install -y libpq-dev  # PostgreSQL开发库
```

#### 3.3.3 模型部署
使用本地部署的Ollama kirito1/qwen3-coder:4b
```bash
# Ollama配置
OLLAMA_HOST=http://172.30.160.1:11434
OLLAMA_MODEL=kirito1/qwen3-coder:4b
```

#### 3.3.4 应用部署
```bash
# 安装Python依赖
pip install --upgrade pip
pip install -r requirements.txt

# 创建配置文件（根据实际环境修改）
详见.env文件

## 四、核心功能实现
### 4.1 数据库连接与表结构管理
数据库连接通过`src/db/database.py`中的`PostgreSQLConnector`类实现：
### 4.2 LLM模型与SQLChain初始化
LLM模型和SQLChain的初始化在`src/llm/sql_generator.py`中实现：

### 4.3 Gradio前端界面实现
Gradio前端界面在`src/ui/gradio_interface.py`中实现，提供直观易用的Web界面：

主要功能包括：
1. **自然语言输入**：用户可以通过带💬图标的文本框输入自然语言查询问题，系统将自动将其转换为SQL语句。
2. **SQL展示**：生成的SQL语句将在带💻图标的区域展示，方便用户查看和验证。
3. **结果可视化**：查询结果以带📊图标的表格形式展示，支持基本的数据浏览和导出功能。
4. **历史记录**：系统自动保存用户的查询历史，包括问题、生成的SQL语句和查询结果，通过📋图标标签页展示。
5. **配置管理**：提供简单的配置选项，如设置最大历史记录数、选择允许访问的表等，通过⚙️图标标识。

## 五、安全与权限控制
1. **数据库权限控制**
   - 创建只读用户限制查询权限：
   ```sql
   -- 创建只读用户
   CREATE USER sql_query_ro WITH PASSWORD 'secure_password';
   -- 授予连接权限
   GRANT CONNECT ON DATABASE your_db TO sql_query_ro;
   -- 授予特定表的查询权限
   GRANT USAGE ON SCHEMA public TO sql_query_ro;
   GRANT SELECT ON products TO sql_query_ro;
   ```

2. **应用层安全**
   - 限制可访问的表（通过`ALLOWED_TABLES`配置）
   - 记录所有查询操作日志，支持审计追踪
   - 禁止执行修改数据的操作（通过数据库用户权限控制）

3. **网络安全**
   - Gradio服务默认只监听本地端口，如需外部访问需配置防火墙
   - 生产环境建议配置Nginx反向代理并添加HTTPS

## 六、优化与扩展
### 6.1 性能优化
1. **表结构缓存**：减少重复获取表结构的开销
2. **查询结果缓存**：对相同查询进行结果缓存
3. **模型优化**：
   - 根据硬件选择合适大小的模型
   - 调整Ollama的`num_ctx`参数优化上下文长度

### 6.2 功能扩展
1. **多轮对话**：支持上下文关联的连续查询
2. **SQL解释**：添加生成SQL的解释说明
3. **结果可视化**：集成图表展示功能（matplotlib/plotly）
4. **查询模板**：预设常用查询模板，简化操作
5. **权限管理**：添加用户认证和不同用户的表访问权限控制

## 七、启动应用
```bash
# 确保虚拟环境已激活
source venv-sql/bin/activate

# 启动应用
python app.py
```
应用将启动在 `http://0.0.0.0:7861`，可通过浏览器访问。

## 八、常见问题排查
### 8.1 模型加载失败
- **问题描述**：Ollama无法加载Qwen3模型
- **解决方案**：
  1. 检查网络连接和Ollama服务状态
  2. 确认模型名称和版本正确
  3. 查看Ollama日志获取详细错误信息

### 8.2 数据库连接超时
- **问题描述**：应用无法连接到PostgreSQL数据库
- **解决方案**：
  1. 检查数据库服务是否正常运行
  2. 确认数据库连接字符串配置正确
  3. 检查防火墙设置是否阻止了连接

### 8.3 SQL生成结果不准确
- **问题描述**：生成的SQL语句无法正确执行或结果不符合预期
- **解决方案**：
  1. 优化Prompt模板，提供更明确的指导
  2. 调整LLM的temperature参数
  3. 增加更多的表结构信息和示例

### 8.4 虚拟环境相关问题
- **问题描述**：依赖包版本冲突或找不到模块
- **解决方案**：
  1. 确保使用项目提供的`venv-sql`虚拟环境
  2. 通过`pip install -r requirements.txt`安装依赖
  3. 检查是否在虚拟环境中运行应用

## 九、附录
### 9.1 参考资料
- [LangChain官方文档](https://python.langchain.com/)
- [Gradio官方文档](https://gradio.app/)
- [PostgreSQL官方文档](https://www.postgresql.org/docs/)
- [Ollama官方文档](https://ollama.ai/)

### 9.2 版本历史
| 版本 | 日期       | 说明                     |
|------|------------|--------------------------|
| 1.0  | 2025-08-06 | 初始版本                 |