G03-304/ml_course_design/README.md

# 客户流失预测系统

> **机器学习 (Python) 课程设计**

## 👥 团队成员

| 姓名 | 学号 | 贡献 |
|------|------|------|
| 黄迎 | 2311020109 | 数据处理、模型训练 |
| 龚士皓 | 2311020107 | Agent 开发、Streamlit |
| 金文磊 | 2311020110 | 测试、文档撰写 |

## 📋 项目概述

本项目是一个基于机器学习的电信客户流失预测系统，结合了智能Agent技术，能够通过自然语言交互和可视化界面提供客户流失风险预测服务。

### 项目目标

- 构建一个结构化数据集的分类/回归模型
- 实现一个能够理解自然语言的智能Agent
- 提供用户友好的可视化交互界面

### 技术栈

- **数据处理**: Polars + pandas
- **可视化**: Seaborn + Streamlit + Plotly
- **数据验证**: Pydantic + pandera
- **机器学习**: scikit-learn + LightGBM
- **智能Agent**: pydantic-ai
- **LLM服务**: DeepSeek

## 🚀 快速开始

### 1. 环境配置

#### 安装依赖

```bash
# 使用uv安装项目依赖
uv sync
```

#### 配置API Key

```bash
# 复制环境变量示例文件
cp .env.example .env

# 编辑.env文件，配置DeepSeek API Key
# DEEPSEEK_API_KEY="your-key-here"
```

### 2. 运行应用

#### 方式A: 运行Streamlit演示应用

```bash
uv run streamlit run src/streamlit_app.py
```

#### 方式B: 运行智能Agent演示

```bash
uv run python src/agent_app.py
```

#### 方式C: 运行模型训练脚本

```bash
uv run python src/train.py
```

### 3. 从任意目录运行（可选）

如果你想从项目根目录外运行应用，可以使用完整路径：

```bash
# 运行智能Agent演示
uv run python "path/to/ml_course_design/src/agent_app.py"

# 运行模型训练脚本
uv run python "path/to/ml_course_design/src/train.py"

# 运行Streamlit演示应用
uv run -C "path/to/ml_course_design" streamlit run src/streamlit_app.py
```

## 📊 数据说明

### 数据集

本项目使用了Kaggle上的**Telco Customer Churn**数据集，包含了7043名电信客户的信息和流失状态。

### 数据字段

- **客户信息**: 性别、年龄、是否有伴侣/家属、在网时长
- **服务信息**: 电话服务、互联网服务、在线安全、云备份等
- **合同信息**: 合同类型、支付方式、月费用、总费用
- **目标变量**: 是否流失(Churn)

### 数据预处理

- 使用Polars Lazy API进行高效数据处理
- 处理缺失值和异常值
- 特征编码和标准化

## 🧠 机器学习实现

### 模型架构

- **基准模型**: Logistic Regression
- **高级模型**: LightGBM

### 评估指标

| 模型 | 准确率 | 精确率 | 召回率 | F1分数 | ROC-AUC |
|------|--------|--------|--------|--------|---------|
| Logistic Regression | 0.8068 | 0.6600 | 0.5629 | 0.6076 | 0.8547 |
| LightGBM | 0.9723 | 0.9358 | 0.9616 | 0.9485 | 0.9951 |

### 特征重要性

影响客户流失的关键特征包括：
- 合同类型（月付客户流失风险更高）
- 在网时长（新客户流失风险更高）
- 月费用（高费用客户流失风险更高）
- 支付方式（电子支票支付客户流失风险更高）

## 🤖 Agent 实现

### 功能概述

智能Agent能够理解自然语言输入，提取客户信息，并提供流失风险预测和决策建议。

### 工具列表

| 工具名称 | 功能 | 输入 | 输出 |
|---------|------|------|------|
| `predict_churn` | 使用ML模型预测流失风险 | CustomerFeatures | float |
| `explain_churn` | 解释影响流失的关键因素 | CustomerFeatures | list[str] |

### 交互示例

**输入**: 
```
我有一个女性客户，35岁，在网2个月，月费用89.99，使用电子支票支付，采用月付合同
```

**输出**: 
```json
{
  "risk_score": 0.72,
  "decision": "高风险客户，建议重点关注",
  "actions": ["主动联系客户", "提供个性化优惠", "分析使用习惯"],
  "rationale": "月付合同、在网时长短和电子支票支付是导致高流失风险的主要因素"
}
```

## 🎨 Streamlit 应用

### 功能特点

- **直观的输入界面**: 分步填写客户信息
- **实时预测结果**: 立即显示流失风险评分
- **风险等级可视化**: 使用颜色和进度条直观展示风险
- **影响因素分析**: 提供详细的风险因素解释
- **数据统计展示**: 可视化展示不同特征与流失率的关系

### 使用方法

1. 在左侧边栏填写客户信息
2. 点击"预测流失风险"按钮
3. 在主界面查看预测结果和建议

## 📁 项目结构

```
ml_course_design/
├── pyproject.toml            # 项目依赖配置
├── .env.example              # 环境变量示例
├── .gitignore                # Git忽略规则
├── README.md                 # 项目说明文档
├── data/                     # 数据集目录
│   └── WA_Fn-UseC_-Telco-Customer-Churn.csv
├── models/                   # 模型保存目录
│   └── best_model_lr.joblib
├── src/                      # 源代码目录
│   ├── __init__.py
│   ├── data.py               # 数据处理模块
│   ├── features.py           # 特征定义模块
│   ├── train.py              # 模型训练模块
│   ├── infer.py              # 推理接口模块
│   ├── agent_app.py          # Agent应用
│   └── streamlit_app.py      # Streamlit应用
└── tests/                    # 测试目录
```

## 🔧 核心模块说明

### 1. 数据处理模块 (data.py)

```python
# 使用Polars Lazy API高效处理数据
lf = pl.scan_csv("data/train.csv")
result = (
    lf.filter(pl.col("age") > 30)
    .group_by("category")
    .agg(pl.col("value").mean())
    .collect()
)
```

### 2. 特征定义模块 (features.py)

```python
# 使用Pydantic定义特征模型
class CustomerFeatures(BaseModel):
    gender: gender_types
    SeniorCitizen: int = Field(ge=0, le=1)
    tenure: int = Field(ge=0, le=100)
    MonthlyCharges: float = Field(ge=0, le=200)
    # ... 其他特征
```

### 3. 模型训练模块 (train.py)

```python
# 创建预处理管道
preprocessor = ColumnTransformer([
    ('num', StandardScaler(), numeric_features),
    ('cat', OneHotEncoder(), categorical_features)
])

# 训练LightGBM模型
lgb_model = lgb.train(
    params,
    lgb_train,
    num_boost_round=500
)
```

### 4. 推理接口模块 (infer.py)

```python
# 单例预测
result = inferencer.predict_single(customer_features)

# 预测解释
result = inferencer.explain_prediction(customer_features)
```

## 📈 模型性能

### 训练集性能

| 模型 | 准确率 | 精确率 | 召回率 | F1分数 | ROC-AUC |
|------|--------|--------|--------|--------|---------|
| Logistic Regression | 0.8068 | 0.6600 | 0.5629 | 0.6076 | 0.8547 |
| LightGBM | 0.9723 | 0.9358 | 0.9616 | 0.9485 | 0.9951 |

### 测试集性能

| 模型 | 准确率 | 精确率 | 召回率 | F1分数 | ROC-AUC |
|------|--------|--------|--------|--------|---------|
| Logistic Regression | 0.7982 | 0.6364 | 0.5615 | 0.5966 | 0.8357 |

## 🎯 项目亮点

1. **高效数据处理**: 使用Polars Lazy API实现大规模数据的快速处理
2. **严格数据验证**: 结合Pydantic和pandera确保数据质量
3. **双模型架构**: 同时实现基准模型和高级模型，便于对比分析
4. **智能Agent交互**: 支持自然语言查询，提供人性化服务
5. **可视化界面**: 直观的Streamlit应用，降低使用门槛
6. **可解释性**: 提供详细的预测解释和影响因素分析

## 📝 开发日志

### Day 1: 项目初始化
- 完成项目结构搭建
- 配置开发环境
- 数据探索和分析

### Day 2: 数据处理
- 实现数据加载和预处理
- 特征工程
- 数据验证规则定义

### Day 3: 模型训练
- 实现Logistic Regression模型
- 实现LightGBM模型
- 模型评估和对比

### Day 4: Agent和应用开发
- 实现智能Agent
- 开发Streamlit应用
- 功能测试和优化

### Day 5: 项目完善
- 文档编写
- 代码优化
- 最终测试

## 4️⃣ 开发心得

### 4.1 主要困难与解决方案

在项目开发过程中，遇到的主要困难及其解决方案如下：

1. **模块导入问题**
   - **困难**：当从项目根目录外运行脚本时，Python无法找到`src`模块，出现`ModuleNotFoundError`
   - **解决方案**：在脚本中添加路径处理逻辑，自动将项目根目录添加到Python路径中，确保模块能够正确导入

2. **环境兼容性问题**
   - **困难**：用户使用的PowerShell 5不支持现代Shell语法（如`&&`命令分隔符）
   - **解决方案**：创建了基于Python的跨平台启动脚本，确保在不同环境下都能正常运行

3. **第三方库API变化**
   - **困难**：`pydantic_ai`库的API与预期不符（如`register_tool`方法不存在，需要使用`tool`方法；`run`方法需要改为`run_sync`）
   - **解决方案**：查阅库的帮助文档和源代码，调整代码以使用正确的API

4. **模型版本兼容性**
   - **困难**：加载模型时出现scikit-learn版本不兼容的警告
   - **解决方案**：确保训练和推理使用相同版本的库，并在文档中注明版本要求

### 4.2 对 AI 辅助编程的感受

使用AI辅助编程工具（如Trae IDE）的体验非常良好，主要体现在以下方面：

1. **有帮助的场景**
   - **快速生成代码框架**：能够根据需求快速生成项目结构和基础代码
   - **解决技术问题**：对于特定的技术问题，能够提供多种解决方案
   - **优化代码质量**：能够识别代码中的问题并提供改进建议
   - **学习新技术**：能够解释复杂的技术概念，帮助快速掌握新技术

2. **需要注意的地方**
   - **代码验证**：生成的代码可能存在细微错误，需要仔细验证和测试
   - **API准确性**：对于特定库的最新API可能不够了解，需要查阅官方文档确认
   - **业务逻辑**：复杂的业务逻辑需要结合人类的专业知识进行设计
   - **过度依赖**：避免过度依赖AI工具，保持独立思考和问题解决能力

### 4.3 局限与未来改进

如果有更多时间，项目还可以从以下几个方面进行改进：

1. **模型性能优化**
   - 尝试更多的特征工程方法，如特征选择、特征交叉等
   - 调参优化LightGBM模型，提高预测准确率
   - 尝试其他先进的算法，如XGBoost、CatBoost或深度学习模型

2. **应用功能扩展**
   - 添加更多的可视化图表，如客户流失风险分布、特征重要性分析等
   - 实现批量预测功能，支持导入Excel或CSV文件进行批量分析
   - 添加模型监控和更新机制，定期重新训练模型以适应新数据
   - 支持多语言界面，提高应用的可用性

3. **系统架构改进**
   - 分离前后端，使用FastAPI构建API，Streamlit作为前端
   - 实现模型服务化部署，支持RESTful API调用
   - 添加用户认证和权限管理，提高系统安全性
   - 支持多模型版本管理，方便模型迭代和回滚

4. **开发流程优化**
   - 添加更全面的单元测试和集成测试，提高代码质量
   - 实现CI/CD流水线，自动构建、测试和部署
   - 添加代码质量检查工具，如flake8、mypy等
   - 完善文档和注释，提高代码的可维护性

5. **用户体验改进**
   - 优化Streamlit界面，提高用户交互体验
   - 添加详细的使用说明和帮助文档
   - 提供更智能的用户输入提示和错误处理

通过这些改进，可以进一步提高项目的性能、可用性和可维护性，使其成为一个更完善的电信客户流失预测系统。