DataWhisperer我做了一个自然语言数据分析智能体支持中文提问自动生成 SQL、图表和分析结论项目信息GitHubhttps://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 和执行轨迹从截图里可以看到系统根据“各地区订单销售情况”自动生成了柱状图并给出了对应的业务分析结论。三、技术栈这个项目第一阶段主要使用模块技术后端框架FastAPI数据模型Pydantic数据库访问SQLAlchemy数据库MySQL 8大模型接口OpenAI-compatible API默认模型DashScope / Qwen前端HTML CSS JavaScript图表ECharts测试pytest ruff容器Docker Compose第一版没有直接上复杂前端框架而是先用原生前端把核心体验跑通。因为这个阶段最重要的是验证 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_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODELqwen-plus LLM_API_KEY你的 API Key3. SQL 安全校验这是我觉得这个项目里很重要的一点。大模型生成 SQL 后系统不会直接执行而是先经过服务端安全校验。因为提示词不是安全边界。即使 prompt 里写了“只能生成 SELECT”模型仍然可能输出危险 SQL或者被用户诱导生成危险语句。所以我在服务端做了硬校验只允许SELECT或WITH查询禁止INSERT禁止UPDATE禁止DELETE禁止DROP禁止ALTER禁止TRUNCATE禁止多语句 SQL禁止 SQL 注释绕过自动补充LIMIT。这个设计的核心思想是大模型负责理解和生成服务端代码负责安全兜底。4. 执行查询并返回表格SQL 通过安全校验后系统会执行查询并返回columns字段名rows查询结果generated_sql最终执行的 SQLwarnings风险提示或兜底说明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}响应里会包含生成的 SQLSQL 解释查询结果表格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 版本管理增加模型输出解析和失败重试。V3RAG 指标口径库支持 GMV、客单价、复购率等业务指标定义让模型先检索指标口径再生成 SQL。V4MCP 工具化把 schema 查询、SQL 生成、查询执行、图表生成等能力包装成 MCP 工具让其他 Agent 或客户端也可以复用这些工具。V5多智能体协作后续可以拆成多个角色Schema Analyst理解数据库结构SQL Engineer生成 SQLSafety Reviewer审查 SQLChart Designer选择图表Report Writer生成分析报告。不过我没有一开始就做多智能体因为第一阶段最重要的是先把完整闭环跑通。十、总结DataWhisperer 第一版实现了一个可以运行的自然语言数据分析智能体。它目前已经支持中文自然语言提问自动读取 MySQL schema大模型生成 SQL服务端 SQL 安全校验查询真实数据返回表格和 ECharts 图表生成中文业务分析结论展示完整执行轨迹。这个项目的核心价值在于把大模型从“会回答问题”变成“能安全调用工具完成数据分析任务”。后面我会继续围绕提示词治理、RAG、MCP 和多智能体方向迭代让它更接近一个真正可用的数据分析智能体产品。目前项目已经开源到 GitHubhttps://github.com/chenpan979/DataWhisperer如果你也对 Text-to-SQL、大模型应用开发、MCP、RAG 或多智能体方向感兴趣可以看看这个项目的源码和后续迭代。我也会继续把开发过程中的思路、问题和优化记录下来。
自然语言数据分析智能体(DataWhisperer v1版本)
DataWhisperer我做了一个自然语言数据分析智能体支持中文提问自动生成 SQL、图表和分析结论项目信息GitHubhttps://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 和执行轨迹从截图里可以看到系统根据“各地区订单销售情况”自动生成了柱状图并给出了对应的业务分析结论。三、技术栈这个项目第一阶段主要使用模块技术后端框架FastAPI数据模型Pydantic数据库访问SQLAlchemy数据库MySQL 8大模型接口OpenAI-compatible API默认模型DashScope / Qwen前端HTML CSS JavaScript图表ECharts测试pytest ruff容器Docker Compose第一版没有直接上复杂前端框架而是先用原生前端把核心体验跑通。因为这个阶段最重要的是验证 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_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODELqwen-plus LLM_API_KEY你的 API Key3. SQL 安全校验这是我觉得这个项目里很重要的一点。大模型生成 SQL 后系统不会直接执行而是先经过服务端安全校验。因为提示词不是安全边界。即使 prompt 里写了“只能生成 SELECT”模型仍然可能输出危险 SQL或者被用户诱导生成危险语句。所以我在服务端做了硬校验只允许SELECT或WITH查询禁止INSERT禁止UPDATE禁止DELETE禁止DROP禁止ALTER禁止TRUNCATE禁止多语句 SQL禁止 SQL 注释绕过自动补充LIMIT。这个设计的核心思想是大模型负责理解和生成服务端代码负责安全兜底。4. 执行查询并返回表格SQL 通过安全校验后系统会执行查询并返回columns字段名rows查询结果generated_sql最终执行的 SQLwarnings风险提示或兜底说明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}响应里会包含生成的 SQLSQL 解释查询结果表格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 版本管理增加模型输出解析和失败重试。V3RAG 指标口径库支持 GMV、客单价、复购率等业务指标定义让模型先检索指标口径再生成 SQL。V4MCP 工具化把 schema 查询、SQL 生成、查询执行、图表生成等能力包装成 MCP 工具让其他 Agent 或客户端也可以复用这些工具。V5多智能体协作后续可以拆成多个角色Schema Analyst理解数据库结构SQL Engineer生成 SQLSafety Reviewer审查 SQLChart Designer选择图表Report Writer生成分析报告。不过我没有一开始就做多智能体因为第一阶段最重要的是先把完整闭环跑通。十、总结DataWhisperer 第一版实现了一个可以运行的自然语言数据分析智能体。它目前已经支持中文自然语言提问自动读取 MySQL schema大模型生成 SQL服务端 SQL 安全校验查询真实数据返回表格和 ECharts 图表生成中文业务分析结论展示完整执行轨迹。这个项目的核心价值在于把大模型从“会回答问题”变成“能安全调用工具完成数据分析任务”。后面我会继续围绕提示词治理、RAG、MCP 和多智能体方向迭代让它更接近一个真正可用的数据分析智能体产品。目前项目已经开源到 GitHubhttps://github.com/chenpan979/DataWhisperer如果你也对 Text-to-SQL、大模型应用开发、MCP、RAG 或多智能体方向感兴趣可以看看这个项目的源码和后续迭代。我也会继续把开发过程中的思路、问题和优化记录下来。
