NLP MySQL 智能数据分析平台 —— 项目概览与技术选型

📖 引言：为什么做这个项目？

在企业的日常运营中，数据查询是最高频的需求之一，但现实却很骨感：

业务人员：想查个数据得找 IT 写 SQL，排队等半天
IT 工程师：整天被”帮我跑个报表”打断，没时间做更有价值的事
数据分析师：熟悉 SQL 但不熟悉每个业务的表结构，每次都要先 DESCRIBE 一遍

能不能让用户用自然语言直接问数据库？

这就是 NLP MySQL 智能数据分析平台 的核心使命 —— 让非技术人员用中文提问，系统自动翻译成 SQL 并返回可视化结果。

🎯 核心功能一览

1. 智能对话（Chat）

1
2
3

用户："查询最近7天每个品类的销售额"
系统：
  ① 理解语义 → ② 生成 SQL → ③ 执行查询 → ④ 返回结果 + 图表

亮点：

✅ 多轮对话上下文支持（”上面的数据按地区再细分一下”）
✅ 自动推荐图表类型（折线图/柱状图/饼图/指标卡）
✅ 可一键生成分析报告

2. 数据大屏（Dashboard）

🎨 拖拽式编辑器：像搭积木一样搭建大屏
⚡ 两阶段分离架构：设计时调 LLM 生成 SQL，运行时纯 SQL 执行（性能提升 10x）
🔥 一键快速生成：输入一句话（”帮我做一个销售概览大屏”），LLM 自动布局 + 配置组件

3. 元数据管理（Metadata）

🤖 LLM 智能解析：自动为表/字段起中文名、推断表关系
🔗 关系可视化编辑：图形化维护外键关系
📊 语义模型构建：将数据库结构转化为 LLM 能理解的 JSON 描述

4. 公式系统（Formula）

📝 预定义参数化 SQL 模板（如”同比环比计算”、”TOP N 排名”）
♻️ 在大屏和对话中复用

🏗️ 技术栈选型与决策理由

后端技术栈

技术	选型版本	为什么选它？
FastAPI	0.100+	⚡ 异步原生支持 + 自动生成 OpenAPI 文档 + Pydantic 集成
SQLAlchemy 2.0 (async)	2.0+	🔀 支持 async/await，避免阻塞事件循环；ORM + Core 双模式
Pydantic v2	2.0+	✅ 数据校验性能提升 5x+；Strict/Loose 模式灵活切换
LiteLLM	1.0+	🌐 统一调用 DeepSeek/OpenAI/Claude 等多种 LLM，一行代码切换模型
aiomysql	0.2+	🚀 MySQL 的异步驱动，配合 SQLAlchemy async 使用
Uvicorn	0.24+	⚡ ASGI 服务器，支持 HTTP/2 和 WebSocket

💡 关键决策 1：为什么选择 FastAPI 而不是 Django/Flask？

# FastAPI 的异步路由示例
@router.post("/api/chat/{session_id}/message")
async def chat(session_id: int, msg: ChatMessageSend, db: AsyncSession = Depends(get_db)):
    # 整个请求链路都是异步的！
    result = await chat_engine.chat(db, session_id, msg.message)
    return result

理由：

原生 async/await：我们的核心流程涉及 LLM API 调用（IO 密集型）+ 数据库查询（IO 密集型），异步可以显著提升并发能力
自动文档：前端同事可以直接看 Swagger UI 调试接口
Pydantic 深度集成：请求/响应模型强类型校验，减少 80% 的参数校验代码

💡 关键决策 2：双数据库架构（SQLite + MySQL）

# database.py — 两套异步引擎
# SQLite: 存储应用元数据（会话、大屏配置、元数据等）
sqlite_engine = create_async_engine("sqlite+aiosqlite:///./app.db")

# MySQL: 用户配置的目标业务数据库（运行时动态连接）
async def get_mysql_connection(datasource_id: int):
    ds = await get_datasource(datasource_id)
    return await aiomysql.connect(host=ds.host, port=ds.port, ...)

为什么要分开？

SQLite（轻量级）：应用自身的元数据量小（几百条记录），无需额外部署 MySQL 服务，开发测试更方便
MySQL（目标库）：用户的业务数据可能很大（百万级），需要专业的关系型数据库；且支持多数据源，用户可配置多个 MySQL 实例

前端技术栈

技术	版本	核心价值
Vue 3	3.4+	Composition API 更适合复杂状态管理；TS 支持完善
TypeScript	5.0+	类型安全，减少运行时错误
Vite	5.0+	⚡ HMR 极快（<50ms），开发体验极佳
Element Plus	2.4+	企业级 UI 组件库，表单/表格/对话框开箱即用
ECharts (vue-echarts)	6.0+	📊 功能最强大的图表库，支持 20+ 图表类型
Pinia	2.1+	Vue 3 官方推荐的状态管理，比 Vuex 更简洁

💡 关键决策 3：为什么不使用低代码平台？

市面上有很多 BI 工具（如 Metabase、Superset），但它们存在以下痛点：

痛点	传统 BI 工具	我们的方案
自然语言查询	❌ 需要手动拖拽字段	✅ 直接中文提问
多数据源关联	⚠️ 配置复杂	✅ LLM 自动推断表关系
定制化程度	❌ 受限于平台模板	✅ 完全自定义 Vue 组件
部署成本	❌ 需要 JVM/大数据集群	✅ 单机 Docker 即可运行
LLM 集成	❌ 大多数不支持	✅ 深度集成 DeepSeek/OpenAI

LLM 技术选型

维度	选择	理由
主模型	DeepSeek-V3	🇨🇳 中文理解能力强；价格仅为 GPT-4 的 1/10
调用层	LiteLLM	🌐 统一接口，未来可无缝切换到 OpenAI/Claude
Prompt 工程	System Prompt + Few-shot	📝 结构化输出控制（强制 JSON 格式）

💡 关键决策 4：为什么用 LiteLLM 而不是直接调 OpenAI SDK？

# llm_gateway.py — 统一网关设计
class LLMGateway:
    def _get_model_name(self, model=None):
        if "deepseek" in self.model.lower():
            return f"deepseek/{self.model}"  # DeepSeek 格式
        return f"openai/{self.model}"        # OpenAI 格式

    async def generate(self, prompt, system_prompt=None):
        response = await litellm.acompletion(
            model=self._get_model_name(),
            messages=[...],
            api_key=self.api_key,
            api_base=self.api_base,
        )
        return response.choices[0].message.content

优势：

零成本切换模型：只需修改 .env 中的 LLM_MODEL=deepseek-chat → LLM_MODEL=gpt-4
统一异常处理：不同 LLM 的错误码被标准化
内置重试机制：网络抖动时自动重试（可配置）

📐 系统整体架构

NLP MySQL 智能数据分析平台系统架构

NLP MySQL 智能数据分析平台系统架构

架构分层说明

第一层：前端展示层（Presentation Layer）

技术栈：Vue 3 + TypeScript + Vite + Element Plus + ECharts
核心模块：
- 智能对话界面（多轮聊天 + 结果展示）
- 数据大屏编辑器（拖拽 + Grid 布局）
- 元数据管理界面（表/字段/关系 CRUD）
- 图表组件库（LineChart / BarChart / PieChart / MetricCard）

第二层：API 网关层（API Gateway）

技术栈：FastAPI Router
职责：
- RESTful 路由分发（/api/chat/*, /api/dashboards/*, …）
- 请求参数校验（Pydantic Schema）
- 统一错误处理（HTTP Exception Handler）

第三层：后端服务层（Business Logic Layer）

7 个核心服务：

服务	文件	职责
LLM Gateway	`llm_gateway.py`	统一 LLM 调用、Prompt 管理、响应清洗
SQL Generator	`sql_generator.py`	NL→SQL 转换、安全验证、执行查询
Chat Engine	`chat_engine.py`	对话上下文管理、图表推荐、报告生成
Dashboard Engine	`dashboard_engine.py`	大屏 CRUD、NL→SQL 解析、渲染逻辑
Metadata Service	`metadata.py`	元数据 CRUD、LLM 智能分析、语义模型构建
Formula Engine	`formula.py`	参数化 SQL 模板执行
Datasource Service	`datasource.py`	数据源连接管理、密码加密

第四层：数据存储层（Data Layer）

**SQLite (aiosqlite)**：应用元数据（会话、大屏配置、元数据、公式定义）
**MySQL (aiomysql)**：目标业务数据库（用户实际查询的数据）
LLM API：DeepSeek / OpenAI 云服务
**环境配置 (.env)**：API Key、数据库连接串等敏感信息

🎬 典型用户场景演示

场景 1：业务人员查询销售数据

场景1：业务人员自然语言查销售数据

用户中文提问，系统返回 SQL 与柱状图结果

场景 2：数据分析师搭建监控大屏

场景2：一键生成运营概览大屏

LLM 自动布局组件，预览阶段不再调用 LLM

📊 项目数据规模（参考）

指标	数值	说明
代码行数	~5,000 行	后端 Python ~3,000 行 + 前端 TS/Vue ~2,000 行
API 接口数	25+	覆盖对话/大屏/元数据/数据源/公式
数据库表数	8 张	SQLite 应用库（dashboards, widgets, sessions, …）
支持的图表类型	5 种	折线图、柱状图、饼图、指标卡、表格
LLM 调用场景	4 类	NL→SQL、元数据分析、大屏生成、报告撰写
单次查询耗时	2~5 秒	含 LLM 调用（~~2s）+ SQL 执行（~~0.1s）
大屏渲染耗时	<200ms	纯 SQL 执行 + ECharts 渲染（无 LLM 调用）

🚀 快速开始

环境要求

Python 3.10+
Node.js 18+
MySQL 8.0+（目标数据库）
DeepSeek API Key（或 OpenAI API Key）

1️⃣ 启动后端

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# 编辑 .env 填入你的 LLM_API_KEY

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2️⃣ 启动前端

1
2
3

cd frontend
npm install
npm run dev

3️⃣ 导入测试数据

1	`mysql -u root -p your_database < test_data.sql`

访问 http://localhost:5173 即可体验！

🎯 本系列文章预告

本系列共 8 篇深度技术博客，将从架构设计到生产部署全方位拆解这个项目：

篇数	核心主题	适合读者	预计阅读时间
✅ 第1篇	项目概览与技术选型	所有人	15 分钟
第2篇	LLM统一网关设计	后端工程师	20 分钟
第3篇	元数据智能管理系统	数据工程师	25 分钟
第4篇	NL→SQL转换引擎	AI应用开发者	30 分钟
第5篇	智能对话引擎实战	全栈开发者	25 分钟
第6篇	数据大屏两阶段分离架构	架构师	30 分钟
第7篇	前端拖拽交互系统实现	前端工程师	25 分钟
第8篇	生产部署与性能优化	DevOps/运维	20 分钟

💡 总结与思考

通过这个项目，我们解决了三个核心问题：

降低数据查询门槛：从”必须会 SQL”到”会说中文就行”
提升大屏开发效率：从”手工写代码”到”自然语言描述 + 一键生成”
实现 LLM 与传统系统的深度融合：不是简单的 API 调用，而是两阶段分离架构确保生产环境稳定性

下一篇文章，我们将深入剖析 LLM Gateway 的设计细节 —— 如何通过 LiteLLM 实现多模型统一调用？如何设计 Prompt 模板确保输出质量？如何清洗 LLM 响应中的噪声数据？

敬请期待！🚀

作者：DevCfg.com
版权声明：本文可自由转载，请注明出处