214 lines
6.6 KiB
Markdown
214 lines
6.6 KiB
Markdown
# AI-Driven Data Analysis Framework
|
||
|
||
全自动 AI 数据分析框架。给一个 CSV 文件，AI 自主完成从数据理解到报告生成的全流程。
|
||
|
||
## 核心理念
|
||
|
||
**框架只提供引擎和工具，AI 在运行时做所有决策。**
|
||
|
||
- 没有硬编码的列名规则、数据类型判断或分析策略
|
||
- AI 只能看到元数据（表头、统计摘要、样本值），永远不接触原始数据行
|
||
- 对任意 CSV 文件自动适配，无需修改代码
|
||
|
||
## 工作流程
|
||
|
||
```
|
||
CSV 文件
|
||
│
|
||
▼
|
||
[1] AI 数据理解 ─── AI 看元数据，推断数据类型、关键字段、质量评分
|
||
│
|
||
▼
|
||
[2] 需求理解 ─────── 解析自然语言需求 + 可选模板，生成分析目标
|
||
│
|
||
▼
|
||
[3] AI 分析规划 ──── AI 根据数据特征和工具库，生成具体任务列表
|
||
│
|
||
▼
|
||
[4] AI 任务执行 ──── ReAct 模式：AI 选工具 → 调用 → 观察结果 → 决定下一步
|
||
│
|
||
▼
|
||
[5] 报告生成 ─────── AI 生成图文结合的 Markdown 报告
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
创建 `.env` 文件：
|
||
|
||
```env
|
||
OPENAI_API_KEY=your-api-key
|
||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||
OPENAI_MODEL=gpt-4
|
||
```
|
||
|
||
支持任何 OpenAI 兼容 API（如自定义 base_url）。
|
||
|
||
### 3. 运行分析
|
||
|
||
```bash
|
||
# 最简用法 — AI 自动决定分析什么、怎么分析
|
||
python run_analysis_en.py --data your_data.csv
|
||
|
||
# 指定分析需求
|
||
python run_analysis_en.py --data sales.csv --requirement "分析各产品线的销售趋势和异常"
|
||
|
||
# 使用报告模板
|
||
python run_analysis_en.py --data tickets.csv --template templates/ticket_analysis.md
|
||
|
||
# 指定输出目录
|
||
python run_analysis_en.py --data data.csv --output my_output
|
||
```
|
||
|
||
### 4. 查看结果
|
||
|
||
每次运行会在输出目录下创建带时间戳的子目录：
|
||
|
||
```
|
||
analysis_output/
|
||
└── run_20260309_143025/
|
||
├── analysis_report.md ← 图文结合的分析报告
|
||
└── charts/
|
||
├── bar_chart.png
|
||
├── pie_chart.png
|
||
└── ...
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── run_analysis_en.py # 主入口（5 阶段 pipeline）
|
||
├── src/
|
||
│ ├── config.py # 配置管理（环境变量 / JSON / .env）
|
||
│ ├── data_access.py # 数据访问层（隐私保护，AI 不可见原始数据）
|
||
│ ├── engines/
|
||
│ │ ├── ai_data_understanding.py # [阶段1] AI 数据理解
|
||
│ │ ├── requirement_understanding.py # [阶段2] 需求解析
|
||
│ │ ├── analysis_planning.py # [阶段3] AI 分析规划
|
||
│ │ ├── task_execution.py # [阶段4] ReAct 任务执行
|
||
│ │ └── report_generation.py # [阶段5] 报告生成
|
||
│ ├── tools/
|
||
│ │ ├── base.py # 工具抽象基类 + 注册表
|
||
│ │ ├── tool_manager.py # 工具筛选（按数据特征过滤）
|
||
│ │ ├── query_tools.py # 查询工具（分布、计数、时间序列、相关性）
|
||
│ │ ├── stats_tools.py # 统计工具（描述统计、分组聚合、异常检测、趋势）
|
||
│ │ └── viz_tools.py # 可视化工具（柱状图、折线图、饼图、热力图）
|
||
│ └── models/ # 数据模型
|
||
│ ├── data_profile.py # DataProfile, ColumnInfo
|
||
│ ├── requirement_spec.py # RequirementSpec, AnalysisObjective
|
||
│ ├── analysis_plan.py # AnalysisPlan, AnalysisTask
|
||
│ └── analysis_result.py # AnalysisResult
|
||
├── templates/ # 报告模板（可选）
|
||
├── test_data/ # 示例数据
|
||
└── examples/ # 使用示例
|
||
```
|
||
|
||
## 内置工具
|
||
|
||
框架提供 12 个分析工具，AI 在运行时自主选择和组合：
|
||
|
||
| 类别 | 工具 | 说明 |
|
||
|------|------|------|
|
||
| 查询 | `get_column_distribution` | 列分布统计（值计数、百分比） |
|
||
| 查询 | `get_value_counts` | 唯一值计数 |
|
||
| 查询 | `get_time_series` | 时间序列聚合 |
|
||
| 查询 | `get_correlation` | 相关性矩阵 |
|
||
| 统计 | `calculate_statistics` | 描述性统计（均值、中位数、偏度等） |
|
||
| 统计 | `perform_groupby` | 分组聚合 |
|
||
| 统计 | `detect_outliers` | 异常值检测（IQR / Z-score） |
|
||
| 统计 | `calculate_trend` | 趋势分析（线性回归） |
|
||
| 可视化 | `create_bar_chart` | 柱状图 |
|
||
| 可视化 | `create_line_chart` | 折线图 |
|
||
| 可视化 | `create_pie_chart` | 饼图 |
|
||
| 可视化 | `create_heatmap` | 热力图 |
|
||
|
||
## 隐私保护
|
||
|
||
数据访问层（`DataAccessLayer`）是核心安全边界：
|
||
|
||
- AI **永远看不到**原始数据行
|
||
- AI 只能通过工具获取**聚合结果**（统计值、分布、图表）
|
||
- 数据画像只包含元数据：列名、数据类型、缺失率、唯一值数、样本值（最多 5 个）
|
||
- 工具返回结果自动截断（最多 100 行），防止数据泄露
|
||
|
||
## 配置
|
||
|
||
### 环境变量（推荐）
|
||
|
||
通过 `.env` 文件或系统环境变量配置：
|
||
|
||
```env
|
||
# LLM 配置（必填）
|
||
OPENAI_API_KEY=sk-xxx
|
||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||
OPENAI_MODEL=gpt-4
|
||
|
||
# 可选配置
|
||
LLM_TEMPERATURE=0.7
|
||
LLM_TIMEOUT=120
|
||
AGENT_MAX_ROUNDS=20
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
### JSON 配置文件
|
||
|
||
也可以使用 `config.example.json` 作为模板创建配置文件。
|
||
|
||
## 报告模板
|
||
|
||
可以提供 Markdown 模板来控制报告结构。模板中的占位符会被 AI 用实际分析数据填充。
|
||
|
||
参考 `templates/` 目录下的示例模板。
|
||
|
||
## 扩展工具
|
||
|
||
实现 `AnalysisTool` 抽象类并注册即可：
|
||
|
||
```python
|
||
from src.tools.base import AnalysisTool, register_tool
|
||
|
||
class MyCustomTool(AnalysisTool):
|
||
@property
|
||
def name(self) -> str:
|
||
return "my_custom_tool"
|
||
|
||
@property
|
||
def description(self) -> str:
|
||
return "工具描述（AI 会看到这段文字来决定是否使用）"
|
||
|
||
@property
|
||
def parameters(self) -> dict:
|
||
return {
|
||
"type": "object",
|
||
"properties": {
|
||
"column": {"type": "string", "description": "列名"}
|
||
},
|
||
"required": ["column"]
|
||
}
|
||
|
||
def execute(self, data, **kwargs) -> dict:
|
||
# 实现分析逻辑，返回聚合结果
|
||
return {"result": "..."}
|
||
|
||
def is_applicable(self, data_profile) -> bool:
|
||
return True
|
||
|
||
register_tool(MyCustomTool())
|
||
```
|
||
|
||
注册后，AI 会自动在规划和执行阶段发现并使用新工具。
|
||
|
||
## 依赖
|
||
|
||
- Python 3.10+
|
||
- pandas, numpy, matplotlib, scipy, scikit-learn
|
||
- openai（兼容任何 OpenAI API 格式的 LLM 服务）
|
||
- python-dotenv
|