重构readme
This commit is contained in:
541
README.md
541
README.md
@@ -1,436 +1,213 @@
|
||||
# AI 数据分析 Agent
|
||||
# AI-Driven Data Analysis Framework
|
||||
|
||||
一个真正由 AI 驱动的数据分析系统，能够像人类分析师一样理解数据、自主规划分析、执行任务并生成洞察性报告。
|
||||
全自动 AI 数据分析框架。给一个 CSV 文件，AI 自主完成从数据理解到报告生成的全流程。
|
||||
|
||||
## 特性
|
||||
## 核心理念
|
||||
|
||||
- **AI 驱动决策**：让 AI 做决策，而不是执行预定义的规则
|
||||
- **动态适应**：根据数据特征和发现动态调整分析计划
|
||||
- **隐私保护**：AI 不读取原始数据，只通过工具获取摘要信息
|
||||
- **工具驱动**：通过动态工具集赋能 AI 的分析能力
|
||||
- **自然语言交互**：用自然语言描述需求，系统自动理解并执行
|
||||
- **模板支持**：支持使用模板作为参考框架，同时保持灵活性
|
||||
**框架只提供引擎和工具，AI 在运行时做所有决策。**
|
||||
|
||||
- 没有硬编码的列名规则、数据类型判断或分析策略
|
||||
- AI 只能看到元数据（表头、统计摘要、样本值），永远不接触原始数据行
|
||||
- 对任意 CSV 文件自动适配，无需修改代码
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
CSV 文件
|
||||
│
|
||||
▼
|
||||
[1] AI 数据理解 ─── AI 看元数据，推断数据类型、关键字段、质量评分
|
||||
│
|
||||
▼
|
||||
[2] 需求理解 ─────── 解析自然语言需求 + 可选模板，生成分析目标
|
||||
│
|
||||
▼
|
||||
[3] AI 分析规划 ──── AI 根据数据特征和工具库，生成具体任务列表
|
||||
│
|
||||
▼
|
||||
[4] AI 任务执行 ──── ReAct 模式：AI 选工具 → 调用 → 观察结果 → 决定下一步
|
||||
│
|
||||
▼
|
||||
[5] 报告生成 ─────── AI 生成图文结合的 Markdown 报告
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 安装
|
||||
### 1. 安装依赖
|
||||
|
||||
1. 克隆仓库：
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd <repository-name>
|
||||
```
|
||||
|
||||
2. 安装依赖：
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. 配置环境变量：
|
||||
### 2. 配置环境变量
|
||||
|
||||
创建 `.env` 文件（参考 `.env.example`）：
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
创建 `.env` 文件：
|
||||
|
||||
编辑 `.env` 文件，设置 OpenAI API 密钥：
|
||||
```
|
||||
OPENAI_API_KEY=your_api_key_here
|
||||
```env
|
||||
OPENAI_API_KEY=your-api-key
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4
|
||||
```
|
||||
|
||||
### 基本使用
|
||||
支持任何 OpenAI 兼容 API（如自定义 base_url）。
|
||||
|
||||
#### 方式1：命令行接口
|
||||
### 3. 运行分析
|
||||
|
||||
```bash
|
||||
# 完全自主分析
|
||||
python -m src.cli data.csv
|
||||
# 最简用法 — AI 自动决定分析什么、怎么分析
|
||||
python run_analysis_en.py --data your_data.csv
|
||||
|
||||
# 指定分析需求
|
||||
python -m src.cli data.csv -r "分析工单健康度"
|
||||
python run_analysis_en.py --data sales.csv --requirement "分析各产品线的销售趋势和异常"
|
||||
|
||||
# 使用模板
|
||||
python -m src.cli data.csv -t templates/ticket_analysis.md
|
||||
# 使用报告模板
|
||||
python run_analysis_en.py --data tickets.csv --template templates/ticket_analysis.md
|
||||
|
||||
# 指定输出目录
|
||||
python -m src.cli data.csv -o results/
|
||||
|
||||
# 显示详细日志
|
||||
python -m src.cli data.csv -v
|
||||
python run_analysis_en.py --data data.csv --output my_output
|
||||
```
|
||||
|
||||
#### 方式2：Python API
|
||||
### 4. 查看结果
|
||||
|
||||
```python
|
||||
from src.main import run_analysis
|
||||
|
||||
# 运行分析
|
||||
result = run_analysis(
|
||||
data_file="data.csv",
|
||||
user_requirement="分析工单健康度",
|
||||
output_dir="output"
|
||||
)
|
||||
|
||||
# 检查结果
|
||||
if result['success']:
|
||||
print(f"报告路径: {result['report_path']}")
|
||||
print(f"执行时间: {result['elapsed_time']:.1f}秒")
|
||||
else:
|
||||
print(f"分析失败: {result['error']}")
|
||||
```
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景1：完全自主分析
|
||||
|
||||
只需提供数据文件，AI 会自动：
|
||||
- 识别数据类型（工单、销售、用户等）
|
||||
- 推断关键字段的业务含义
|
||||
- 自主决定分析维度
|
||||
- 生成合理的分析计划
|
||||
- 执行分析并生成报告
|
||||
|
||||
```bash
|
||||
python -m src.cli cleaned_data.csv
|
||||
```
|
||||
|
||||
**输出示例**：
|
||||
```
|
||||
数据类型：工单数据
|
||||
关键发现：
|
||||
* 待处理工单占比50%（异常高）
|
||||
* 某车型问题占比80%
|
||||
* 平均处理时长超过标准2倍
|
||||
建议：优先处理该车型的积压工单
|
||||
```
|
||||
|
||||
### 场景2：指定分析方向
|
||||
|
||||
用自然语言描述需求，AI 会：
|
||||
- 理解抽象概念的业务含义
|
||||
- 将其转化为具体指标
|
||||
- 根据数据特征选择合适的分析方法
|
||||
- 生成针对性的报告
|
||||
|
||||
```bash
|
||||
python -m src.cli cleaned_data.csv -r "我想了解工单的健康度"
|
||||
```
|
||||
|
||||
**AI 理解**：
|
||||
- 健康度 = 关闭率 + 处理效率 + 积压情况 + 响应及时性
|
||||
|
||||
**AI 分析**：
|
||||
- 关闭率：75%（中等）
|
||||
- 平均处理时长：48小时（偏长）
|
||||
- 积压工单：50%（严重）
|
||||
- 健康度评分：60/100（需改进）
|
||||
|
||||
### 场景3：使用模板
|
||||
|
||||
使用模板作为参考框架，AI 会：
|
||||
- 理解模板的结构和要求
|
||||
- 检查数据是否满足模板要求
|
||||
- 如果数据缺少某些字段，灵活调整
|
||||
- 按模板结构组织报告
|
||||
|
||||
```bash
|
||||
python -m src.cli cleaned_data.csv -t templates/ticket_analysis.md
|
||||
```
|
||||
|
||||
### 场景4：迭代深入分析
|
||||
|
||||
AI 能根据发现自主深入分析：
|
||||
- 识别异常或关键发现
|
||||
- 自主决定是否需要深入分析
|
||||
- 动态调整分析计划
|
||||
- 追踪问题的根因
|
||||
|
||||
## 系统架构
|
||||
|
||||
系统采用五阶段流水线架构，每个阶段都由 AI 驱动：
|
||||
每次运行会在输出目录下创建带时间戳的子目录：
|
||||
|
||||
```
|
||||
数据输入 → 数据理解 → 需求理解 → 分析规划 → 任务执行 → 报告生成
|
||||
analysis_output/
|
||||
└── run_20260309_143025/
|
||||
├── analysis_report.md ← 图文结合的分析报告
|
||||
└── charts/
|
||||
├── bar_chart.png
|
||||
├── pie_chart.png
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 1. 数据理解（Data Understanding）
|
||||
- 加载和解析 CSV 文件
|
||||
- 推断数据类型和业务含义
|
||||
- 识别关键字段
|
||||
- 评估数据质量
|
||||
|
||||
### 2. 需求理解（Requirement Understanding）
|
||||
- 解析用户的自然语言需求
|
||||
- 将抽象概念转化为具体指标
|
||||
- 解析和理解分析模板
|
||||
- 检查数据是否支持需求
|
||||
|
||||
### 3. 分析规划（Analysis Planning）
|
||||
- 根据数据特征和需求生成任务列表
|
||||
- 确定任务优先级和依赖关系
|
||||
- 选择合适的分析方法
|
||||
- 生成初始工具配置
|
||||
|
||||
### 4. 任务执行（Task Execution）
|
||||
- 使用 ReAct 模式（思考-行动-观察）执行任务
|
||||
- 动态选择和调用工具
|
||||
- 验证结果并处理错误
|
||||
- 根据发现动态调整计划
|
||||
|
||||
### 5. 报告生成（Report Generation）
|
||||
- 提炼关键发现
|
||||
- 组织报告结构
|
||||
- 生成结论和建议
|
||||
- 嵌入图表和可视化
|
||||
|
||||
## 命令行参数
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
usage: python -m src.cli [-h] [-r REQUIREMENT] [-t TEMPLATE] [-o OUTPUT]
|
||||
[-v] [--no-progress] [--version]
|
||||
data_file
|
||||
|
||||
positional arguments:
|
||||
data_file 数据文件路径（CSV 格式）
|
||||
|
||||
optional arguments:
|
||||
-h, --help 显示帮助信息
|
||||
-r, --requirement 用户需求（自然语言）
|
||||
-t, --template 模板文件路径（Markdown 格式）
|
||||
-o, --output 输出目录，默认为 "output"
|
||||
-v, --verbose 显示详细日志
|
||||
--no-progress 不显示进度条
|
||||
--version 显示版本信息
|
||||
├── 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 在运行时自主选择和组合：
|
||||
|
||||
在 `.env` 文件中配置以下参数：
|
||||
|
||||
```bash
|
||||
# OpenAI API 配置
|
||||
OPENAI_API_KEY=your_api_key_here
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4
|
||||
|
||||
# 性能参数
|
||||
MAX_RETRIES=3
|
||||
TIMEOUT=120
|
||||
MAX_ITERATIONS=10
|
||||
|
||||
# 输出配置
|
||||
OUTPUT_DIR=output
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
|
||||
可以创建 `config.json` 文件（参考 `config.example.json`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"llm": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4",
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 4000
|
||||
},
|
||||
"performance": {
|
||||
"max_retries": 3,
|
||||
"timeout": 120,
|
||||
"max_iterations": 10
|
||||
},
|
||||
"output": {
|
||||
"dir": "output",
|
||||
"format": "markdown"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 输出文件
|
||||
|
||||
分析完成后，输出目录包含：
|
||||
|
||||
- `analysis_report.md` - 分析报告（Markdown 格式）
|
||||
- `analysis.log` - 执行日志
|
||||
- `*.png` - 生成的图表（如果有）
|
||||
- `data_profile.json` - 数据画像（可选）
|
||||
- `analysis_plan.json` - 分析计划（可选）
|
||||
|
||||
## 工具系统
|
||||
|
||||
系统提供丰富的分析工具，并根据数据特征动态调整：
|
||||
|
||||
### 数据查询工具
|
||||
- `get_column_distribution` - 获取列的分布统计
|
||||
- `get_value_counts` - 获取值计数
|
||||
- `get_time_series` - 获取时间序列数据
|
||||
- `get_correlation` - 获取相关性分析
|
||||
|
||||
### 统计分析工具
|
||||
- `calculate_statistics` - 计算描述性统计
|
||||
- `perform_groupby` - 执行分组聚合
|
||||
- `detect_outliers` - 检测异常值
|
||||
- `calculate_trend` - 计算趋势
|
||||
|
||||
### 可视化工具
|
||||
- `create_bar_chart` - 创建柱状图
|
||||
- `create_line_chart` - 创建折线图
|
||||
- `create_pie_chart` - 创建饼图
|
||||
- `create_heatmap` - 创建热力图
|
||||
- `ai_picture` - 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 **永远看不到**原始数据行
|
||||
- AI 只能通过工具获取**聚合结果**（统计值、分布、图表）
|
||||
- 数据画像只包含元数据：列名、数据类型、缺失率、唯一值数、样本值（最多 5 个）
|
||||
- 工具返回结果自动截断（最多 100 行），防止数据泄露
|
||||
|
||||
## 性能指标
|
||||
## 配置
|
||||
|
||||
- 数据理解阶段：< 30秒
|
||||
- 分析规划阶段：< 60秒
|
||||
- 单个任务执行：< 120秒
|
||||
- 完整分析流程：< 30分钟（取决于数据大小和任务数量）
|
||||
- 支持最大 100万行数据
|
||||
### 环境变量（推荐）
|
||||
|
||||
## 故障排除
|
||||
通过 `.env` 文件或系统环境变量配置：
|
||||
|
||||
### 问题1：找不到 OpenAI API 密钥
|
||||
```env
|
||||
# LLM 配置（必填）
|
||||
OPENAI_API_KEY=sk-xxx
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4
|
||||
|
||||
**错误信息**：`OpenAI API key not found`
|
||||
|
||||
**解决方案**：
|
||||
1. 确保 `.env` 文件存在
|
||||
2. 检查 `OPENAI_API_KEY` 是否正确设置
|
||||
3. 确保 `.env` 文件在项目根目录
|
||||
|
||||
### 问题2：数据加载失败
|
||||
|
||||
**错误信息**：`Failed to load data file`
|
||||
|
||||
**解决方案**：
|
||||
1. 检查文件路径是否正确
|
||||
2. 确保文件是 CSV 格式
|
||||
3. 尝试使用 `-v` 参数查看详细错误信息
|
||||
4. 检查文件编码（系统会自动尝试多种编码）
|
||||
|
||||
### 问题3：分析失败
|
||||
|
||||
**错误信息**：`Analysis failed`
|
||||
|
||||
**解决方案**：
|
||||
1. 检查日志文件 `output/analysis.log`
|
||||
2. 确保数据文件不为空
|
||||
3. 确保数据格式正确
|
||||
4. 检查 API 配额是否充足
|
||||
|
||||
### 问题4：AI 调用超时
|
||||
|
||||
**错误信息**：`LLM call timeout`
|
||||
|
||||
**解决方案**：
|
||||
1. 增加 `TIMEOUT` 配置值
|
||||
2. 检查网络连接
|
||||
3. 尝试使用更快的模型
|
||||
|
||||
## 开发和测试
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 运行所有测试
|
||||
pytest
|
||||
|
||||
# 运行单元测试
|
||||
pytest tests/ -k "not properties"
|
||||
|
||||
# 运行属性测试
|
||||
pytest tests/ -k "properties"
|
||||
|
||||
# 运行集成测试
|
||||
pytest tests/test_integration.py -v
|
||||
|
||||
# 运行特定测试
|
||||
pytest tests/test_integration.py::TestEndToEndAnalysis -v
|
||||
|
||||
# 显示覆盖率
|
||||
pytest --cov=src --cov-report=html
|
||||
# 可选配置
|
||||
LLM_TEMPERATURE=0.7
|
||||
LLM_TIMEOUT=120
|
||||
AGENT_MAX_ROUNDS=20
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
### 项目结构
|
||||
### JSON 配置文件
|
||||
|
||||
```
|
||||
.
|
||||
├── src/ # 源代码
|
||||
│ ├── main.py # 主流程编排
|
||||
│ ├── cli.py # 命令行接口
|
||||
│ ├── config.py # 配置管理
|
||||
│ ├── data_access.py # 数据访问层
|
||||
│ ├── error_handling.py # 错误处理
|
||||
│ ├── logging_config.py # 日志配置
|
||||
│ ├── engines/ # 分析引擎
|
||||
│ │ ├── data_understanding.py
|
||||
│ │ ├── requirement_understanding.py
|
||||
│ │ ├── analysis_planning.py
|
||||
│ │ ├── task_execution.py
|
||||
│ │ ├── plan_adjustment.py
|
||||
│ │ └── report_generation.py
|
||||
│ ├── models/ # 数据模型
|
||||
│ │ ├── data_profile.py
|
||||
│ │ ├── requirement_spec.py
|
||||
│ │ ├── analysis_plan.py
|
||||
│ │ └── analysis_result.py
|
||||
│ └── tools/ # 分析工具
|
||||
│ ├── base.py
|
||||
│ ├── query_tools.py
|
||||
│ ├── stats_tools.py
|
||||
│ ├── viz_tools.py
|
||||
│ └── tool_manager.py
|
||||
├── tests/ # 测试文件
|
||||
├── templates/ # 分析模板
|
||||
├── test_data/ # 测试数据
|
||||
├── examples/ # 示例脚本
|
||||
├── docs/ # 文档
|
||||
├── .env.example # 环境变量示例
|
||||
├── config.example.json # 配置文件示例
|
||||
├── requirements.txt # 依赖列表
|
||||
└── README.md # 本文件
|
||||
也可以使用 `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 会自动在规划和执行阶段发现并使用新工具。
|
||||
|
||||
查看 `examples/` 目录获取更多示例：
|
||||
## 依赖
|
||||
|
||||
- `autonomous_analysis.py` - 完全自主分析示例
|
||||
- `requirement_based_analysis.py` - 指定需求分析示例
|
||||
- `template_based_analysis.py` - 基于模板分析示例
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎贡献！请遵循以下步骤：
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 创建 Pull Request
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题或建议，请创建 Issue。
|
||||
|
||||
## 致谢
|
||||
|
||||
感谢所有贡献者和使用者的支持！
|
||||
- Python 3.10+
|
||||
- pandas, numpy, matplotlib, scipy, scikit-learn
|
||||
- openai（兼容任何 OpenAI API 格式的 LLM 服务）
|
||||
- python-dotenv
|
||||
|
||||
Reference in New Issue
Block a user