企业官网建设流程全解析

DataWhisperer：我做了一个自然语言数据分析智能体，支持中文提问自动生成 SQL、图表和分析结论

项目信息

• GitHub：https://github.com/chenpan979/DataWhisperer
• 项目名称：DataWhisperer
• 当前版本：v1
• 核心方向：Text-to-SQL、LLM 应用开发、数据分析智能体

本文记录我做的一个大模型接入项目：DataWhisperer。它是一个 Text-to-SQL 数据分析智能体，用户输入中文数据问题，系统自动读取 MySQL 表结构，生成安全 SQL，执行查询，并返回表格、图表和业务分析结论。

一、为什么想做这个项目？

现在很多业务同学都有数据分析需求，但并不是每个人都会写 SQL。

比如一个运营同学可能会问：

• 最近 6 个月每月销售额趋势怎么样？
• 哪个地区客单价最高？
• 各商品品类销售额占比是多少？
• 找出销售额下滑最明显的商品。
• 我想看看各地区订单的销售情况。

这些问题如果都让研发或数据分析师手动写 SQL，效率会比较低。

所以我想做一个工具：让用户直接用自然语言提问，系统自动帮他完成从“问题理解”到“数据查询”再到“图表和结论”的完整流程。

这就是 DataWhisperer 的第一版目标。

二、项目效果展示

1. 控制台初始状态

系统启动后，会进入一个中文数据分析控制台。左侧是问题输入区和示例问题，右侧展示结果指标、分析结论、图表、表格、SQL 和执行轨迹。

2. 自然语言查询结果

例如输入：

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

系统会自动生成 SQL，执行查询，然后返回：

• 查询结果行数
• 字段数量
• 推荐图表类型
• 执行步骤
• 中文分析结论
• 柱状图
• 表格数据
• SQL 和执行轨迹
  
  从截图里可以看到，系统根据“各地区订单销售情况”自动生成了柱状图，并给出了对应的业务分析结论。

三、技术栈

这个项目第一阶段主要使用：

第一版没有直接上复杂前端框架，而是先用原生前端把核心体验跑通。因为这个阶段最重要的是验证 Text-to-SQL 的完整闭环。

四、整体架构

DataWhisperer v1 采用的是单主控 Agent 工具链。

整体流程如下：

用户中文问题 | v FastAPI 接口：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：负责测试用例。

这样拆分的好处是：每个模块职责比较清楚，后续想接 MCP、RAG 或多智能体时，也比较容易扩展。

五、核心功能设计

1. 自动读取数据库 Schema

大模型生成 SQL 之前，必须先知道数据库有哪些表、有哪些字段、字段类型是什么、表之间有什么关系。

所以我做了一个 Schema Tool，它会自动读取 MySQL 的表结构信息，并整理成适合放进 prompt 的文本。

为什么不直接把完整 JSON 喂给模型？

因为真实企业数据库表很多、字段很多，如果把完整结构全部塞进去：

• prompt 会变长；
• token 成本会上升；
• 模型更容易被无关字段干扰；
• 生成 SQL 的稳定性会下降。

所以第一版只保留和 SQL 生成最相关的信息，比如表名、字段名、字段类型、主键和外键。

2. 大模型生成 SQL

用户输入自然语言问题后，系统会把用户问题和 schema 摘要一起交给大模型，让模型生成 MySQL 查询语句。

这里使用的是 OpenAI-compatible 封装，所以不绑定某一家模型服务。

当前默认使用 DashScope/Qwen，后续也可以切换成 OpenAI、DeepSeek 或其他兼容接口。

环境变量大概长这样：

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

3. SQL 安全校验

这是我觉得这个项目里很重要的一点。

大模型生成 SQL 后，系统不会直接执行，而是先经过服务端安全校验。

因为提示词不是安全边界。即使 prompt 里写了“只能生成 SELECT”，模型仍然可能输出危险 SQL，或者被用户诱导生成危险语句。

所以我在服务端做了硬校验：

• 只允许SELECT或WITH查询；
• 禁止INSERT；
• 禁止UPDATE；
• 禁止DELETE；
• 禁止DROP；
• 禁止ALTER；
• 禁止TRUNCATE；
• 禁止多语句 SQL；
• 禁止 SQL 注释绕过；
• 自动补充LIMIT。

这个设计的核心思想是：

大模型负责理解和生成，服务端代码负责安全兜底。

4. 执行查询并返回表格

SQL 通过安全校验后，系统会执行查询，并返回：

• columns：字段名；
• rows：查询结果；
• generated_sql：最终执行的 SQL；
• warnings：风险提示或兜底说明；
• trace_steps：执行轨迹。

执行轨迹对调试很有帮助，也方便面试讲解。

比如我可以告诉面试官：这个项目不是简单调一个模型接口，而是有完整的执行链路。

5. 自动推荐图表

查询结果出来后，系统会根据字段类型和数据形态推荐 ECharts 图表。

第一版支持：

• 柱状图；
• 折线图；
• 饼图；
• 表格兜底。

比如“各地区订单数量”这种问题，系统会推荐柱状图。

“最近 6 个月销售额趋势”这种问题，系统会推荐折线图。

“商品品类销售额占比”这种问题，系统会推荐饼图。

6. 生成业务分析结论

最后系统会基于查询结果生成中文业务结论。

这里我限制了模型输出风格：

• 只基于查询结果分析；
• 不编造结果里没有的数据；
• 结论简短；
• 面向业务人员表达。

这样生成的内容不会太像“聊天机器人”，而更像一个数据分析助手。

六、主要接口

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 图表配置；
• 业务分析结论；
• 执行轨迹；
• 风险提示。

七、测试情况

目前我补了基础测试：

• SQL 安全校验测试；
• 图表推荐测试；
• 示例问题接口测试；
• API 契约测试。

本地测试结果：

17 passed All checks passed!

这里用到了：

pytest ruff check.

八、这个项目对我来说学到了什么？

这个项目让我更清楚地理解了：大模型应用不是简单调用一次 API。

真正有工程价值的大模型应用，需要考虑：

• 数据从哪里来；
• 模型需要什么上下文；
• 工具如何拆分；
• 输出如何校验；
• 风险如何兜底；
• 失败时如何处理；
• 用户界面如何展示；
• 后续如何扩展。

尤其是 Text-to-SQL 场景，SQL 安全非常关键。不能因为模型说“这是安全的”，系统就直接执行。

九、后续规划

第一版先完成 Text-to-SQL MVP，后续我准备继续扩展：

V1.1：完善项目展示

• 补充更多截图；
• 补充 GitHub Actions；
• 增加更多接口示例；
• 增强 README 展示效果。

V2：提示词治理

• 把 prompt 独立成模板文件；
• 增加 prompt 版本管理；
• 增加模型输出解析和失败重试。

V3：RAG 指标口径库

• 支持 GMV、客单价、复购率等业务指标定义；
• 让模型先检索指标口径，再生成 SQL。

V4：MCP 工具化

• 把 schema 查询、SQL 生成、查询执行、图表生成等能力包装成 MCP 工具；
• 让其他 Agent 或客户端也可以复用这些工具。

V5：多智能体协作

后续可以拆成多个角色：

• Schema Analyst：理解数据库结构；
• SQL Engineer：生成 SQL；
• Safety Reviewer：审查 SQL；
• Chart Designer：选择图表；
• Report Writer：生成分析报告。

不过我没有一开始就做多智能体，因为第一阶段最重要的是先把完整闭环跑通。

十、总结

DataWhisperer 第一版实现了一个可以运行的自然语言数据分析智能体。

它目前已经支持：

• 中文自然语言提问；
• 自动读取 MySQL schema；
• 大模型生成 SQL；
• 服务端 SQL 安全校验；
• 查询真实数据；
• 返回表格和 ECharts 图表；
• 生成中文业务分析结论；
• 展示完整执行轨迹。

这个项目的核心价值在于：

把大模型从“会回答问题”变成“能安全调用工具完成数据分析任务”。

后面我会继续围绕提示词治理、RAG、MCP 和多智能体方向迭代，让它更接近一个真正可用的数据分析智能体产品。

目前项目已经开源到 GitHub：

https://github.com/chenpan979/DataWhisperer

如果你也对 Text-to-SQL、大模型应用开发、MCP、RAG 或多智能体方向感兴趣，可以看看这个项目的源码和后续迭代。我也会继续把开发过程中的思路、问题和优化记录下来。