vibe_data_ana/README_MAIN.md

AI 数据分析 Agent - 主流程使用指南

概述

这是一个真正由 AI 驱动的数据分析系统，能够自动理解数据、规划分析、执行任务并生成报告。

快速开始

1. 安装依赖

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：使用命令行接口

# 完全自主分析
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

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：完全自主分析

python -m src.cli cleaned_data.csv

系统会自动：

• 识别数据类型（工单、销售、用户等）
• 推断关键字段的业务含义
• 自主决定分析维度
• 生成合理的分析计划
• 执行分析并生成报告

示例2：指定分析方向

python -m src.cli cleaned_data.csv -r "我想了解工单的健康度"

系统会：

• 理解"健康度"的业务含义
• 将抽象概念转化为具体指标（关闭率、处理效率、积压情况等）
• 根据数据特征选择合适的分析方法
• 生成针对性的报告

示例3：使用模板

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
• 确保数据文件不为空
• 确保数据格式正确

开发和测试

运行测试

# 运行所有测试
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。