# SmartGrid

**Repository Path**: zxporz/SmartGrid

## Basic Information

- **Project Name**: SmartGrid
- **Description**: SmartGrid 是一个智能 Excel 数据分析平台，使用非常简单，用自然语言描述需求，自动分析 Excel 数据、生成图表等。对数据分析师和开发人员同样友好，支持微调 sql 进行数据分析。更多功能等你来探！
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-18
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI

## README



# 前言
SmartGrid 是一款面向非技术用户的全栈数据智能分析工具，目标是将 Excel 数据快速转化为可查询、可洞察、可可视化的知识资产。

如果有一些交互问题，请无需在意，因为本产品并不是以交互体验为主的。它集中为你解决excel数据分析的能力。

比如：透视图、关联Sheet分析，一些Excel的函数，如果不会深度使用excel那么你一定会望Excel兴叹，即便你是数据分析师或开发人员。

我部署了最新的版本供你尝试，[请戳链接](http://180.184.78.42:81/?db=smartGrid+%281%29_b371afe5_20251218_173214)

如果你觉得这个项目帮助了你或者对你有启发，还望不吝Star，您的鼓励是我迭代的动力！

后续我还会尝试添加各种能力，比如机器学习分析excel的功能。

核心能力包括：

- Excel 导入与 SQLite 持久化
- 自然语言转 SQL（NLU→SQL）
- 数据字典生成与编辑（用于提升Test2SQL的准确度）
- 图表推荐与可视化（pyecharts/matplotlib）帮你快速生成分析结果可交互图表
- AI 分析结论生成（基于大模型）

# 快速开始

1.  `pip install -r requirements.txt`
2.  windows `streamlit run --server.port 80 excel_processor.py`
3.  linux `nohup python -m streamlit run --server.port 80 excel_processor.py &`
4.  你需要一个QWEN的api_key，从https://bailian.console.aliyun.com/申请，并替换到`config.json->api_key`
5.  运行成功后，访问 http://localhost



# 项目结构
项目采用“前端 + 多个后端处理模块”的扁平结构，便于理解与扩展：
- 前端入口：excel_processor.py（Streamlit 应用）
- 数据处理：excel_to_sqlite.py（Excel→SQLite、SQL 查询、数据字典）
- SQL 生成：genSql.py（基于表结构与数据字典生成 SQL）
- 大模型封装：llmmodels.py（统一调用 DashScope API）
- 可视化：pandas_chart.py（图表推荐与生成）
- 配置与依赖：config.json、requirements.txt
- 启动脚本：start.bat
- 示例图表模板：pyechartsDemos/*.txt

```mermaid
graph TB
subgraph "前端"
V["excel_processor.py<br/>Streamlit 视图层"]
end
subgraph "后端处理"
M1["excel_to_sqlite.py<br/>Excel→SQLite/SQL/数据字典"]
M2["genSql.py<br/>NLU→SQL"]
M3["llmmodels.py<br/>大模型封装"]
M4["pandas_chart.py<br/>图表推荐/生成"]
end
subgraph "资源与配置"
C["config.json<br/>API密钥等"]
R["requirements.txt<br/>依赖清单"]
S["start.bat<br/>启动脚本"]
D["pyechartsDemos/*.txt<br/>示例代码模板"]
end
V --> M1
V --> M4
M1 --> M2
M1 --> M3
M2 --> M3
M4 --> M3
V --> C
V --> R
V --> S
M4 --> D
```

# 核心组件
- Streamlit 前端（View 层）
  - 文件上传、Excel 保存与备份、侧边栏文件管理、数据预览、数据字典面板、SQL 调试区、分析结论生成、图表生成与展示
- Excel→SQLite 持久化（Model/Controller）
  - Excel 文件解析、表名清洗、SQLite 写入、查询执行、表结构与列信息查询、数据字典生成/加载/保存
- NLU→SQL（Model/Controller）
  - 基于表结构、示例数据与数据字典，调用大模型生成 ANSI SQL
- 大模型封装（Model/Controller）
  - 统一的 DashScope 客户端与提示词模板，支持不同模型与参数
- 图表推荐与生成（Model/Controller）
  - 基于数据特征与用户问题推荐图表类型；优先使用大模型生成 pyecharts 代码，失败回退 matplotlib

- file://pandas_chart.py#L1-L821)

# 架构总览
SmartGrid 的控制流从 Streamlit 页面发起，经由 excel_processor.py 调用 excel_to_sqlite.py 完成数据入库与查询，再通过 genSql.py 生成 SQL，最终由 llmmodels.py 调用大模型完成 SQL 生成与分析结论生成；图表生成由 pandas_chart.py 完成，优先使用 pyecharts，失败回退 matplotlib。

```mermaid
sequenceDiagram
participant U as "用户"
participant V as "excel_processor.py"
participant M1 as "excel_to_sqlite.py"
participant M2 as "genSql.py"
participant M3 as "llmmodels.py"
participant M4 as "pandas_chart.py"
U->>V : 上传Excel并提交自然语言指令
V->>M1 : 保存Excel并生成SQLite数据库
V->>M1 : analyze_database_sql(指令)
M1->>M2 : genSql(表结构/示例/数据字典, 指令)
M2->>M3 : 调用大模型生成SQL
M3-->>M2 : 返回SQL文本
M2-->>M1 : 返回美化后的SQL
M1-->>V : 执行SQL并返回结果DataFrame
V->>M4 : generate_chart(结果DataFrame, 指令)
M4->>M3 : 推荐图表类型/生成代码可选
M3-->>M4 : 返回推荐/代码
M4-->>V : 返回图表对象或matplotlib Figure
V-->>U : 展示结果、SQL、结论、图表
```



# 详细组件分析

## 组件A：Streamlit 前端（View 层）
- 功能要点
  - 上传 Excel 并保存至 excelfile 目录，同时生成备份
  - 侧边栏列出 Excel 文件，支持打开与删除
  - 加载 SQLite 数据并预览各 Sheet 的前若干行
  - 数据字典面板：一键生成/重新生成字段说明与数据示例，支持在线编辑并自动保存
  - 分析区：自然语言指令输入、SQL 调试（表名/列名、可编辑 SQL、执行）、分析结论生成、图表生成与展示
- 关键交互
  - 通过 session_state 管理状态，避免重复计算
  - URL 参数 db 用于定位当前数据库文件
  - 支持“执行 SQL”即时验证与刷新

```mermaid
flowchart TD
Start["进入页面"] --> Upload["上传Excel"]
Upload --> Save["保存Excel并生成SQLite"]
Save --> Preview["预览各Sheet数据"]
Preview --> DictPanel["数据字典面板"]
DictPanel --> GenSQL["生成SQLNLU→SQL"]
GenSQL --> ExecSQL["执行SQL并返回结果"]
ExecSQL --> Answer["生成分析结论"]
ExecSQL --> Chart["生成图表"]
Answer --> End["展示结论"]
Chart --> End
```



## 组件B：Excel→SQLite 与数据字典（Model/Controller）
- 功能要点
  - Excel→SQLite：逐 Sheet 读取，清洗列名，写入 SQLite
  - 查询执行：支持 SQL 查询并返回 DataFrame
  - 表结构与列信息：获取建表语句、表名、列名、示例数据
  - 数据字典：生成字段说明（调用大模型）、数据示例、保存/加载 excel_dict 表
- 关键算法
  - 列名清洗：去除特殊字符、处理中文、避免以数字开头、替换空格为下划线
  - SQL 生成：将表结构、示例数据、数据字典拼装为提示词，调用大模型生成 ANSI SQL

```mermaid
flowchart TD
A["Excel文件"] --> B["读取Sheet"]
B --> C["清洗列名"]
C --> D["写入SQLite表"]
D --> E["查询/统计"]
E --> F["生成数据字典"]
F --> G["保存excel_dict表"]
```

## 组件C：自然语言转 SQL（Model/Controller）
- 功能要点
  - 将用户自然语言指令转换为 ANSI SQL，支持日期字段的正确处理规则
  - 可选加入数据字典与示例数据，提升 SQL 准确性
- 关键提示词
  - 明确 ANSI SQL 标准、注释说明、日期字段处理规则、必要时多表关联

```mermaid
sequenceDiagram
participant V as "excel_processor.py"
participant M1 as "excel_to_sqlite.py"
participant M2 as "genSql.py"
participant M3 as "llmmodels.py"
V->>M1 : analyze_database_sql(指令)
M1->>M1 : 获取表结构/示例/数据字典
M1->>M2 : genSql(表结构/示例/数据字典, 指令)
M2->>M3 : 调用大模型生成SQL
M3-->>M2 : 返回SQL
M2-->>M1 : 返回美化SQL
M1-->>V : 返回SQL
```



## 组件D：大模型封装（Model/Controller）
- 功能要点
  - 统一 DashScope 客户端初始化与调用
  - 支持不同模型（qwen-turbo/qwen3-max-preview 等）与参数（temperature/top_p）
  - 支持 JSON 输出与调试打印
- 配置
  - 从 config.json 读取 api_key

```mermaid
classDiagram
class LLMModel {
+getTongYi(api_key)
+getTongYiModelResponse(...)
+getModelResponse(...)
+promptTemplate(template)
}
class MyLargeModel {
+_llm_type
+_call(prompt, stop)
+_identifying_params
}
LLMModel <|-- MyLargeModel
```

## 组件E：图表推荐与可视化（Model/Controller）
- 功能要点
  - 基于数据特征与用户问题推荐图表类型（饼图/柱状图/折线图/雷达图/K线图/3D柱状图/多轴组合图）
  - 使用大模型生成 pyecharts 代码，失败回退 matplotlib
  - 支持示例模板（pyechartsDemos/*.txt）辅助生成
- 关键流程
  - recommend_chart_by_llm → generate_chart_code_by_llm → exec 生成图表对象
  - 失败时 _determine_chart_type 自动选择 matplotlib 图表类型

```mermaid
flowchart TD
DF["DataFrame"] --> Rec["recommend_chart_by_llm"]
Rec --> Code["generate_chart_code_by_llm"]
Code --> Exec["exec 生成图表对象"]
Exec --> Show["渲染/展示"]
Rec --> |失败| Mat["matplotlib 自动选择类型"]
Mat --> Show
```



# 依赖关系分析
- 外部依赖
  - Streamlit、pandas、openai、langchain、sqlparse、pyecharts、openpyxl、requests、python-docx、tabulate 等
- 内部模块耦合
  - excel_processor.py 依赖 excel_to_sqlite.py、pandas_chart.py
  - excel_to_sqlite.py 依赖 genSql.py、llmmodels.py
  - genSql.py 依赖 llmmodels.py
  - pandas_chart.py 依赖 llmmodels.py、pyechartsDemos 示例模板

```mermaid
graph LR
V["excel_processor.py"] --> M1["excel_to_sqlite.py"]
V --> M4["pandas_chart.py"]
M1 --> M2["genSql.py"]
M1 --> M3["llmmodels.py"]
M2 --> M3
M4 --> M3
M4 --> D["pyechartsDemos/*.txt"]
```

# 性能与可扩展性
- 性能特性
  - Excel→SQLite：按 Sheet 逐表写入，避免一次性大内存操作
  - SQL 查询：使用 pandas.read_sql_query，支持 LIMIT 与 COUNT 估算
  - 图表生成：优先 pyecharts，失败回退 matplotlib，兼顾质量与稳定性
- 可扩展方向
  - SQL 生成：引入更多上下文（如历史查询、业务规则）
  - 图表：增加更多模板与样式配置
  - 数据字典：支持多语言、字段分类、质量评分
  - 并发与缓存：为常用查询与图表生成增加缓存层

[本节为通用建议，无需章节来源]

# 故障排查指南
- 常见问题
  - 上传文件后无法加载：确认 excelfile 与 dbfile 目录存在，且文件名匹配
  - SQL 执行报错：检查 SQL 是否符合 ANSI 标准，日期字段处理是否正确
  - 图表生成失败：检查 pyecharts 依赖安装与示例模板是否存在
  - 大模型调用失败：检查 config.json 中 api_key 是否正确
- 定位方法
  - 查看 Streamlit 页面的错误提示与 traceback
  - 在 SQL 调试区手动执行 SQL，逐步缩小问题范围
  - 在数据字典面板中核对字段说明与示例

## 结论
SmartGrid 以“前端交互 + 后端处理模块”的方式，将 Excel 数据快速转化为可查询、可洞察、可可视化的知识资产。通过自然语言转 SQL、数据字典、图表推荐与可视化、AI 分析结论生成等能力，显著降低了数据分析门槛，适用于数据分析师、业务人员与开发者。未来可在 SQL 上下文增强、图表模板扩展、数据字典治理与缓存等方面持续演进。

# 附录

### 使用场景示例：销售数据“上季度各区域销售额对比”
- 步骤
  1) 在前端上传销售数据 Excel，系统自动保存并生成 SQLite 数据库
  2) 在分析区输入自然语言指令：“上季度各区域销售额对比”
  3) 系统调用 excel_to_sqlite.analyze_database_sql 生成 ANSI SQL
  4) 执行 SQL 得到结果 DataFrame
  5) 自动生成分析结论与图表（默认柱状图，可由大模型推荐更合适图表）
- 路径映射
  - 前端交互：excel_processor.py
  - SQL 生成：excel_to_sqlite.py → genSql.py
  - 大模型：llmmodels.py
  - 图表生成：pandas_chart.py

```mermaid
sequenceDiagram
participant U as "用户"
participant V as "excel_processor.py"
participant M1 as "excel_to_sqlite.py"
participant M2 as "genSql.py"
participant M3 as "llmmodels.py"
participant M4 as "pandas_chart.py"
U->>V : 上传Excel并输入指令
V->>M1 : analyze_database_sql(指令)
M1->>M2 : genSql(表结构/示例/数据字典, 指令)
M2->>M3 : 调用大模型
M3-->>M2 : 返回SQL
M2-->>M1 : 返回SQL
M1-->>V : 执行SQL得到结果
V->>M4 : generate_chart(结果, 指令)
M4-->>V : 返回图表
V-->>U : 展示结果/SQL/结论/图表
```

# 目标用户与价值
- 目标用户
  - 数据分析师：快速生成 SQL、验证假设、生成结论与图表
  - 业务人员：通过自然语言表达业务问题，获得可解释的洞察
  - 开发者：可复用模块（SQL 生成、数据字典、图表生成）集成到更大系统
- 价值
  - 降低数据分析门槛：从 Excel 到洞察的自动化流水线
  - 提升协作效率：数据字典与结论可共享、可编辑
  - 强化可解释性：SQL 可调试、图表可解释、结论可溯源