CourseDesignTemplate/示例项目-AI数据分析师/README.md

# 📊 AI 数据分析师

一个基于 DeepSeek API + Streamlit 的智能数据分析平台，上传 CSV 数据即可获得 AI 驱动的深度洞察和可视化报告。

![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![Streamlit](https://img.shields.io/badge/Streamlit-1.28+-red.svg)
![DeepSeek](https://img.shields.io/badge/DeepSeek-API-green.svg)
![Difficulty](https://img.shields.io/badge/难度-⭐⭐⭐⭐-orange.svg)

## ✨ 功能特性

| 功能 | 描述 |
|:---|:---|
| 📈 **数据预览** | 数据表格展示、统计摘要、列信息分析 |
| 📊 **智能可视化** | 根据数据类型自动生成直方图、散点图、箱线图、热力图 |
| 🤖 **AI 深度分析** | 综合分析、相关性分析、异常检测三种模式 |
| 💬 **自然语言问答** | 用中文直接询问关于数据的任何问题 |
| 📝 **报告生成** | 一键生成完整的 Markdown 格式分析报告并下载 |

## 🖼️ 界面预览

```
┌────────────────────────────────────────────────────────────────────┐
│  📊 AI 数据分析师                                                   │
│  上传数据，让 AI 帮你发现数据中的故事                                 │
├────────────────────────────────────────────────────────────────────┤
│ [📈 数据预览] [📊 智能可视化] [🤖 AI 分析] [💬 数据问答] [📝 生成报告] │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐                           │
│  │  100 │  │   7  │  │   0  │  │   5  │                           │
│  │ 数据行 │  │ 数据列 │  │ 缺失值 │  │ 数值列 │                           │
│  └──────┘  └──────┘  └──────┘  └──────┘                           │
│                                                                    │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │ 姓名   │ 部门   │ 年龄 │ 工龄 │ 月薪  │ 绩效评分 │ 满意度 │  │
│  │ 张三   │ 技术部 │  28  │  3   │ 15000 │  85.5   │  4.2   │  │
│  │ 李四   │ 市场部 │  32  │  5   │ 18000 │  78.3   │  3.8   │  │
│  │ ...    │ ...    │ ...  │ ...  │ ...   │  ...    │  ...   │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘
```

## 🚀 快速开始

### 1. 进入项目目录

```bash
cd 示例项目-AI数据分析师
```

### 2. 创建虚拟环境（推荐）

```bash
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置 API Key

创建 `.env` 文件：

```bash
echo "DEEPSEEK_API_KEY=sk-your-api-key" > .env
```

或直接在应用界面的侧边栏输入 API Key。

### 5. 运行应用

```bash
streamlit run app.py
```

浏览器会自动打开 http://localhost:8501

## 📁 项目结构

```
示例项目-AI数据分析师/
├── app.py              # 主程序 (~600行)
├── requirements.txt    # 项目依赖
├── sample_data.csv     # 示例数据（员工信息）
├── .env                # 环境变量（需自行创建）
├── .gitignore          # Git 忽略文件
└── README.md           # 项目说明
```

## 🛠️ 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                      Streamlit UI                        │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │数据预览 │ │智能可视化│ │ AI分析  │ │数据问答 │        │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘       │
│       │           │           │           │             │
├───────┼───────────┼───────────┼───────────┼─────────────┤
│       ▼           ▼           ▼           ▼             │
│  ┌─────────────────────────────────────────────────┐   │
│  │              Pandas DataFrame                    │   │
│  │         (数据处理与统计分析)                      │   │
│  └─────────────────────────────────────────────────┘   │
│       │           │                                     │
│       ▼           ▼                                     │
│  ┌─────────┐ ┌─────────────────────────────────────┐   │
│  │ Altair  │ │          DeepSeek API               │   │
│  │ (可视化)│ │  (AI 分析 / 问答 / 报告生成)         │   │
│  └─────────┘ └─────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

## 🔑 核心技术点

### 1. 数据处理与摘要生成

```python
def get_data_summary(df: pd.DataFrame) -> str:
    """生成数据摘要供 AI 分析"""
    summary = []
    
    # 基本信息
    summary.append(f"数据集包含 {len(df)} 行和 {len(df.columns)} 列。")
    
    # 数值列统计
    numeric_cols = df.select_dtypes(include=['number']).columns
    stats = df[numeric_cols].describe().to_string()
    
    # ... 更多统计信息
    return "\n".join(summary)
```

### 2. AI 分析的 Prompt 工程

```python
def analyze_with_ai(client, data_summary, analysis_type):
    prompts = {
        "general": """你是一个专业的数据分析师...
请从以下几个方面进行分析：
1. 📊 数据概况
2. 🔍 关键发现
3. 📈 建议可视化
4. ⚠️ 注意事项
5. 💡 进一步分析建议""",
        
        "correlation": """分析变量之间的相关性...""",
        "anomaly": """检测数据中的异常值..."""
    }
    
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=[
            {"role": "system", "content": prompts[analysis_type]},
            {"role": "user", "content": f"数据摘要：\n{data_summary}"}
        ]
    )
    return response.choices[0].message.content
```

### 3. 自动可视化生成

```python
def create_visualizations(df):
    """根据数据类型自动选择合适的图表"""
    charts = []
    numeric_cols = df.select_dtypes(include=['number']).columns
    cat_cols = df.select_dtypes(include=['object']).columns
    
    # 数值分布 -> 直方图
    if numeric_cols:
        hist_chart = alt.Chart(df).mark_bar().encode(
            x=alt.X(f'{col}:Q', bin=True),
            y='count()'
        )
        charts.append(hist_chart)
    
    # 多数值变量 -> 散点图 + 相关性热力图
    # 分类+数值 -> 箱线图
    # ...
    
    return charts
```

### 4. 多轮对话的上下文管理

```python
def ask_data_question(client, data_summary, question, chat_history):
    messages = [
        {"role": "system", "content": "你是数据分析助手..."},
        {"role": "user", "content": f"数据摘要：\n{data_summary}"},
        {"role": "assistant", "content": "我已了解数据，请问您想知道什么？"}
    ]
    
    # 添加历史对话
    for msg in chat_history:
        messages.append(msg)
    
    # 添加当前问题
    messages.append({"role": "user", "content": question})
    
    return client.chat.completions.create(
        model="deepseek-chat",
        messages=messages
    )
```

### 5. Session State 管理

```python
# 初始化状态
if "df" not in st.session_state:
    st.session_state.df = None
if "analyses" not in st.session_state:
    st.session_state.analyses = {}
if "qa_history" not in st.session_state:
    st.session_state.qa_history = []

# 跨 Tab 共享数据
df = st.session_state.df
```

## 📊 使用的 Streamlit 组件

| 组件 | 用途 |
|:---|:---|
| `st.tabs` | 多标签页布局 |
| `st.columns` | 统计卡片布局 |
| `st.file_uploader` | CSV 文件上传 |
| `st.dataframe` | 交互式数据表格 |
| `st.altair_chart` | Altair 图表渲染 |
| `st.chat_message` | 问答对话界面 |
| `st.chat_input` | 聊天输入框 |
| `st.session_state` | 状态管理 |
| `st.download_button` | 报告下载 |
| `st.spinner` | 加载动画 |
| `st.expander` | 可折叠区域 |

## 🎨 Vibe Coding 开发过程

### 初始 Prompt

> "帮我创建一个 AI 数据分析师应用，使用 DeepSeek API 和 Streamlit。
> 
> 功能需求：
> 1. 上传 CSV 文件，显示数据预览和统计
> 2. 自动根据数据类型生成可视化图表（用 Altair）
> 3. AI 分析功能：综合分析、相关性分析、异常检测
> 4. 自然语言问答，可以问关于数据的问题
> 5. 生成 Markdown 格式的分析报告
> 
> 技术要求：
> - 使用 st.tabs 做多标签页布局
> - 使用 st.session_state 管理状态
> - 界面要美观，使用自定义 CSS"

### 迭代优化

```
Prompt 1: "给数据预览页添加统计卡片，显示行数、列数、缺失值等"

Prompt 2: "让可视化更智能，根据数据类型自动选择图表类型"

Prompt 3: "问答功能要支持多轮对话，AI 要记住之前的问题"

Prompt 4: "报告生成功能要把之前的分析结果都整合进去"

Prompt 5: "加一个示例数据选项，方便没有数据的用户体验"
```

## 🔧 扩展建议

如果你想进一步完善这个项目，可以考虑：

1. **支持更多文件格式**：Excel、JSON、Parquet
2. **添加数据清洗功能**：缺失值处理、异常值处理
3. **更丰富的可视化**：时间序列图、地理图
4. **导出更多格式**：PDF、HTML、Word
5. **添加数据筛选器**：让用户选择分析哪些列/行
6. **机器学习预测**：简单的回归/分类预测功能

## ⚠️ 注意事项

1. **数据大小**：大数据集（>10万行）可能导致界面卡顿
2. **API 成本**：长文本分析和多轮问答会消耗更多 Token
3. **隐私安全**：敏感数据请在本地使用，不要上传到公共服务器
4. **API Key 安全**：不要将 `.env` 提交到代码仓库

## 📚 参考资料

- [Streamlit 官方文档](https://docs.streamlit.io)
- [Altair 可视化文档](https://altair-viz.github.io)
- [Pandas 数据分析](https://pandas.pydata.org/docs/)
- [DeepSeek API 文档](https://platform.deepseek.com/api-docs)

## 👤 作者

Python 程序设计课程设计 - 高级示例项目

---

**让数据说话，用 AI 倾听！** 📊🤖