内容
## Demo
https://github.com/user-attachments/assets/fe7f040d-f89b-4960-974c-faffb837d60b
---
# SQL 聊天机器人
SQL 聊天机器人是一款智能的**多代理 GenAI 应用程序**，使用**谷歌 ADK（代理开发工具包）**构建。
它允许用户使用**自然语言**与 Excel 和 CSV 文件交互，自动将问题翻译成**安全、了解模式的 SQL 查询**，并通过现代 Web 界面返回清晰的结构化结果。
系统自动：
- 用普通英语理解用户的问题
- 生成安全有效的 SQL 查询
- 在用户上传的数据上执行查询
- 以易于阅读的格式返回结果
---
## ❓ 为什么使用 SQL 聊天机器人？
传统的數據分析需要用戶編寫複雜的 SQL 查询，并了解數據庫模式和表格關係。这可能耗時且具有挑戰性，尤其是對於不熟悉 SQL 的用戶。
SQL 聊天机器人通过允许用户用普通英语提问来消除这一障碍。
聊天机器人理解自然语言查询，在后台生成安全准确的 SQL，执行数据查询，并以清晰易读的格式返回结果。
---
## 🏗️ 系统架构
---
## ✨ SQL 聊天机器人的主要功能
- **用普通英语提问**：无需编写复杂的 SQL 查询。只需用自然语言提问，即可获得清晰易懂的答案。
- **一次查询多个文件**：无需编写 SQL，即可跨多个上传的 Excel 或 CSV 文件提问。
- **支持复杂的多部分问题**：聊天机器人可以处理复杂查询，请求不同类型的信息（不限于单个或多个人员）。
- **设计为只读和安全**：仅允许 SELECT（读取）操作。您的数据始终受到保护，不会更新、删除或插入。 不允许写入操作。
- **智能后续问题建议和新用户起始问题**：聊天机器人会在每次回复后建议相关后续问题，并在聊天开始或提出一般性查询时提供起始问题，帮助用户轻松探索数据而不会卡住。
- **用户界面中代理可见**：聊天界面清楚地显示了** orchestrator 选择的 AI 代理**。
- **查看生成的数据库模式**：通过**“显示模式”**按钮，用户可以查看从上传文件生成的模式。
- **MCP（模型上下文协议）集成**：MCP 支持允许聊天机器人**安全地公开工具、模式和资源**，使其更具扩展性和强大功能。
---
## 👥 可用代理
聊天机器人使用**5 个专门的 AI 代理**，每个代理都有特定的责任：
### 1️⃣ **协调器代理（入口点）**
- **责任：** 这是主要的入口点代理，负责将用户查询路由到适当的子代理。
它分析用户的意图，并将其转移到问候代理或 SQL 代理。
### 2️⃣ **问候代理**
- **责任：** 此代理欢迎用户并介绍 SQL 聊天机器人系统。它解释了聊天机器人可以做什么以及用户应该如何继续。
- **功能：**
- 使用 `get_schema` 工具获取模式
- 生成与用户数据相关的样本问题
### 3️⃣ **SQL 代理（顺序协调器）**
- **责任：** SQL 代理通过 2 个子代理顺序处理 SQL 查询。
- **2 步流程：**
1. 输入验证和 SQL 生成代理：- 验证用户输入 + 生成 SQL
2. SQL 验证器和 SQL 执行器代理：- 验证 SQL + 执行 SQL
### 4️⃣ **输入验证和 SQL 生成代理**
- **责任：**
1. 该代理验证用户输入并生成安全的 SQL 查询。
2. 验证用户输入的安全性（仅允许读取查询，不允许写入操作）
3. 检查请求的列/表格是否存在
4. 生成有效的 SQL 查询
- **工具：** `get_schema`
- **输出：**
- 在 `state['generated_sql']` 中存储生成的 SQL
- **关键：** 将检索到的完整 `schema` 传递给下一个代理
- **验证规则：**
- 拒绝不安全的查询
- 警告缺少的列
- 仅使用现有的模式列
### 5️⃣ **SQL 验证器和 SQL 执行器代理**
- **责任：**
1. 该代理验证 SQL，执行它，并返回用户友好的响应。
2. 与模式进行交叉检查（从前一个代理接收）
3. 使用 `execute_sql()` 工具执行 SQL
4. 生成查询后的**建议（后续问题）**
- **工具：** `execute_sql`
- **输入：** 从 `state['generated_sql']` 读取 SQL 和模式
- **输出：** 在 `state['query_result']` 中存储结果
---
## 🔌 模型上下文协议（MCP）
该应用程序使用**模型上下文协议（MCP）**来规范 AI 代理与外部工具和数据之间的交互。
### **架构**
- **MCP 服务器**：一个独立的进程（在端口 `8001` 上运行），公开 `get_schema` 和 `execute_sql` 工具。它可以直接访问数据库和文件系统。
- **MCP 客户端**：AI 代理作为客户端，使用 **SSE（服务器发送事件）**连接到服务器。
### **为什么使用 MCP？**
- **解耦：** 工具与代理逻辑分离。
- **标准化：** 提供统一的工具发现和执行接口。
- **可扩展性：** 服务器可以独立部署或单独扩展。
---
## 📂 文件上传和数据流程
了解数据从上传到查询执行的过程：
### **步骤 1：上传文件**
- 您通过 Web 界面上传 Excel 或 CSV 文件。
- 系统仅接受有效的 文件类型：`.csv`、`.xlsx`、`.xls`。
- 自动检测并避免重复文件。
### **步骤 2：保存文件**
- 上传的文件安全地存储在 `uploads/` 文件夹中。
- 每个文件都使用唯一的 ID（UUID）重命名，以避免冲突。
- 文件详细信息，例如：
- 原始文件名
- 上传时间
- 文件哈希
保存在 `metadata/` 文件夹中。
### **步骤 3：创建模式**
- 系统读取上传的文件以了解：
- 列名
- 数据类型（文本、数字、日期等）
- 以 JSON 格式生成模式（数据结构）。
- 此模式保存在 `schemas/` 文件夹中。
### **步骤 4：数据存储在数据库中**
- 使用 Pandas 加载文件的數據。
- 所有行都插入到持久的 SQLite 数据库（`database/chatbot.db`）中。
- 此数据库针对快速可靠的 SQL 查询进行了优化。
### **步骤 5：提问**
- 当您用自然语言提问时：
- AI 使用存储的模式来理解您的数据。
- 生成安全的 SQL 查询。
- 查询在 SQLite 数据库上执行。
- 结果以清晰的用户友好格式返回给您。
---
## 🚀 设置和安装
请按照以下步骤在本地设置和运行 SQL 聊天机器人。
### **先决条件**
确保您的系统已安装以下内容：
- Python 3.8+
- Node.js 14+（用于 Angular 前端）
- 以下 API 提供商之一：
- Google Gemini API 密钥（通过 Google ADK），或
- Azure OpenAI API 密钥
### **步骤 1：克隆存储库**
```bash
git clone <repository-url>
cd genai-sql-chatbot
```
### **步骤 2：创建虚拟环境**
```bash
python -m venv venv
```
### **步骤 3：激活虚拟环境**
```bash
# Windows
venv\Scripts\Activate
# Linux/Mac
source venv/bin/activate
```
### **步骤 4：安装依赖项**
```bash
pip install -r requirements.txt
```
### **步骤 5：设置 API 密钥**
在项目根目录创建 `.env` 文件：
✅ 选项 1：谷歌 Gemini（谷歌 ADK）
```env
GOOGLE_API_KEY=your_google_api_key_here
MODEL=gemini-2.0-flash-exp
```
✅ 选项 2：Azure OpenAI
```env
AZURE_OPENAI_API_KEY=your_azure_openai_api_key_here
AZURE_OPENAI_ENDPOINT=your_azure_openai_endpoint_here
AZURE_OPENAI_API_VERSION=your_api_version_here
MODEL=your_azure_openai_model_name
```
### **步骤 6：运行 MCP 服务器**
MCP 服务器必须运行，以便 AI 代理可以访问诸如模式检索和 SQL 执行等工具。
```bash
python -m src.app.mcp.server.mcp_server
```
MCP 服务器将在：`http://localhost:8001` 启动
### **步骤 7：启动后端（FastAPI）服务器**
打开新的终端，重新激活虚拟环境，然后运行：
```bash
# 使用 Python 模块
python -m src.app.main_fastapi
# 或直接使用 uvicorn
uvicorn src.app.main_fastapi:app --host 0.0.0.0 --port 8000 --reload
```
后端将在：`http://localhost:8000` 启动
### **步骤 8：运行前端 **
```bash
cd src/ui
npm install
npm start
```
前端将在：`http://localhost:4200` 启动
---
## 📝 如何使用
### **1. 上传文件**
- 在 Web 界面中单击“上传文件”
- 选择 Excel（.xlsx，.xls）或 CSV 文件
- 聊天机器人将自动提取模式
### **2. 提问**
使用自然语言查询您的数据：
**示例：**
```
"显示所有记录"
"数据中有多少行？"
"列名是什么？"
"列出薪水 > 50000 的所有员工"
"按部门获取平均年龄"
"显示薪酬最高的 10 名员工"
"统计状态为“活跃”的记录数"
```
### **3. 查看结果**
- 聊天机器人将显示：
- 它正在执行的操作的说明
- 生成的 SQL 查询
- 以格式化表格形式显示的结果
---
## 🧰 技术栈
### **后端**
- **FastAPI** - 现代 Python Web 框架
- **谷歌 ADK** - 多代理 AI 的代理开发工具包
- **模型上下文协议（MCP）** - 标准化工具接口
- **FastMCP** - 用于构建 MCP 服务器的框架
- **谷歌 Gemini** - 用于自然语言理解的 LLM
- **Azure OpenAI** - 用于自然语言理解的 LLM
- **SQLite** - 用于查询执行的内存数据库
- **Pandas** - Excel/CSV 文件处理
### **前端**
- **Angular** - Web 应用程序框架
- **TypeScript** - 类型安全的 JavaScript
- **HTML/CSS** - 现代、响应式 UI
### **开发工具**
- **Uvicorn** - ASGI 服务器
- **Pydantic** - 数据验证
- **Python-dotenv** - 环境配置
---
## 📂 项目结构
```
genai-sql-chatbot/
├── src/
│ ├── app/
│ │ ├── agents/ # 所有 AI 代理
│ │ │ ├── orchestrator_agent/
│ │ │ ├── greeting_agent/
│ │ │ ├── sql_agent/
│ │ │ ├── inputValidationAndSqlGeneration_agent/
│ │ │ └── sqlValidatorAndSqlExecutor_agent/
│ │ ├── api/ # API 路由
│ │ │ ├── chat.py
│ │ │ ├── file_manager.py
│ │ │ └── health.py
│ │ ├── mcp/ # MCP 实现
│ │ │ ├── server/ # MCP 服务器和工具集
│ │ │ │ ├── mcp_server.py
│ │ │ │ └── mcp_toolset.py
│ │ │ └── tools/ # 实际工具实现
│ │ │ ├── get_schema.py
│ │ │ └── execute_sql.py
│ │ ├── services/ # 业务逻辑
│ │ ├── utils/ # 帮助函数
│ │ ├── configs/ # 配置
│ │ └── main_fastapi.py # 应用程序入口
│ └── ui/ # Angular 前端
├── uploads/ # 上传的文件
├── schemas/ # 存储的模式
├── requirements.txt
└── README.md
```
