96927a789d
- Layer 1 Planner: 意图规划，将问题转为结构化分析计划 - Layer 2 Explorer: 自适应探索循环，多轮迭代动态生成 SQL - Layer 3 InsightEngine: 异常检测 + 主动洞察 - Layer 4 ContextManager: 多轮对话上下文记忆 安全设计：AI 只看 Schema + 聚合结果，不接触原始数据。 支持任意 OpenAI 兼容 API（OpenAI / Ollama / DeepSeek / vLLM）
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
|