275 lines
6.4 KiB
Markdown
275 lines
6.4 KiB
Markdown
# AI 数据分析 Agent - 主流程使用指南
|
||
|
||
## 概述
|
||
|
||
这是一个真正由 AI 驱动的数据分析系统，能够自动理解数据、规划分析、执行任务并生成报告。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
创建 `.env` 文件并设置 OpenAI API 密钥：
|
||
|
||
```
|
||
OPENAI_API_KEY=your_api_key_here
|
||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||
```
|
||
|
||
### 3. 运行分析
|
||
|
||
#### 方式1：使用命令行接口
|
||
|
||
```bash
|
||
# 完全自主分析
|
||
python -m src.cli data.csv
|
||
|
||
# 指定分析需求
|
||
python -m src.cli data.csv -r "分析工单健康度"
|
||
|
||
# 使用模板
|
||
python -m src.cli data.csv -t template.md
|
||
|
||
# 指定输出目录
|
||
python -m src.cli data.csv -o results/
|
||
|
||
# 显示详细日志
|
||
python -m src.cli data.csv -v
|
||
```
|
||
|
||
#### 方式2：使用 Python API
|
||
|
||
```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. **数据理解（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 显示版本信息
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 示例1：完全自主分析
|
||
|
||
```bash
|
||
python -m src.cli cleaned_data.csv
|
||
```
|
||
|
||
系统会自动：
|
||
- 识别数据类型（工单、销售、用户等）
|
||
- 推断关键字段的业务含义
|
||
- 自主决定分析维度
|
||
- 生成合理的分析计划
|
||
- 执行分析并生成报告
|
||
|
||
### 示例2：指定分析方向
|
||
|
||
```bash
|
||
python -m src.cli cleaned_data.csv -r "我想了解工单的健康度"
|
||
```
|
||
|
||
系统会：
|
||
- 理解"健康度"的业务含义
|
||
- 将抽象概念转化为具体指标（关闭率、处理效率、积压情况等）
|
||
- 根据数据特征选择合适的分析方法
|
||
- 生成针对性的报告
|
||
|
||
### 示例3：使用模板
|
||
|
||
```bash
|
||
python -m src.cli cleaned_data.csv -t templates/ticket_analysis.md
|
||
```
|
||
|
||
系统会：
|
||
- 理解模板的结构和要求
|
||
- 检查数据是否满足模板要求
|
||
- 如果数据缺少某些字段，灵活调整
|
||
- 按模板结构组织报告
|
||
|
||
## 输出文件
|
||
|
||
分析完成后，输出目录包含：
|
||
|
||
- `analysis_report.md` - 分析报告（Markdown 格式）
|
||
- `analysis.log` - 执行日志
|
||
- `*.png` - 生成的图表（如果有）
|
||
|
||
## 日志和可观察性
|
||
|
||
系统提供详细的日志记录：
|
||
|
||
- **进度显示**：实时显示当前执行阶段和进度
|
||
- **AI 思考过程**：显示 AI 的决策过程（使用 `-v` 参数）
|
||
- **执行摘要**：显示各阶段的执行时间和状态
|
||
- **错误追踪**：详细的错误信息和堆栈跟踪
|
||
|
||
## 错误处理
|
||
|
||
系统具有强大的错误处理能力：
|
||
|
||
- **数据加载错误**：自动尝试多种编码和分隔符
|
||
- **AI 调用错误**：重试机制和指数退避
|
||
- **工具执行错误**：参数验证和异常捕获
|
||
- **任务执行错误**：依赖检查和错误恢复
|
||
|
||
## 性能指标
|
||
|
||
- 数据理解阶段：< 30秒
|
||
- 完整分析流程：< 30分钟（取决于数据大小和任务数量）
|
||
- 支持最大 100万行数据
|
||
|
||
## 隐私保护
|
||
|
||
系统遵循严格的隐私保护原则：
|
||
|
||
- AI 不能直接访问原始数据
|
||
- 只能通过工具获取聚合结果
|
||
- 数据画像只包含元数据和统计摘要
|
||
- 所有原始数据处理在本地完成
|
||
|
||
## 故障排除
|
||
|
||
### 问题1：找不到 OpenAI API 密钥
|
||
|
||
**解决方案**：确保 `.env` 文件存在并包含正确的 API 密钥。
|
||
|
||
### 问题2：数据加载失败
|
||
|
||
**解决方案**：
|
||
- 检查文件路径是否正确
|
||
- 确保文件是 CSV 格式
|
||
- 尝试使用 `-v` 参数查看详细错误信息
|
||
|
||
### 问题3：分析失败
|
||
|
||
**解决方案**：
|
||
- 检查日志文件 `output/analysis.log`
|
||
- 确保数据文件不为空
|
||
- 确保数据格式正确
|
||
|
||
## 开发和测试
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行集成测试
|
||
pytest tests/test_integration.py -v
|
||
|
||
# 运行特定测试
|
||
pytest tests/test_integration.py::TestEndToEndAnalysis -v
|
||
```
|
||
|
||
### 代码结构
|
||
|
||
```
|
||
src/
|
||
├── main.py # 主流程编排
|
||
├── cli.py # 命令行接口
|
||
├── logging_config.py # 日志配置
|
||
├── data_access.py # 数据访问层
|
||
├── error_handling.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
|
||
```
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献！请遵循以下步骤：
|
||
|
||
1. Fork 项目
|
||
2. 创建特性分支
|
||
3. 提交更改
|
||
4. 推送到分支
|
||
5. 创建 Pull Request
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请创建 Issue。
|