118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
|
# 数据分析 Agent —— Schema-Only + 四层架构自适应分析
|
|||
|
|
|
|||
|
|
**AI 只看表结构，不碰原始数据。通过四层架构自适应探索，生成深度分析报告。**
|
|||
|
|
|
|||
|
|
## 架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────┐
|
|||
|
|
│ Agent (编排层) │
|
|||
|
|
│ 接收问题 → 调度四层 → 输出报告 │
|
|||
|
|
└──────┬──────────┬──────────┬──────────┬─────────────────┘
|
|||
|
|
│ │ │ │
|
|||
|
|
┌────▼────┐ ┌──▼─────┐ ┌─▼──────┐ ┌▼─────────┐
|
|||
|
|
│ Planner │ │Explorer│ │Insight │ │ Context │
|
|||
|
|
│ 意图规划 │ │探索循环 │ │异常检测 │ │ 上下文记忆 │
|
|||
|
|
└─────────┘ └────────┘ └────────┘ └──────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 四层分工
|
|||
|
|
|
|||
|
|
| 层 | 组件 | 职责 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| L1 | **Planner** | 理解用户意图，生成结构化分析计划（类型、维度、指标） |
|
|||
|
|
| L2 | **Explorer** | 基于计划多轮迭代探索，每轮根据上一轮结果决定下一步 |
|
|||
|
|
| L3 | **InsightEngine** | 从探索结果中检测异常、趋势、关联，输出主动洞察 |
|
|||
|
|
| L4 | **ContextManager** | 管理多轮对话历史，后续问题可引用之前的分析 |
|
|||
|
|
|
|||
|
|
### 安全隔离
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
用户提问 → Agent 看 Schema 生成 SQL → 沙箱执行 → 聚合结果 → Agent 生成报告
|
|||
|
|
↑
|
|||
|
|
原始数据永远留在这里
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **Schema 提取器**：只提取表结构、列类型、行数、枚举值，不碰数据
|
|||
|
|
- **沙箱执行器**：禁止 SELECT * / DDL / DML，必须聚合函数，小样本抑制（n<5）
|
|||
|
|
- **AI 的视角**：只有 Schema + 聚合统计结果，从未接触任何一行原始数据
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. 安装依赖
|
|||
|
|
pip install openai
|
|||
|
|
|
|||
|
|
# 2. 配置 LLM（兼容 OpenAI API 格式）
|
|||
|
|
|
|||
|
|
# OpenAI
|
|||
|
|
export LLM_API_KEY=sk-xxx
|
|||
|
|
export LLM_BASE_URL=https://api.openai.com/v1
|
|||
|
|
export LLM_MODEL=gpt-4o
|
|||
|
|
|
|||
|
|
# Ollama（本地部署，隐私优先）
|
|||
|
|
export LLM_API_KEY=ollama
|
|||
|
|
export LLM_BASE_URL=http://localhost:11434/v1
|
|||
|
|
export LLM_MODEL=qwen2.5-coder:7b
|
|||
|
|
|
|||
|
|
# DeepSeek
|
|||
|
|
export LLM_API_KEY=sk-xxx
|
|||
|
|
export LLM_BASE_URL=https://api.deepseek.com
|
|||
|
|
export LLM_MODEL=deepseek-chat
|
|||
|
|
|
|||
|
|
# 3. 运行演示（自动创建 5 万条示例数据 + 3 个分析任务）
|
|||
|
|
python3 demo.py
|
|||
|
|
|
|||
|
|
# 4. 交互式分析
|
|||
|
|
python3 cli.py
|
|||
|
|
|
|||
|
|
# 5. 分析你自己的数据库
|
|||
|
|
python3 cli.py /path/to/your.db
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 文件结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
├── config.py # 配置（LLM、安全规则、探索轮数）
|
|||
|
|
├── schema_extractor.py # Schema 提取器（只提取结构）
|
|||
|
|
├── sandbox_executor.py # 沙箱执行器（SQL 验证 + 结果脱敏）
|
|||
|
|
├── planner.py # [L1] 意图规划器
|
|||
|
|
├── explorer.py # [L2] 自适应探索器
|
|||
|
|
├── insights.py # [L3] 洞察引擎（异常检测）
|
|||
|
|
├── context.py # [L4] 上下文管理器
|
|||
|
|
├── reporter.py # 报告生成器
|
|||
|
|
├── agent.py # Agent 编排层
|
|||
|
|
├── demo.py # 一键演示
|
|||
|
|
├── cli.py # 交互式 CLI
|
|||
|
|
├── requirements.txt # 依赖
|
|||
|
|
└── README.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 对比预制脚本
|
|||
|
|
|
|||
|
|
| | 预制脚本 / 模板 | 本方案（四层架构） |
|
|||
|
|
|---|---|---|
|
|||
|
|
| SQL 生成 | 模板拼接 | LLM 动态生成 |
|
|||
|
|
| 查询数量 | 固定 | 1-6 轮，AI 自适应 |
|
|||
|
|
| 后续追问 | 无 | AI 看到结果后判断是否深挖 |
|
|||
|
|
| 异常发现 | 无 | 主动检测 + 主动输出 |
|
|||
|
|
| 多轮对话 | 无 | 上下文记忆，可引用历史分析 |
|
|||
|
|
| 适用场景 | 已知分析模式 | 探索性分析、开放性问题 |
|
|||
|
|
|
|||
|
|
## CLI 命令
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
📊 > 帮我分析各地区的销售表现 # 分析问题
|
|||
|
|
📊 > rounds=3 最近的趋势怎么样 # 限制探索轮数
|
|||
|
|
📊 > schema # 查看数据库 Schema
|
|||
|
|
📊 > history # 查看分析历史
|
|||
|
|
📊 > audit # 查看 SQL 审计日志
|
|||
|
|
📊 > clear # 清空历史
|
|||
|
|
📊 > help # 帮助
|
|||
|
|
📊 > quit # 退出
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## License
|
|||
|
|
|
|||
|
|
MIT
|