🧠 智析BI / SmartBI-AI

轻量级 AI 商业智能分析平台
面向中小企业 · 纯 Python 技术栈 · 开箱即用

---

✨ 功能概览

功能	说明
📊 多源数据管理	连接 MySQL / PostgreSQL / MongoDB，上传 Excel / CSV
🔍 NL2SQL 智能查询	自然语言提问 → AI 自动生成 SQL → 一键执行
🧹 一键数据清洗	自动去重、缺失值填充、异常值检测与移除
🔗 跨源合并分析	将不同数据源数据按关联字段合并（如 MySQL 订单 + Excel 客户表）
📈 智能可视化	自动推荐图表类型，支持柱状图/折线图/饼图/散点图/热力图
💡 AI 业务洞察	AI 自动分析趋势、发现异常、提供可执行业务建议
💬 对话式分析	像聊天一样分析数据，AI 自动生成 SQL 并展示结果
⚙️ 模型管理	在页面中配置/切换 AI 模型，支持多模型存储，无需修改环境变量
🏠 本地模型支持	支持 Qwen2 等本地开源模型，数据不出企业

🖼️ 界面预览

⚙️ 模型管理 — 添加/切换 AI 模型，无需改配置文件

📊 数据源管理 — 连接数据库或上传文件

💬 对话式分析 — 自然语言提问，AI 自动生成 SQL 并展示图表

🏗️ 架构

┌────────────────────┐     HTTP      ┌────────────────────┐
│   Streamlit 前端   │ ◄───────────► │   FastAPI 后端     │
│   (端口 8501)      │               │   (端口 8000)      │
└────────────────────┘               └─────────┬──────────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │              │           │           │              │
              ┌─────▼─────┐ ┌─────▼────┐ ┌────▼────┐ ┌───▼───┐ ┌───────▼──────┐
              │   MySQL   │ │ PostgreSQL│ │ MongoDB │ │ Excel │ │     CSV      │
              └───────────┘ └──────────┘ └─────────┘ └───────┘ └──────────────┘
                    │
              ┌─────▼─────────────────────────────────────────────────────┐
              │              SQLite（元信息存储）                          │
              └───────────────────────────────────────────────────────────┘
                    │
              ┌─────▼─────────────────────────────────────────────────────┐
              │   AI 引擎（通义千问 / OpenAI / 讯飞星火 / 本地模型）       │
              └───────────────────────────────────────────────────────────┘

🚀 快速开始

环境要求

• Python 3.10+
• pip

1. 克隆项目

git clone https://github.com/guohangbk/SmartBI-AI.git
cd SmartBI-AI

2. 安装依赖

# 创建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements.txt

3. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，填入你的 AI API Key

最小配置（默认使用 SQLite，无需额外配置）：

.env 只需配置数据库相关选项，AI 模型通过系统页面「⚙️ 模型管理」配置。

可选：将元信息库从 SQLite 切换到 MySQL

DATABASE_URL=mysql+pymysql://user:password@127.0.0.1:3306/smartbi_meta?charset=utf8mb4

4. 初始化数据库 & 加载演示数据

make init-db    # 初始化 SQLite 数据库
make seed       # 加载演示数据（可选）

5. 启动服务

# 同时启动 API + 前端（推荐）
make dev

# 或分别启动
make api        # API: http://localhost:8000/docs
make frontend   # 前端: http://localhost:8501

打开浏览器访问 http://localhost:8501 即可使用。

🐳 Docker 部署

方式一：零配置启动（默认 SQLite）

docker pull guohangbk/smartbi-ai:latest

docker run -d \
  --name smartbi-ai \
  -p 8000:8000 \
  -p 8501:8501 \
  -v smartbi-data:/app/data \
  guohangbk/smartbi-ai:latest

# 访问:  前端 http://localhost:8501  |  API http://localhost:8000/docs

方式二：指定 MySQL（通过 -e 参数，无需 .env 文件）

docker run -d \
  --name smartbi-ai \
  -p 8000:8000 \
  -p 8501:8501 \
  -v smartbi-data:/app/data \
  -e DATABASE_URL="mysql+pymysql://user:password@host:3306/smartbi_meta?charset=utf8mb4" \
  guohangbk/smartbi-ai:latest

Linux 连接宿主机数据库需加 --add-host=host.docker.internal:host-gateway

方式三：Docker Compose

git clone https://github.com/guohangbk/SmartBI-AI.git
cd SmartBI-AI

# 默认 SQLite 零配置启动；如需 MySQL 编辑 docker-compose.yml 中的 DATABASE_URL
docker compose up -d

方式四：从源码构建

git clone https://github.com/guohangbk/SmartBI-AI.git
cd SmartBI-AI
make docker-build       # 构建镜像
make docker-up          # 启动服务

Docker + Ollama 本地模型

Ollama 模型配置在系统启动后通过「⚙️ 模型管理」页面添加。

Docker 内连接宿主机 Ollama 时，API Base 填 http://host.docker.internal:11434。

host.docker.internal 是 Docker 访问宿主机的特殊域名（macOS/Windows 开箱可用）。 Linux 用户需加 --add-host=host.docker.internal:host-gateway。

📖 使用教程

Step 1: 添加数据源

进入「📊 数据源」页面：

• 数据库：填写 MySQL/PostgreSQL/MongoDB 连接信息，点击「测试连接」→「保存」
• 文件：直接上传 Excel (.xlsx) 或 CSV 文件

系统会自动拉取表结构和字段信息。

Step 2: 补全字段描述（推荐）

在「元信息管理」标签页，为字段添加中文描述：

例如：order_date → "订单日期"，total_amount → "订单总金额（元）"

字段描述越详细，NL2SQL 的准确率越高。

Step 3: 智能查询

进入「🔍 智能查询」页面，用自然语言提问：

"查看每个地区的销售额排名" → AI 自动生成 SQL 并执行

Step 4: 可视化 & AI 洞察

• 「📈 可视化」：基于查询结果生成图表
• 「💡 AI 洞察」：AI 自动分析数据趋势，提供业务建议

📂 项目结构

SmartBI-AI/
├── smartbi/                # 核心 Python 包
│   ├── api/                # FastAPI 路由
│   ├── ai/                 # AI 能力层（NL2SQL、洞察）
│   ├── connectors/         # 数据源连接器
│   ├── models/             # ORM 模型（SQLite 元信息）
│   ├── schemas/            # Pydantic 请求/响应模型
│   ├── services/           # 业务逻辑层
│   ├── utils/              # 工具函数
│   └── config.py           # 全局配置
├── frontend/               # Streamlit 前端
│   ├── pages/              # 各功能页面
│   ├── components/         # 可复用组件
│   └── api_client.py       # API 调用封装
├── scripts/                # 脚本工具
├── tests/                  # 测试
├── data/                   # 运行时数据（SQLite 数据库，自动生成）
├── .env.example            # 配置模板
├── requirements.txt        # 依赖
├── Makefile                # 快捷命令
└── README.md

⚙️ AI 模型配置

AI 模型配置通过系统页面管理，无需修改环境变量或配置文件。

配置步骤

1. 启动系统后，进入「⚙️ 模型管理」页面（侧边栏第一个菜单）
2. 点击「➕ 添加模型」
3. 选择提供商（通义千问 / OpenAI / Ollama / 讯飞星火）
4. 填入模型标识和 API Key
5. 勾选「创建后立即激活」并保存

支持添加多个模型配置，在侧边栏随时切换，无需重启服务。

支持的提供商

提供商	模型标识示例	是否需要 API Key
🔮 通义千问	qwen-plus / qwen-turbo	✅ 是
🤖 OpenAI	gpt-4o / gpt-3.5-turbo	✅ 是
🦙 Ollama	qwen2.5:7b / deepseek-r1:7b	❌ 否
✨ 讯飞星火	generalv3.5	✅ 是

Ollama 本地模型（推荐的本地方案）

1. 安装 Ollama：访问 https://ollama.com 下载安装
2. 拉取模型：

ollama pull qwen2.5:7b        # 通用，~4.7GB
ollama pull qwen2.5-coder:7b  # 代码/SQL 专用，NL2SQL 推荐

3. 在「⚙️ 模型管理」页面添加 Ollama 模型：
   • 提供商选 Ollama
   • API Base 填 http://localhost:11434（Docker 内填 http://host.docker.internal:11434）
   • 模型标识填 qwen2.5:7b

🤝 贡献指南

欢迎贡献代码！请遵循以下流程：

1. Fork 本项目
2. 创建分支：git checkout -b feature/your-feature
3. 提交代码：git commit -m 'feat: add your feature'
4. 推送分支：git push origin feature/your-feature
5. 创建 Pull Request

提交规范

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• refactor: 重构
• test: 测试

📄 开源协议

本项目基于 Apache License 2.0 开源。

⭐ Star History

如果这个项目对你有帮助，请给一个 Star ⭐ 支持一下！