# nlagent

**Repository Path**: QBB/nlagent

## Basic Information

- **Project Name**: nlagent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-20
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SQL Agent 数据分析系统

基于 LangChain 1.0 和 RAG 技术的自然语言转 SQL 智能数据分析系统。

## 功能特性

- 🤖 **AI 驱动的 SQL 生成**：通过自然语言问题自动生成 SQL 查询
- 🗄️ **多数据库支持**：支持 MySQL、Apache Doris、PostgreSQL、SQL Server
- 📊 **数据可视化**：自动生成图表展示查询结果
- 🎓 **RAG 训练数据管理**：支持 SQL 示例、DDL 结构、表文档的增删查改
- 💬 **智能对话**：支持多轮对话，理解上下文
- 🔍 **实时查询**：即时执行 SQL 并展示结果
- 📈 **数据分析报告**：自动生成数据洞察和分析建议
- 🔧 **智能方言识别**：自动识别数据库类型并生成符合该数据库语法的 SQL

## 技术栈

### 后端
- **框架**: FastAPI
- **LLM**: OpenAI API (兼容格式)
- **向量数据库**: Milvus
- **嵌入模型**: Jina Embeddings
- **数据库**: MySQL / Apache Doris / PostgreSQL / SQL Server（多数据库支持）
- **连接池**: DBUtils（MySQL/Doris）
- **Agent**: LangChain 1.0 + LangGraph

### 前端
- **框架**: React + TypeScript
- **构建工具**: Vite
- **UI 组件**: shadcn/ui + Tailwind CSS
- **图表**: Chart.js
- **路由**: React Router

## 快速开始

### 环境要求

- Python 3.11+
- Node.js 18+
- Milvus 2.3+
- **数据库（任选其一）**：
  - MySQL 5.7+ / 8.0+
  - Apache Doris 1.0+
  - PostgreSQL 12+
  - SQL Server 2016+（需安装 ODBC Driver 18）

### 后端配置

1. 进入后端目录：
```bash
cd backend/vanna
```

2. 创建并配置 `.env` 文件（参考 `.env.example`）

3. 安装依赖：
```bash
conda create -n vanna python=3.11
conda activate vanna
pip install -r requirements.txt
```

4. 启动后端服务：
```bash
python api_server.py
```

### 前端配置

1. 进入前端目录：
```bash
cd frontend
```

2. 安装依赖：
```bash
npm install
```

3. 启动开发服务器：
```bash
npm run dev
```

4. 访问 http://localhost:3000

## 项目结构

```
06_LangChainSqlAgent/
├── backend/
│   └── vanna/
│       ├── api_server.py          # FastAPI 服务入口
│       ├── react_agent.py         # Agent 主程序
│       └── src/
│           └── Improve/
│               ├── agent/         # Agent 核心逻辑
│               ├── clients/       # 客户端（Vanna, Embedding）
│               └── middleware/    # 日志和追踪中间件
├── frontend/
│   └── src/
│       ├── components/
│       │   ├── Dashboard.tsx      # 主面板
│       │   ├── ChatPanel.tsx      # AI 对话面板
│       │   ├── QueryPanel.tsx     # SQL 编辑器
│       │   ├── ResultsPanel.tsx   # 结果展示
│       │   └── TrainingDataPanel.tsx  # 训练数据管理
│       └── pages/
│           └── Home.tsx           # 首页
└── README.md
```

## 多数据库支持

本系统支持多种主流数据库，可通过配置文件轻松切换。

### 支持的数据库

| 数据库 | 版本要求 | 特点 | 用途 |
|--------|---------|------|------|
| **MySQL** | 5.7+ / 8.0+ | 最流行的开源关系型数据库 | OLTP 业务系统 |
| **Apache Doris** | 1.0+ | 高性能 OLAP 数据库（兼容 MySQL 协议） | 大数据分析、实时报表 |
| **PostgreSQL** | 12+ | 功能最丰富的开源数据库 | 复杂查询、地理数据 |
| **SQL Server** | 2016+ | 微软企业级数据库 | Windows 企业环境 |

### 数据库配置

在 `backend/vanna/.env` 中配置数据库连接：

**通用配置（推荐）**

```bash
# 数据库类型：mysql | doris | postgresql | sqlserver
DB_TYPE=mysql

# 连接信息
DB_HOST=localhost
DB_PORT=3306
DB_NAME=your_database
DB_USER=your_username
DB_PASSWORD=your_password

# 连接池配置（可选，MySQL/Doris 支持）
DB_POOL_ENABLED=true
DB_POOL_MIN_CACHED=2
DB_POOL_MAX_CACHED=5
DB_POOL_MAX_CONNECTIONS=10
```

**各数据库特定配置**

```bash
# MySQL
DB_TYPE=mysql
DB_PORT=3306

# Apache Doris（注意：使用 FE 查询端口 9030，不是 3306）
DB_TYPE=doris
DB_PORT=9030

# PostgreSQL
DB_TYPE=postgresql
DB_PORT=5432

# SQL Server（需先安装 ODBC Driver 18）
DB_TYPE=sqlserver
DB_PORT=1433
```

### 数据库方言自动识别

系统会自动识别数据库类型并生成符合该数据库语法的 SQL：

- **MySQL**: 支持所有标准特性（事务、存储过程、外键等）
- **Doris**: 自动检测并避免使用不支持的特性（事务、存储过程、用户变量等）
- **PostgreSQL**: 自动使用 PostgreSQL 特有语法（如 RETURNING 子句）
- **SQL Server**: 自动使用 T-SQL 语法（如 TOP、OFFSET FETCH）

### 测试多数据库连接

运行测试脚本验证数据库连接：

```bash
cd backend/vanna
python test_multi_db_connection.py
```

详细测试文档请参考：[TEST_MULTI_DB.md](backend/vanna/TEST_MULTI_DB.md)

### 切换数据库

系统支持运行时动态切换数据库，无需重启服务：

1. 通过前端界面：在"数据源"面板选择数据库类型并连接
2. 通过 API：调用 `/api/v1/database/connect` 接口

切换数据库后，Agent 会自动重新加载并注入对应的数据库方言提示。

## 使用说明

### 1. 数据源配置

在左侧"数据源"标签中：
- 选择数据库类型（MySQL / Doris / PostgreSQL / SQL Server）
- 填写连接信息
- 查看已连接的数据库表

### 2. 训练数据管理

切换到"训练数据"标签：
- 添加 SQL 查询示例（问题 + SQL 语句）
- 添加 DDL 表结构定义
- 添加表文档说明

### 3. AI 对话查询

在右侧对话面板中：
1. 输入自然语言问题
2. AI 自动生成并执行 SQL
3. 查看查询结果和可视化图表
4. 获取数据分析报告

### 4. SQL 手动编辑

在中间 SQL 编辑器中：
- 手动编写或修改 SQL
- 点击执行按钮查询
- 查看结果表格

## 核心功能

### RAG 增强

系统使用 RAG（检索增强生成）技术：
- 从向量数据库检索相似的 SQL 示例
- 检索相关的表结构和文档
- 提升 SQL 生成的准确度

### Agent 工作流

1. 用户提问
2. 检索相关训练数据（RAG）
3. 理解问题意图
4. 生成 SQL 查询
5. 验证 SQL 语法
6. 执行查询
7. 分析结果
8. 生成可视化图表
9. 返回分析报告

## 贡献指南

欢迎提交 Issue 和 Pull Request！

## 开源协议

MIT License

## 联系方式

- GitHub: https://github.com/fufankeji/SQLAgent