# nl2sql

**Repository Path**: mzb329/nl2sql

## Basic Information

- **Project Name**: nl2sql
- **Description**: nl2sql的agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-22
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PocketFlow MCP 数据库查询 Agent

这是一个使用 PocketFlow 框架构建的 MCP 数据库查询代理，能够将自然语言查询转换为 SQL，然后使用 FastMCP 工具执行查询并格式化结果，并支持生成ECharts可视化图表。

## 特性

- 自然语言转SQL查询（使用LLM）
- 支持SQLite和MySQL数据库
- 使用MCP工具安全执行数据库查询
- 自动调试和修复SQL错误（使用LLM）
- **优化：使用代码而非LLM格式化查询结果**
- 自动将查询结果导出为Excel文件，文件名基于查询内容
- 增强的错误处理和重试机制
- 支持日期类型和复杂数据类型的JSON序列化
- **新增：将SQL查询结果可视化为ECharts动态图表**
- **优化：使用代码而非LLM推荐最适合的图表类型**
- **新增：生成可直接使用的ECharts配置文件**
- **新增：工作流步骤详细日志和性能指标**
- **新增：控制台实时输出各节点处理的详细数据内容**
- **新增：服务管理功能，避免重复启动服务**

## 项目结构

```
.
├── docs/
│   └── design.md          # 设计文档
├── utils/
│   ├── __init__.py
│   ├── llm.py             # LLM调用函数
│   ├── mcp_utils.py       # MCP工具函数
│   ├── chart_utils.py     # 图表生成工具函数
│   └── logging_node.py    # 日志增强节点包装器
├── vector_db_server.py    # 向量数据库服务器
├── simple_db_server_fastmcp.py  # FastMCP数据库服务器
├── chart_server.py        # FastMCP图表生成服务器
├── config.py              # 数据库配置文件
├── nodes.py               # PocketFlow节点定义
├── flow.py                # PocketFlow流程定义
├── main.py                # 主程序入口
├── start_services.sh      # 服务启动脚本
├── run_query.sh           # 查询执行脚本
├── test_logging.py        # 日志功能测试脚本
├── test_console_output.py # 控制台输出测试脚本
├── requirements.txt       # 依赖清单
├── README.md              # 本文件
├── metrics/               # 性能指标存储目录
├── chromadb/              # ChromaDB数据存储目录
├── results/               # 查询结果存储目录
├── test_excel_output/     # Excel导出测试目录
├── test_results/          # 测试结果目录
├── models/                # 模型存储目录
```

## 服务管理

系统现在包含一个服务管理器，能够在主进程启动时启动所需服务，并在整个过程中保持这些服务在线。这样可以避免每次执行查询时重新启动服务，大大提高了效率。

### 管理的服务

- **向量数据库服务器** - 用于相似性检索，端口 8003
- **数据库操作服务器** - 执行SQL查询，端口 8000
- **图表生成服务器** - 生成可视化图表，端口 8050

### 使用脚本

为了方便使用，系统提供了两个脚本：

1. **启动服务** - 单独启动所有服务并保持运行：

```bash
./start_services.sh
```

2. **运行查询** - 利用已运行的服务执行查询：

```bash
# 直接运行查询（交互式输入）
./run_query.sh

# 指定查询
./run_query.sh "查找2023年销售额最高的5个产品"
# 或者
./run_query.sh -q "查找2023年销售额最高的5个产品"

# 启用控制台详细输出
./run_query.sh -c "查询内容"

# 指定输出目录
./run_query.sh -o ./my_results "查询内容"
```

### 命令行参数

`main.py` 现在支持以下命令行参数：

- `--server` - 只启动服务并保持运行
- `--query "查询内容"` - 执行指定查询
- `--chart` - 启用图表生成功能
- `--console-output` - 启用控制台详细数据输出
- `--max-output-length 值` - 设置控制台输出的最大长度
- `--output-dir 路径` - 指定结果输出目录
- `--test` - 运行自动测试

## 安装

1. 克隆仓库

```bash
git clone <repository-url>
```

2. 创建并激活虚拟环境

```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows
```

3. 安装依赖

```bash
pip install -r requirements.txt
```

4. 配置环境变量

创建 `.env` 文件，可以基于 `.env.example` 进行修改:

```
# API密钥 (选择其一或两者都设置)
OPENAI_API_KEY=your_openai_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here

# 数据库类型：sqlite 或 mysql
DB_TYPE=sqlite

# SQLite配置 (当DB_TYPE=sqlite时使用)
SQLITE_DB_PATH=example.db

# MySQL配置 (当DB_TYPE=mysql时使用)
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password_here
MYSQL_DATABASE=example
MYSQL_CHARSET=utf8mb4
```

5. 下载bge-m3模型放在models文件夹下

```bash
git lfs install

git lfs clone https://www.modelscope.cn/BAAI/bge-m3.git
```

## 使用方法

1. 运行主程序

```bash
python main.py
```

2. 选择操作模式：
   - 仅查询模式：生成SQL并输出结果
   - 图表模式：生成SQL、结果和ECharts图表
   - 自动测试模式：使用测试查询

3. 输入自然语言查询，例如：

- "查询价格超过1000元的产品"
- "列出所有已完成的订单及其客户信息"
- "计算每个类别的平均价格并以图表展示"

4. 查看格式化的结果、生成的Excel文件和可视化图表

查询结果会自动保存为Excel文件，文件名基于查询内容生成。Excel文件包含两个工作表：
- 第一个工作表：包含完整的查询结果数据
- 第二个工作表（摘要）：包含查询信息、执行时间、记录数和结果摘要

图表配置文件会保存在results目录下，采用JSON格式，可以直接用于ECharts库渲染。

## 优化的工作流程

本项目优化了LLM使用方式，只在以下环节使用大模型：
1. **自然语言转SQL**：将用户查询转换为SQL语句
2. **SQL错误修复**：当SQL执行失败时，使用LLM分析错误并修复

其他环节使用代码处理：
1. **结果格式化**：使用pandas和HTML模板格式化SQL查询结果
2. **图表推荐**：基于数据特征和用户查询自动推荐合适的图表类型

这种优化减少了LLM调用次数，提高了系统效率和响应速度，同时降低了API成本。

## 支持的图表类型

- **柱状图**：用于比较不同类别的数值大小，适合离散数据和排名数据
- **折线图**：用于展示数据随时间或序列的变化趋势，适合时间序列数据和趋势分析
- **饼图**：用于展示整体中各部分的占比，适合比例数据和构成分析
- **散点图**：用于展示两个变量之间的关系，适合相关性分析和分布模式研究
- **表格**：适用于缺少数值列的数据
- **仪表盘**：适用于单一数值的展示

## MySQL配置说明

如果需要使用MySQL数据库，请在`.env`文件中设置：

```
DB_TYPE=mysql
```

并配置相应的MySQL连接参数。程序会自动创建数据库和示例表，如果指定的数据库不存在。

## 技术栈

- [PocketFlow](https://github.com/the-pocket/PocketFlow) - 轻量级LLM工作流框架
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP服务器和客户端库
- [OpenAI API](https://openai.com/blog/openai-api)/[DeepSeek API](https://deepseek.com/api) - LLM服务
- [Pandas](https://pandas.pydata.org/) - 数据处理和Excel导出
- [ChromaDB](https://www.trychroma.com/) - 向量数据库
- [Sentence Transformers](https://www.sbert.net/) - 文本嵌入
- [PyECharts](https://pyecharts.org/) - 图表生成和ECharts配置
- [ECharts](https://echarts.apache.org/) - 交互式图表库
- SQLite - 轻量级嵌入式数据库
- MySQL - 关系型数据库管理系统

## 许可证

MIT

## 致谢

- PocketFlow团队提供的优秀框架
- FastMCP提供的MCP工具库
- DeepSeek和OpenAI提供的LLM API服务 
- Apache ECharts项目提供的优秀可视化库 

## 详细日志和性能指标

系统现在能够为每个工作流步骤输出详细的日志和性能指标。这些指标帮助我们了解系统的运行情况，诊断问题，并持续优化性能。

### 收集的指标

每个工作流节点会记录以下指标：

- **执行时间**：节点执行每个阶段（准备、执行、后处理）所需的时间
- **数据流大小**：输入和输出数据的大小（字节）
- **重试次数**：节点执行失败重试的次数
- **后续路径**：节点执行完成后选择的后续路径

### 指标输出形式

指标以两种形式输出：

1. **日志文件**：`workflow_metrics.log` 包含详细的节点执行日志
2. **指标文件**：`metrics/` 目录中以 JSON 格式保存每个节点的详细指标
3. **控制台输出**：实时显示每个节点处理的详细数据内容

### 汇总报告

在执行完整个工作流后，系统会生成汇总报告，包括：

- 每个节点的平均执行时间
- 最慢和最快的节点
- 数据流量最大的节点
- 总执行时间

### 控制台详细数据输出

系统现在可以在控制台实时显示每个节点处理的详细输入和输出数据，便于开发和调试：

- **格式化显示**：使用易读的格式显示复杂数据结构
- **阶段区分**：清晰标识准备阶段、执行阶段和后处理阶段的数据
- **截断处理**：自动截断过大的数据，避免控制台被大量数据淹没
- **共享数据追踪**：显示节点对共享数据的修改

控制台输出可以通过参数配置：
- `console_output_enabled`：启用/禁用控制台输出
- `max_console_output_length`：设置最大输出长度

### 使用方法

测试日志功能：

```bash
./test_logging.py
```

测试控制台详细输出功能：

```bash
./test_console_output.py
```

在实际运行中，指标将自动记录到 `metrics` 目录和日志文件中。在测试或主程序结束时，会自动生成汇总报告。