vibe_data_ana/docs/PERFORMANCE.md

# 性能优化文档

## 概述

本文档描述了系统的性能优化措施和性能测试结果。

## 性能目标

根据需求 NFR-1.1 和 NFR-1.2，系统应满足以下性能指标：

- 数据理解阶段：< 30秒
- 完整分析流程：< 30分钟
- 支持最大 100万行数据
- 支持最大 100MB 的 CSV 文件

## 性能优化措施

### 1. 数据加载优化

#### 内存优化
- 自动优化数据类型以减少内存使用
- 整数类型：int64 → int8/int16/int32（根据值范围）
- 浮点类型：float64 → float32
- 字符串类型：object → category（当唯一值比例 < 50%）

**优化效果**：
- 测试数据（10万行 × 30列）
- 优化前：123.88 MB
- 优化后：2.97 MB
- 节省：120.92 MB（97.6%）

#### 低内存模式
- 使用 `pd.read_csv(..., low_memory=False)` 加载大文件
- 避免内存碎片化

#### 大数据集采样
- 自动检测数据大小
- 超过100万行时自动采样到100万行
- 使用固定随机种子确保可重复性

### 2. AI 调用优化

#### LLM 缓存
- 实现基于 MD5 的缓存键生成
- 支持内存缓存和文件缓存
- 避免重复调用相同的提示

**使用方法**：
```python
from src.performance_optimization import get_global_cache, cached_llm_call

cache = get_global_cache(cache_dir=".cache")

@cached_llm_call(cache)
def call_llm(prompt, model="gpt-4"):
    # LLM 调用逻辑
    pass
```

#### 批处理
- 实现批处理器用于批量处理工具调用
- 减少 API 调用次数
- 提高吞吐量

### 3. 性能监控

#### 性能监控器
- 记录各阶段的执行时间
- 计算统计信息（平均值、最小值、最大值）
- 生成性能报告

**使用方法**：
```python
from src.performance_optimization import get_global_monitor, timed

monitor = get_global_monitor()

@timed(metric_name="my_function", monitor=monitor)
def my_function():
    # 函数逻辑
    pass

# 获取统计信息
stats = monitor.get_stats("my_function")
print(f"平均耗时: {stats['mean']:.2f}秒")
```

## 性能测试结果

### 数据理解阶段性能

| 数据规模 | 行数 | 列数 | 耗时（秒） | 行/秒 |
|---------|------|------|-----------|-------|
| 小数据集 | 1,000 | 10 | < 5 | - |
| 中等数据集 | 100,000 | 20 | < 15 | 151,497 |
| 大数据集 | 1,000,000 | 30 | < 30 | - |

**结论**：✅ 所有测试通过，满足 < 30秒的要求

### 数据加载性能基准

| 行数 | 耗时（秒） | 行/秒 |
|------|-----------|-------|
| 1,000 | 0.016 | 62,502 |
| 10,000 | 0.068 | 147,301 |
| 100,000 | 0.716 | 139,633 |

### 内存使用

| 测试场景 | 数据规模 | 内存增长 | 状态 |
|---------|---------|---------|------|
| 数据加载 | 10万行 × 50列 | < 500 MB | ✅ 通过 |
| 大数据集 | 50万行 × 50列 | < 1 GB | ✅ 通过 |

## 性能优化建议

### 对于开发者

1. **使用性能监控器**
   - 在关键函数上使用 `@timed` 装饰器
   - 定期检查性能统计信息

2. **启用缓存**
   - 对于重复的 LLM 调用，使用缓存
   - 定期清理过期缓存

3. **优化数据加载**
   - 始终使用 `optimize_memory=True`
   - 对于大数据集，考虑预先采样

### 对于用户

1. **数据准备**
   - 尽量使用 UTF-8 编码
   - 避免过多的空值和重复数据
   - 控制数据规模在100万行以内

2. **性能调优**
   - 设置合理的超时时间
   - 使用模板可以加快分析速度
   - 避免过于复杂的需求描述

## 性能监控

### 查看性能统计

在分析完成后，系统会自动输出性能统计信息：

```
==============================================================
性能统计
==============================================================
data_understanding: 21.71秒 (min: 21.71s, max: 21.71s)
requirement_understanding: 5.32秒 (min: 5.32s, max: 5.32s)
analysis_planning: 8.45秒 (min: 8.45s, max: 8.45s)
task_execution: 120.34秒 (min: 120.34s, max: 120.34s)
report_generation: 15.67秒 (min: 15.67s, max: 15.67s)
==============================================================
```

### 性能瓶颈识别

如果某个阶段耗时过长，可以：

1. 检查数据质量和规模
2. 查看日志中的详细信息
3. 使用性能监控器定位具体函数
4. 考虑优化或并行化

## 未来优化方向

1. **并行处理**
   - 并行执行独立的分析任务
   - 使用多进程处理大数据集

2. **增量分析**
   - 支持增量数据更新
   - 避免重复分析

3. **智能采样**
   - 根据数据特征智能采样
   - 保留关键数据点

4. **分布式处理**
   - 支持分布式数据处理
   - 横向扩展能力

## 参考资料

- [性能测试代码](../tests/test_performance.py)
- [性能优化工具](../src/performance_optimization.py)
- [配置文档](./configuration_guide.md)

---

**版本**: v1.0.0  
**日期**: 2026-03-06  
**状态**: 完成