【实战开源】再也不用帮业务写SQL了！我用LLM做了个数据分析智能体，中文提问自动出SQL+图表+结论

做后端开发和数据岗的同学，大概率都有过这种经历：
运营同学跑过来问“最近6个月每个月的销售额趋势怎么样？”
产品甩来需求“帮我看下哪个地区的客单价最高？”
甚至老板临时要“各商品品类的销售额占比，半小时后开会要用”。

这些问题本身不难，但架不住频次高、重复度大——每天光给业务同学写SQL、导数据、做图表，就能耗掉小半天时间，核心开发进度反而被一拖再拖。

与其每次手动重复劳动，不如直接把这件事交给AI。于是我花了两周时间，做了一个开箱即用的自然语言数据分析智能体 DataWhisperer v1。

业务同学只用输入一句中文问题，系统就能自动读取MySQL表结构、生成安全可执行的SQL、返回数据表格、自动匹配图表，甚至还能输出一份业务视角的分析结论。全程零代码，10秒出结果。

项目已经完整开源，本文就从思路到实现，完整拆解给大家。
GitHub：https://github.com/chenpan979/DataWhisperer

一、先看效果：一句话搞定数据分析

系统启动后是一个开箱即用的中文控制台，左侧输入问题，右侧一站式返回所有分析结果。

举个例子，输入一句很口语化的需求：

我想看一下各地区的订单的销售情况

不需要指定表名、不需要说字段，系统会自动完成整套流程：

1. 读取对应表结构，理解“地区”“销售情况”对应哪些字段
2. 生成合规的SELECT查询语句
3. 执行SQL拿到真实数据
4. 判断数据形态，自动推荐柱状图
5. 基于结果输出中文业务分析结论

最终返回的内容包含：结果指标、执行步骤、可视化图表、明细表格、原始SQL和完整执行轨迹。

简单做个效率对比：

分析场景	传统人工流程	DataWhisperer
各地区销售额统计	找表结构→写SQL→跑查询→Excel做图→整理结论	输入中文问题→回车，一键出结果
耗时	5-15分钟/次	10秒内
使用门槛	需要掌握SQL+基础数据能力	会说中文就能用

二、这个项目，和普通的Text-to-SQL有什么不一样？

现在Text-to-SQL的demo很多，但大多停留在“生成SQL语句”就结束了。DataWhisperer v1我是按完整可用的产品MVP来做的，重点解决了几个真实落地的核心问题：

✅ 完整闭环，不止生成SQL
从自然语言提问，到数据查询、可视化图表、业务结论，一步到位返回最终结果，用户不用再自己导数据做图。

✅ 服务端硬校验，把安全焊死
绝对不把Prompt当安全边界。哪怕大模型被诱导生成危险语句，服务端也会强制拦截。只允许SELECT/WITH只读查询，禁止增删改、禁止多语句、自动补LIMIT，从机制上杜绝删库跑路风险。

✅ 精简Schema，提升准确率+降成本
没有直接把全量表结构丢给大模型，而是只提取表名、字段、类型、主键外键等核心信息。既减少了Token消耗，也降低了无关字段对模型的干扰，SQL生成准确率提升非常明显。

✅ 模块化架构，方便扩展
采用Agent+工具链的分层设计，Schema查询、SQL生成、执行、图表、结论各自独立。后续接RAG、MCP、多智能体都不用推翻重构。

✅ 轻量化实现，新手也能复刻
前端没有上重型框架，用原生HTML+JS+ECharts就跑通了完整体验，后端基于FastAPI，代码结构清晰，很适合拿来做LLM应用开发的入门练手项目。

三、技术栈与整体架构

技术选型

第一版的核心目标是快速跑通闭环，所以选型都偏向轻量化、易上手：

模块	技术选型
后端框架	FastAPI
数据校验	Pydantic
ORM	SQLAlchemy
数据库	MySQL 8
大模型接口	OpenAI-compatible API（默认通义千问/DashScope）
前端	原生 HTML + CSS + JavaScript
图表	ECharts
测试	pytest + ruff
部署	Docker Compose

大模型部分做了兼容层封装，不绑定单一厂商，切换OpenAI、DeepSeek等其他兼容接口都很方便。

整体架构

v1采用单主控Agent + 工具链的编排模式，流程非常清晰：

用户中文问题
  |
  v
POST /api/chat/query 接口接入
  |
  v
DataAnalysisOrchestrator 主控编排
  |
  ├─ Schema Tool：读取数据库表结构摘要
  ├─ SQL Tool：生成 SQL + 服务端安全校验
  ├─ Query Tool：执行查询，返回结构化数据
  ├─ Chart Tool：根据数据形态推荐图表配置
  └─ Insight Tool：基于结果生成业务分析结论
  |
  v
统一返回：SQL + 表格 + 图表配置 + 分析结论 + 执行轨迹

代码结构按职责分层，后续扩展很方便：

• app/api：FastAPI 路由层
• app/core：配置、数据库连接、大模型客户端
• app/tools：各工具能力的具体实现
• app/agent：主控编排逻辑
• static：前端控制台页面
• tests：单元测试用例

四、核心功能设计拆解

1. 自动读取数据库Schema

大模型要写对SQL，前提是知道库表里有什么。但企业级数据库动辄几十上百张表，字段成百上千，全量喂给模型既费Token，又容易干扰生成结果。

所以Schema Tool做了两层处理：

1. 自动从MySQL读取表名、字段名、字段类型、主键、外键信息
2. 清洗过滤掉冗余信息，只保留SQL生成必需的核心字段，整理成简洁文本

实测下来，精简后的Schema不仅Token消耗减少了40%+，SQL生成的准确率也有明显提升。

2. 大模型生成SQL

将用户的自然语言问题 + Schema摘要一起传入Prompt，让大模型生成符合MySQL语法的查询语句。

因为做了OpenAI兼容接口的封装，切换模型非常灵活，只需要改环境变量即可：

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=qwen-plus
LLM_API_KEY=你的 API Key

3. SQL安全校验（最关键的一步）

这是我认为整个项目里最不能省的环节——永远不要相信大模型的输出。

哪怕你在Prompt里写一百遍“只能生成SELECT语句”，依然存在提示词注入、模型幻觉生成危险SQL的可能。所以我在服务端做了一层硬校验，所有SQL必须过审才能执行：

• 仅允许 SELECT / WITH 开头的只读查询
• 拦截所有 INSERT / UPDATE / DELETE / DROP / ALTER / TRUNCATE 写操作
• 禁止多语句SQL，防止注释绕过
• 自动追加 LIMIT 限制，避免大查询拖垮数据库

核心原则就是：大模型负责理解和生成，服务端代码负责安全兜底。

4. 自动推荐图表

拿到查询结果后，系统会根据字段数量、字段类型、数据分布，自动匹配最合适的图表类型：

• 分类对比类（如各地区订单数）→ 柱状图
• 时间趋势类（如月销售额走势）→ 折线图
• 占比分析类（如品类销售额占比）→ 饼图
• 复杂明细数据 → 表格兜底

返回的是标准ECharts配置，前端可以直接渲染，也很方便二次定制。

5. 生成业务分析结论

最后一步，让大模型基于查询到的真实数据，输出面向业务人员的中文结论。
这里对输出做了严格约束：

• 所有结论必须基于查询结果，严禁编造数据
• 语言口语化，避免技术术语
• 结论精简，突出核心信息

最终输出更像数据分析师的总结，而不是生硬的机器话术。

五、核心接口说明

项目提供了清晰的RESTful接口，方便对接其他系统或者二次开发。

1. 健康检查

GET /api/health

用于确认服务是否正常启动。

2. 获取数据库结构摘要

GET /api/schema/overview

查看系统读取到的MySQL表结构信息。

3. 获取示例问题

GET /api/examples

返回预置的示例问题列表，可用于前端展示。

4. 自然语言查询（核心接口）

POST /api/chat/query

请求示例：

{
  "question": "查询各地区订单数量",
  "max_rows": 100
}

响应包含生成的SQL、SQL解释、表格数据、ECharts图表配置、业务分析结论、执行轨迹、风险提示全量信息。

六、快速上手：5分钟跑起来

项目已经打包了Docker Compose，本地有MySQL环境的话，几步就能跑起来。

1. 克隆代码

git clone https://github.com/chenpan979/DataWhisperer.git
cd DataWhisperer

2. 配置环境变量

cp .env.example .env

修改 .env 文件，填入你的大模型API Key和MySQL连接信息。

3. 启动服务

docker-compose up -d

4. 访问控制台
   打开浏览器访问 http://localhost:8000 就可以直接使用了。

七、测试与开发踩坑

目前已经覆盖了SQL安全校验、图表推荐、接口契约等基础测试，本地17个测试用例全部通过。

17 passed
All checks passed!

开发过程中也踩了不少坑，分享几个最典型的：

1. Schema不是越全越好。一开始我把所有字段注释、索引信息全塞进去了，结果模型经常被无关信息带偏，生成的SQL正确率很低。精简到只留核心字段后，准确率直接上来了。
2. 别靠Prompt做安全。测试的时候试过用提示词注入，让模型生成带DROP的语句，真的能生成。所以必须在服务端做硬拦截，Prompt只能做辅助。
3. 图表推荐不能只看字段数。一开始只按“1个维度1个指标=柱状图”来做，遇到时间维度经常出错。后来加了字段类型判断，识别日期类字段自动优先折线图，合理多了。

做这个项目最大的感受是：真正有工程价值的LLM应用，从来不是简单调一次API。数据上下文怎么给、输出怎么校验、失败怎么兜底、风险怎么控制，这些才是决定项目能不能落地的关键。

八、后续迭代规划

v1只是完成了最基础的MVP闭环，后面还有很多方向可以扩展：

• v1.1 完善展示：补充更多演示案例、接入GitHub Actions、完善文档
• v2 提示词治理：Prompt模板化、版本管理，增加输出解析和失败重试机制
• v3 RAG指标口径库：接入GMV、客单价、复购率等业务指标定义，让模型先检索口径再生成SQL，解决业务术语不统一的问题
• v4 MCP工具化：把各能力封装成MCP工具，供其他Agent和客户端复用
• v5 多智能体协作：拆分成Schema分析师、SQL工程师、安全审核员、图表设计师、报告撰写员多个角色，提升复杂场景的处理能力

写在最后

DataWhisperer v1 实现了一个从0到1的自然语言数据分析完整闭环，把大模型从“会聊天”变成了“能实实在在完成数据分析任务”。

如果你也对Text-to-SQL、LLM应用开发、MCP、RAG、多智能体这些方向感兴趣，欢迎来GitHub逛逛，点个Star✨就是对我最大的支持。
项目地址：https://github.com/chenpan979/DataWhisperer

有任何想法、建议或者遇到问题，都欢迎在评论区留言，或者去GitHub提Issue。后续我也会继续更新开发过程中的思路和踩坑经验，大家可以关注一波~