vibe_data_ana/README.md

AI 数据分析 Agent

一个真正由 AI 驱动的数据分析系统，能够像人类分析师一样理解数据、自主规划分析、执行任务并生成洞察性报告。

特性

• AI 驱动决策：让 AI 做决策，而不是执行预定义的规则
• 动态适应：根据数据特征和发现动态调整分析计划
• 隐私保护：AI 不读取原始数据，只通过工具获取摘要信息
• 工具驱动：通过动态工具集赋能 AI 的分析能力
• 自然语言交互：用自然语言描述需求，系统自动理解并执行
• 模板支持：支持使用模板作为参考框架，同时保持灵活性

快速开始

安装

1. 克隆仓库：

git clone <repository-url>
cd <repository-name>

2. 安装依赖：

pip install -r requirements.txt

3. 配置环境变量：

创建 .env 文件（参考 .env.example）：

cp .env.example .env

编辑 .env 文件，设置 OpenAI API 密钥：

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4

基本使用

方式1：命令行接口

# 完全自主分析
python -m src.cli data.csv

# 指定分析需求
python -m src.cli data.csv -r "分析工单健康度"

# 使用模板
python -m src.cli data.csv -t templates/ticket_analysis.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：完全自主分析

只需提供数据文件，AI 会自动：

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

python -m src.cli cleaned_data.csv

输出示例：

数据类型：工单数据
关键发现：
  * 待处理工单占比50%（异常高）
  * 某车型问题占比80%
  * 平均处理时长超过标准2倍
建议：优先处理该车型的积压工单

场景2：指定分析方向

用自然语言描述需求，AI 会：

• 理解抽象概念的业务含义
• 将其转化为具体指标
• 根据数据特征选择合适的分析方法
• 生成针对性的报告

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

AI 理解：

• 健康度 = 关闭率 + 处理效率 + 积压情况 + 响应及时性

AI 分析：

• 关闭率：75%（中等）
• 平均处理时长：48小时（偏长）
• 积压工单：50%（严重）
• 健康度评分：60/100（需改进）

场景3：使用模板

使用模板作为参考框架，AI 会：

• 理解模板的结构和要求
• 检查数据是否满足模板要求
• 如果数据缺少某些字段，灵活调整
• 按模板结构组织报告

python -m src.cli cleaned_data.csv -t templates/ticket_analysis.md

场景4：迭代深入分析

AI 能根据发现自主深入分析：

• 识别异常或关键发现
• 自主决定是否需要深入分析
• 动态调整分析计划
• 追踪问题的根因

系统架构

系统采用五阶段流水线架构，每个阶段都由 AI 驱动：

数据输入 → 数据理解 → 需求理解 → 分析规划 → 任务执行 → 报告生成

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             显示版本信息

配置说明

环境变量配置

在 .env 文件中配置以下参数：

# 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）：

{
  "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 智能画图

隐私保护

系统遵循严格的隐私保护原则：

• 数据访问限制：AI 不能直接访问原始数据
• 工具驱动：只能通过工具获取聚合结果
• 元数据优先：数据画像只包含元数据和统计摘要
• 本地处理：所有原始数据处理在本地完成，不上传到外部服务

性能指标

• 数据理解阶段：< 30秒
• 分析规划阶段：< 60秒
• 单个任务执行：< 120秒
• 完整分析流程：< 30分钟（取决于数据大小和任务数量）
• 支持最大 100万行数据

故障排除

问题1：找不到 OpenAI API 密钥

错误信息：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. 尝试使用更快的模型

开发和测试

运行测试

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

项目结构

.
├── 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             # 本文件

示例

查看 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。

致谢

感谢所有贡献者和使用者的支持！