# analyticsSys

**Repository Path**: dywen2172/analyticsSys

## Basic Information

- **Project Name**: analyticsSys
- **Description**: xxx
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# analyticsSys

企业级智能数据分析系统，将自然语言提问转化为可执行的数据查询、图表结果与分析能力。围绕 ChatBI / Text-to-SQL / RAG / 嵌入式助手 / 数据源治理构建的完整平台。

## 功能概览

- 管理员配置大模型、数据源、权限、工作空间和嵌入式助手
- 业务用户通过聊天进行问数、看图、导出结果、追问分析和预测
- 通过术语库、数据训练、表结构注释、历史样例等上下文提升 SQL 生成质量
- 支持内置 Web 界面和嵌入页面 / MCP 接口两种使用方式

## 功能模块

### 智能问数 (ChatBI)

对应代码：`backend/apps/chat`、`frontend/src/views/chat`

- 自然语言提问触发问答流程
- 大模型生成 SQL → 执行查询 → 组织图表数据 → 流式返回前端
- 重新生成、推荐问题、结果分析、预测数据
- 导出查询结果为 Excel
- 返回内容涵盖：SQL 执行结果、图表配置与图片、分析/预测结果、执行日志与使用量

### 数据源接入与元数据治理

对应代码：`backend/apps/datasource`、`frontend/src/views/ds`

- 数据源连接管理（新增、编辑、删除、连通性检测）
- 拉取数据表和字段信息
- 选取可供问答使用的表
- 数据预览
- 维护表注释、字段注释、字段权限
- Excel/CSV 导入 PostgreSQL
- 导出/导入数据源 schema 注释模板

### 术语库与数据训练

对应代码：`backend/apps/terminology`、`backend/apps/data_training`

- 维护业务术语、别名、概念映射
- 存储训练样本与校准数据
- 结合 embedding 检索为提示词和上下文构造提供辅助
- 系统启动时自动补齐 embedding 数据

### 仪表板与可视化编辑

对应代码：`backend/apps/dashboard`、`frontend/src/views/dashboard`

- Dashboard 浏览与管理
- 画布式编辑器
- 图表预览与组件化渲染
- 聊天问答结果联动生成图表

### 嵌入式助手与外部集成

对应代码：`backend/apps/system/api/assistant.py`、`frontend/src/views/system/embedded`、`frontend/src/views/embedded`

- 为不同业务域创建嵌入式助手应用
- 限制助手可访问的数据范围和域名来源
- 自定义嵌入 UI（logo、浮标图标等）
- 独立嵌入页面、预览页和 token 校验

### MCP 集成接口

对应代码：`backend/apps/mcp/mcp.py`、`main.py`（`FastApiMCP`）

- 启动会话
- 查询工作空间
- 获取数据源列表
- 发起问答
- 调用外部助手

### 系统管理与安全控制

对应代码：`backend/apps/system`、前端 `system` / `set` 路由

- 登录认证与 token 鉴权
- 用户、成员、工作空间管理
- AI 模型配置
- 参数配置与系统变量
- 平台接入与认证方式配置
- API Key 管理
- 审计日志
- 工作空间隔离、角色权限、按资源授权、嵌入域名校验

## 技术架构

### 整体结构

前后端分离 + 辅助渲染服务：

| 模块 | 说明 |
|------|------|
| `frontend` | Vue 3 + TypeScript 单页应用 |
| `backend` | FastAPI + SQLModel + Alembic 主业务服务 |
| `g2-ssr` | Node.js 图表服务端渲染服务 |
| `installer` | 安装与运维脚本 |
| `tests` | 供应商配置与模型连通性测试 |

运行时服务端口：

| 端口 | 服务 |
|------|------|
| 8000 | 主 Web / API 服务 |
| 8001 | MCP 服务 |
| 3000 | G2 SSR 图表渲染服务 |

系统数据库为 PostgreSQL，容器镜像内集成了本地 PostgreSQL 启动流程。

### 后端

入口：`backend/main.py`

- 基于 FastAPI
- `lifespan` 启动逻辑自动执行 Alembic 迁移
- 启动时初始化缓存、动态 CORS、embedding 数据
- API 文档支持多语言占位符替换
- 中间件统一处理 token、响应包装、请求上下文
- 同时挂载标准 API 和 MCP Server

路由聚合：`backend/apps/api.py`（登录与用户、工作空间、助手应用、AI 模型、设置项、术语库、数据训练、数据源、聊天问答、仪表板、MCP、参数与变量）

### 大模型与 RAG

模型工厂：`backend/apps/ai_model/model_factory.py`

支持的模型协议：

- OpenAI 协议兼容模型
- vLLM / OpenAI 兼容模型
- Azure OpenAI

已适配的模型供应商：阿里云百炼、千帆、DeepSeek、腾讯混元、讯飞星火、Gemini、OpenAI、Kimi、腾讯云、火山引擎、MiniMax、通用 OpenAI 兼容接口

RAG 能力：

- 术语 embedding
- 数据训练 embedding
- 表和数据源 embedding
- 结合表结构、样例 SQL、业务术语进行上下文增强

### 向量模型与 Embedding 优化

#### 当前使用的向量模型

| 项目 | 说明 |
|------|------|
| 模型 | `Qwen/Qwen3-Embedding-0.6B` |
| 向量维度 | 1024 |
| 参数量 | 600M |
| 最大文本长度 | 32768 tokens |
| C-MTEB 分数 | 62.34（超越 BGE-M3） |
| 多语言支持 | 90+ 语言 |
| 内存占用 | ~2.1 GB |

向量存储使用 PostgreSQL + pgvector 扩展，无需独立向量数据库。

#### 已实施的优化

**1. HNSW 索引**

为 `terminology` 和 `data_training` 表的 embedding 列创建 HNSW 索引，查询速度提升 10-100 倍：

```sql
CREATE INDEX ix_terminology_embedding_hnsw
ON terminology USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
```

迁移文件：`backend/alembic/versions/067_add_hnsw_index.py`

**2. 批量 Embedding 攒批**

将逐条 `session.commit()` 改为循环结束后统一提交，减少数据库事务开销约 80%。

**3. Embedding LRU 缓存**

新增线程安全的 LRU 缓存（默认 10000 条），重复查询命中缓存时速度提升 100 倍+。批量查询时仅对未命中缓存的文本调用模型。

配置项：`EMBEDDING_CACHE_MAX_SIZE=10000`

**4. ONNX 量化加速**

可选启用 ONNX Runtime 加速推理，CPU 场景下推理速度提升 2-3 倍，内存占用降低至约 400MB。

安装方式：

```bash
pip install optimum onnxruntime
# 或
uv pip install sqlbot[onnx]
```

配置项：`EMBEDDING_ONNX_ENABLED=true`

#### 向量模型配置页面

系统管理中新增「向量模型配置」页面（`/system/embedding-model`），支持：

- **本地模型**：使用 HuggingFace Transformers 加载，数据不出域
- **线上模型**：支持 OpenAI 兼容接口（OpenAI、阿里云百炼、DeepSeek 等）
- **测试连接**：保存前可测试模型是否可用
- **切换默认**：切换后自动清空缓存，下次查询使用新模型

#### 环境准备

**1. 安装依赖**

```bash
cd backend

# 基础依赖
uv pip install -r pyproject.toml

# 可选：ONNX 量化加速
uv pip install sqlbot[onnx]

# 可选：线上 embedding 模型支持
uv pip install langchain-openai
```

**2. 下载本地模型**

将 `Qwen3-Embedding-0.6B` 模型放到指定目录：

```bash
# 模型目录结构
/opt/sqlbot/models/embedding/
└── Qwen3-Embedding-0.6B/
    ├── config.json
    ├── tokenizer.json
    ├── tokenizer_config.json
    ├── model.safetensors
    └── ...
```

首次启动时如果本地没有模型，会自动从 HuggingFace 下载（约 1.2 GB）。

**3. 配置环境变量**

在 `.env` 文件中添加：

```env
# Embedding 开关
EMBEDDING_ENABLED=true

# 本地模型路径
LOCAL_MODEL_PATH=/opt/sqlbot/models

# 默认模型标识
DEFAULT_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B

# 相似度阈值（根据实际效果调整）
EMBEDDING_DEFAULT_SIMILARITY=0.3

# 可选：ONNX 量化加速
EMBEDDING_ONNX_ENABLED=false

# 可选：缓存大小
EMBEDDING_CACHE_MAX_SIZE=10000
```

**4. 执行数据库迁移**

```bash
cd backend

# 执行所有迁移（包括 HNSW 索引、模型配置表等）
alembic upgrade head
```

迁移包含：

| 迁移文件 | 内容 |
|----------|------|
| `067_add_hnsw_index.py` | 创建 HNSW 索引 |
| `068_migrate_to_qwen3_embedding.py` | 清理旧 embedding 数据，重建索引 |
| `069_add_embedding_model_config.py` | 新增向量模型配置表 |

**5. 重建 Embedding 数据**

迁移后旧的 embedding 数据会被清空（维度从 768 变为 1024），需要重建：

```bash
# 方式一：启动应用自动重建（检测到 NULL embedding 时自动触发）
python main.py

# 方式二：手动运行重建脚本（可控制进度）
python scripts/rebuild_embeddings.py --batch-size 100 --tables all

# 可选参数：
#   --batch-size 50       每批处理数量（内存不足时调小）
#   --tables terminology  只重建术语表
#   --tables data_training 只重建数据训练表
#   --force               强制重建所有记录（包括已有 embedding 的）
```

**6. 配置线上模型（可选）**

如果需要使用线上 embedding 模型，在页面「系统管理 → 向量模型配置」中新增：

| 字段 | 说明 | 示例 |
|------|------|------|
| 模型名称 | 显示名称 | OpenAI text-embedding-3-small |
| 模型类型 | 选择「线上模型」 | - |
| 模型标识 | 模型名称 | text-embedding-3-small |
| API 地址 | OpenAI 兼容接口地址 | https://api.openai.com/v1 |
| API Key | API 密钥 | sk-xxx |
| 向量维度 | 选填 | 1536 |

支持的线上模型：

| 供应商 | 模型标识 | 维度 |
|--------|---------|------|
| OpenAI | text-embedding-3-small | 1536 |
| OpenAI | text-embedding-3-large | 3072 |
| 阿里云百炼 | text-embedding-v3 | 1024 |
| DeepSeek | deepseek-embedding | 4096 |

**7. 服务器资源要求**

| 场景 | CPU | 内存 | 磁盘 |
|------|-----|------|------|
| 本地模型（标准） | 4 核+ | 4 GB+ | 2 GB（模型文件） |
| 本地模型（ONNX） | 4 格+ | 2 GB+ | 1 GB（ONNX 模型） |
| 线上模型 | 2 核+ | 1 GB+ | 无需本地模型 |

#### Redis 集成

项目支持 Redis 用于缓存、速率限制和分布式协调。

**安装 Redis**

```bash
# Docker 方式（推荐）
docker run -d --name redis-sqlbot -p 6379:6379 redis:7 redis-server --requirepass 123456

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis

# CentOS/RHEL
sudo yum install redis
sudo systemctl start redis
```

**配置**

在 `.env` 中添加：

```env
# 启用 Redis 缓存
CACHE_TYPE=redis
CACHE_REDIS_URL=redis://:123456@localhost:6379/0
```

**Redis 使用场景**

| 场景 | 说明 | TTL |
|------|------|-----|
| API 响应缓存 | `@cache` 装饰器自动缓存 | 24 小时 |
| 数据库连接检查 | 避免频繁连接测试 | 30 秒 |
| 速率限制 | 每用户每分钟 30 次问数 | 60 秒 |
| Embedding 缓存 | 跨进程共享 embedding 结果 | 1 小时 |
| 数据源配置缓存 | 减少数据库查询 | 5 分钟 |

**Redis 键命名规范**

```
sqlbot:cache:*          # API 响应缓存
sqlbot:conn_check:*     # 连接检查缓存
sqlbot:rate:*           # 速率限制
sqlbot:emb:*            # Embedding 缓存
sqlbot:ds_config:*      # 数据源配置缓存
```

**多进程/多实例部署**

启用 Redis 后支持多进程部署（如 gunicorn 多 worker）：

```bash
# 使用 Redis 时，多进程共享缓存和速率限制
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

**不使用 Redis**

如果不配置 Redis，系统自动降级为内存缓存（仅支持单进程）：

```env
CACHE_TYPE=memory
# 或
CACHE_TYPE=None  # 完全禁用缓存
```

**缓存管理接口**

管理员可通过 API 查看 Redis 缓存统计：

```bash
GET /api/v1/system/parameter/cache/stats
Authorization: Bearer <admin_token>
```

返回示例：
```json
{
  "status": "ok",
  "keys_count": 1523,
  "used_memory": "12.5M",
  "connected_clients": 5,
  "key_prefixes": {
    "sqlbot:cache:*": 256,
    "sqlbot:emb:*": 1024,
    "sqlbot:schema:*": 128,
    "sqlbot:query:*": 64,
    "sqlbot:session:*": 12
  }
}
```

**清除缓存**

```bash
# 清除指定数据源的 Schema 缓存
redis-cli -a 123456 DEL "sqlbot:schema:123:*"

# 清除所有 Embedding 缓存
redis-cli -a 123456 --scan --pattern "sqlbot:emb:*" | xargs redis-cli -a 123456 DEL
```

### 数据层

系统库：PostgreSQL，配置见 `backend/common/core/config.py`

支持的外部数据源：PostgreSQL、MySQL、Oracle、SQL Server、ClickHouse、Doris、StarRocks、Kingbase、DM、Redshift、Elasticsearch、Excel/CSV

Schema 迁移：Alembic，版本脚本位于 `backend/alembic/versions`

### 前端

技术栈：Vue 3、TypeScript、Vite、Vue Router、Pinia、Element Plus、Vue I18n、AntV G2 / S2 / X6、TinyMCE

路由结构（`frontend/src/router/index.ts`）：

| 路由域 | 说明 |
|--------|------|
| `chat` | 数据问答 |
| `dashboard` | 仪表板与编辑器 |
| `set` | 工作空间内配置（成员、权限、术语、训练、Prompt） |
| `system` | 全局管理（用户、模型、嵌入、系统参数、认证、平台、审计） |
| `assistant` / `embeddedPage` | 外部嵌入场景 |

### 图表 SSR 服务

独立 Node.js 服务，入口：`g2-ssr/app.js`

- 接收图表类型、坐标轴和数据
- 调用 `@antv/g2-ssr` 渲染图片
- 输出图表文件供问答或嵌入场景引用
- 支持前端可交互图表和服务端静态图像两种输出方式

## 部署

### Docker

根目录文件：`Dockerfile`、`docker-compose.yaml`、`start.sh`

容器启动顺序：

1. PostgreSQL
2. `g2-ssr` 服务
3. MCP 服务（端口 8001）
4. 主服务（端口 8000）

`docker-compose.yaml` 默认挂载目录：

- `data/sqlbot/excel`
- `data/sqlbot/file`
- `data/sqlbot/images`
- `data/sqlbot/logs`
- `data/postgresql`

### 本地开发

环境要求：

- Python 3.11
- Node.js
- PostgreSQL

启动步骤：

1. 启动 PostgreSQL
2. `backend` 目录安装依赖，运行 `uvicorn main:app --reload`
3. （可选）启动 MCP 服务：`uvicorn main:mcp_app --port 8001`
4. `g2-ssr` 目录安装依赖，启动图表渲染服务
5. `frontend` 目录安装依赖，运行 Vite 开发服务器

## 目录结构

```
analyticsSys/
├─ backend/        FastAPI 后端、业务模块、数据库迁移
├─ frontend/       Vue 3 前端
├─ g2-ssr/         G2 图表服务端渲染服务
├─ installer/      安装、卸载、运维脚本
├─ docs/           文档
├─ tests/          测试用例
├─ docker-compose.yaml
├─ Dockerfile
└─ start.sh
```

## 新增功能特性

> 基于 SQLBot 社区用户反馈和实际业务需求，持续优化用户体验和功能完整性。

### 智能问数增强功能

#### 聊天记录导出 📄

对应代码：`frontend/src/views/chat/index.vue`

- **一键导出**：在聊天界面上方添加「导出聊天记录」按钮
- **Markdown 格式**：导出包含完整的提问时间、问题内容、SQL 语句、AI 思考过程、回答内容
- **格式清晰**：结构化的导出文件，便于阅读和分享
- **应用场景**：保存对话历史、团队知识共享、审计追溯

#### 表格 URL 点击跳转 🔗

对应代码：`frontend/src/views/chat/component/charts/Table.ts`

- **智能识别**：自动识别 URL 格式的数据（支持 `http://`、`https://`、`www.`）
- **交互优化**：URL 以蓝色下划线样式显示，易于识别
- **一键跳转**：点击即可在新窗口打开链接，提升操作效率
- **安全策略**：使用 `noopener,noreferrer` 防止潜在的安全风险

#### 智能错误提示与重试 🔄

对应代码：`frontend/src/views/chat/ErrorInfo.vue`

- **错误类型识别**：自动识别 SQL 语法错误、数据库连接错误、超时错误、权限问题、空结果等
- **友好提示**：根据错误类型提供明确的解决建议
  - SQL 语法错误 → 建议检查查询语句
  - 数据库连接错误 → 建议检查数据源
  - 超时错误 → 建议简化查询或减少数据量
  - 权限问题 → 建议联系管理员授权
  - 空结果 → 建议调整查询条件
- **一键重试**：提供「重新查询」按钮，快速修复问题
- **详细日志**：支持查看完整的错误堆栈信息

#### 执行详情增强 📊

对应代码：`frontend/src/views/chat/ExecutionDetails.vue`

- **令牌消耗透明化**：显示输入令牌和输出令牌的分解统计
- **性能监控**：显示平均执行时间、总时间、步骤数等关键指标
- **质量统计**：成功/失败率标签显示
- **优化建议**：帮助用户了解查询效率和资源消耗

### 数据可视化增强

#### 雷达图支持 📈

对应代码：`frontend/src/views/chat/component/charts/Radar.ts`

- **多维度展示**：适合展示多维度的综合评价数据
- **高性能渲染**：基于 G2Plot 的雷达图组件
- **多系列对比**：支持多个数据系列的雷达图对比
- **应用场景**：
  - 多指标综合评价
  - 竞品对比分析
  - 能力评估雷达图
  - KPI 完成度展示

#### 柱状图/条形图模式切换 🔄

对应代码：`frontend/src/views/chat/component/charts/Column.ts`、`Bar.ts`、`DisplayChartBlock.vue`

- **双模式支持**：堆叠模式（Stacked）和并列模式（Grouped）
- **一键切换**：图表上方提供切换按钮，实时切换显示模式
- **交互提示**：切换时显示提示信息，提升用户体验
- **智能适配**：自动识别多系列数据，启用模式切换功能

### 数据源管理优化

#### 字段搜索与筛选 🔍

对应代码：`frontend/src/views/ds/DataTable.vue`

- **快速搜索**：支持按字段名称和备注快速搜索
- **类型筛选**：支持按字段类型筛选，自动统计每种类型的数量
- **灵活排序**：支持按名称、类型、备注长度排序
- **统计信息**：实时显示总字段数、已备注数、未备注数
- **筛选结果**：清晰显示当前筛选条件和结果数量

#### 表备注导入导出 📋

对应代码：`frontend/src/views/ds/DataTable.vue`

- **导出功能**：
  - 导出表备注（CSV 格式）
  - 导出字段备注模板（包含原始备注和自定义备注列）
  - 导出完整表结构
- **批量管理**：支持批量编辑和维护表/字段备注
- **格式兼容**：支持 Excel、CSV 等常见格式
- **模板下载**：提供标准导入模板，方便批量录入

#### 批量导入表关系 📥

对应代码：`frontend/src/views/ds/TableRelationshipImport.vue`、`TableRelationship.vue`

- **多格式支持**：支持 Excel（.xlsx、.xls）、CSV、JSON 三种格式
- **分步流程**：选择文件 → 预览数据 → 确认导入，流程清晰
- **数据验证**：自动验证数据完整性，标记错误行
- **预览功能**：导入前预览所有数据，显示有效/无效记录数
- **模板下载**：提供标准导入模板，包含示例数据
- **错误处理**：显示详细错误信息，跳过无效数据

#### 表关系管理增强 🔗

对应代码：`frontend/src/views/ds/TableRelationship.vue`

- **关系类型支持**：支持一对一（1:1）、一对多（1:N）、多对多（M:N）关系
- **关系描述**：支持为表关系添加描述和备注
- **可视化标记**：关系标签显示类型，悬停显示详情
- **数量统计**：表旁显示关系数量徽章
- **过滤排序**：支持仅显示有关系的表，按名称或关系数排序
- **操作便捷**：支持编辑和删除已有关系

### 系统管理增强

#### API 密钥管理 🔑

对应代码：`frontend/src/views/system/api-key/index.vue`

- **密钥创建**：支持创建多个 API 密钥
- **安全显示**：密钥仅在创建时显示一次，之后仅显示首尾字符
- **有效期控制**：支持永久、7天、30天、90天、1年等多种有效期
- **状态管理**：支持启用/禁用密钥
- **一键复制**：便捷的密钥复制功能
- **密钥描述**：支持为密钥添加描述信息

#### 审计日志 📝

对应代码：`frontend/src/views/system/audit-log/index.vue`

- **日志记录**：完整记录用户的关键操作行为
- **多维筛选**：支持按时间范围、操作类型、用户、关键词筛选
- **详细信息**：记录操作人、操作时间、操作内容、结果状态
- **导出功能**：支持导出审计日志为 CSV 格式
- **错误追踪**：清晰显示错误信息和异常详情

### 功能亮点总结

| 功能模块 | 新增功能 | 用户价值 |
|---------|---------|---------|
| 智能问数 | 聊天记录导出 | 知识沉淀、审计追溯 |
| 智能问数 | 表格 URL 点击跳转 | 操作效率提升 |
| 智能问数 | 智能错误提示与重试 | 问题解决效率 |
| 数据可视化 | 雷达图支持 | 图表类型丰富化 |
| 数据可视化 | 柱状图/条形图模式切换 | 数据展示灵活化 |
| 数据源管理 | 字段搜索筛选 | 快速定位字段 |
| 数据源管理 | 表备注导入导出 | 批量管理效率 |
| 数据源管理 | 批量导入表关系 | 减少重复工作 |
| 数据源管理 | 表关系管理增强 | 关系可视化 |
| 系统管理 | API 密钥管理 | 接口安全控制 |
| 系统管理 | 审计日志 | 操作可追溯 |

### 技术实现特点

- **前端优化**：基于 Vue 3 + TypeScript，采用组件化设计
- **用户体验**：注重交互细节，提供友好的提示和反馈
- **代码质量**：遵循现有代码规范，保持代码风格一致
- **性能考虑**：优化数据处理逻辑，避免性能瓶颈
- **安全策略**：敏感信息处理遵循安全最佳实践

---

## License

请参阅 [LICENSE](LICENSE)。