213 lines
6.3 KiB
Markdown
213 lines
6.3 KiB
Markdown
# 电信客户流失预测系统
|
||
|
||
> **机器学习 (Python) 课程设计**
|
||
|
||
## 👥 团队成员
|
||
|
||
| 姓名 | 学号 | 贡献 |
|
||
|------|------|------|
|
||
| 陈思坤 | 2311020204 | 数据处理、模型训练 |
|
||
| （请填写） | （请填写） | Agent 开发、Streamlit |
|
||
| （请填写） | （请填写） | 测试、文档撰写 |
|
||
|
||
## 📝 项目简介
|
||
|
||
本项目基于 Telco Customer Churn 数据集，构建了一个完整的客户流失预测与挽留建议系统。系统包含三个核心能力：
|
||
|
||
1. **传统机器学习**：使用 LightGBM 模型预测客户流失概率
|
||
2. **LLM 集成**：使用 DeepSeek 生成个性化挽留建议
|
||
3. **Agent 工具调用**：通过 pydantic-ai 实现 ML 预测 + 风险分析的工具链
|
||
|
||
## 🚀 快速开始
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone http://hblu.top:3000/MachineLearning2025/GXX-TelcoChurn.git
|
||
cd GXX-TelcoChurn
|
||
|
||
# 安装依赖
|
||
uv sync
|
||
|
||
# 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 填入 API Key
|
||
|
||
# 训练模型
|
||
uv run python src/train.py
|
||
|
||
# 运行 Demo
|
||
uv run streamlit run src/streamlit_app.py
|
||
```
|
||
|
||
---
|
||
|
||
## 1️⃣ 问题定义与数据
|
||
|
||
### 1.1 任务描述
|
||
|
||
- **任务类型**：二分类
|
||
- **业务目标**：预测电信客户是否会流失，并给出针对性的挽留建议
|
||
- **输入**：客户基本信息、服务订阅情况、账户信息
|
||
- **输出**：流失概率、风险等级、挽留行动计划
|
||
|
||
### 1.2 数据来源
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 数据集名称 | Telco Customer Churn |
|
||
| 数据链接 | [Kaggle](https://www.kaggle.com/datasets/blastchar/telco-customer-churn) |
|
||
| 样本量 | 7,043 条 |
|
||
| 特征数 | 20 个 |
|
||
| 流失率 | ~26.5% |
|
||
|
||
### 1.3 数据切分与防泄漏
|
||
|
||
- **切分策略**：80% 训练集，20% 测试集
|
||
- **分层采样**：使用 `stratify=y` 确保训练集和测试集的流失率一致
|
||
- **随机种子**：固定 `random_state=42` 确保可复现
|
||
- **防泄漏措施**：
|
||
- 不使用 customerID 作为特征
|
||
- TotalCharges 与 tenure 存在相关性，但保留两者因为业务含义不同
|
||
- 所有特征工程在训练集上拟合，在测试集上转换
|
||
|
||
---
|
||
|
||
## 2️⃣ 机器学习流水线
|
||
|
||
### 2.1 数据预处理
|
||
|
||
使用 Polars 进行高性能数据处理：
|
||
|
||
```python
|
||
# 使用 Polars Lazy API
|
||
df = pl.read_csv("data/WA_Fn-UseC_-Telco-Customer-Churn.csv")
|
||
df_clean = preprocess_data(df) # 删除缺失值、转换类型
|
||
```
|
||
|
||
使用 Pandera 进行 Schema 校验：
|
||
|
||
```python
|
||
class CleanTelcoSchema(pa.DataFrameModel):
|
||
tenure: int = pa.Field(ge=0, nullable=False)
|
||
MonthlyCharges: float = pa.Field(ge=0, nullable=False)
|
||
Churn: int = pa.Field(isin=[0, 1], nullable=False)
|
||
```
|
||
|
||
### 2.2 基线模型
|
||
|
||
| 模型 | F1 Score | ROC-AUC |
|
||
|------|----------|---------|
|
||
| Logistic Regression | ~0.58 | ~0.84 |
|
||
|
||
### 2.3 进阶模型
|
||
|
||
| 模型 | F1 Score | ROC-AUC |
|
||
|------|----------|---------|
|
||
| LightGBM | ~0.60 | ~0.85 |
|
||
|
||
### 2.4 误差分析
|
||
|
||
模型在以下样本上表现不佳：
|
||
|
||
1. **边界客户**：流失概率在 0.4-0.6 之间的客户，模型难以准确判断
|
||
2. **长期客户突然流失**：任期较长但突然流失的客户，可能受到外部因素影响
|
||
3. **低费用客户**：月费较低的客户，特征区分度不够
|
||
|
||
**改进方向**：
|
||
- 引入更多行为特征（如投诉记录、服务使用频率）
|
||
- 考虑时序特征（如近期费用变化趋势）
|
||
|
||
---
|
||
|
||
## 3️⃣ Agent 实现
|
||
|
||
### 3.1 工具定义
|
||
|
||
| 工具名 | 功能 | 输入 | 输出 |
|
||
|--------|------|------|------|
|
||
| `predict_churn_probability` | 调用 ML 模型预测流失概率 | CustomerFeatures | float |
|
||
| `get_model_explanation` | 获取模型特征重要性 | - | str |
|
||
| `analyze_risk_factors` | 分析客户具体风险因素 | CustomerFeatures | list[str] |
|
||
|
||
### 3.2 决策流程
|
||
|
||
```
|
||
用户输入客户信息
|
||
↓
|
||
Agent 调用 predict_churn_probability → 获取流失概率
|
||
↓
|
||
Agent 调用 get_model_explanation → 获取特征重要性
|
||
↓
|
||
Agent 调用 analyze_risk_factors → 获取具体风险因素
|
||
↓
|
||
Agent 生成结构化输出 (ChurnPrediction)
|
||
↓
|
||
返回：流失概率 + 风险等级 + 关键因素 + 行动计划 + 依据说明
|
||
```
|
||
|
||
### 3.3 案例展示
|
||
|
||
**输入**：
|
||
```
|
||
客户信息：任期 2 个月，月费 $89.99，月付合同，光纤服务，电子支票支付
|
||
```
|
||
|
||
**输出**：
|
||
```json
|
||
{
|
||
"churn_probability": 0.82,
|
||
"risk_level": "高风险",
|
||
"key_factors": [
|
||
"新客户（任期仅2个月），流失风险较高",
|
||
"月付合同，无长期绑定，容易流失",
|
||
"使用电子支票支付，该支付方式用户流失率最高"
|
||
],
|
||
"action_plan": [
|
||
{"action": "提供首年合同升级优惠（8折）", "priority": "高"},
|
||
{"action": "赠送 3 个月在线安全服务", "priority": "高"},
|
||
{"action": "引导切换为自动银行转账支付", "priority": "中"}
|
||
],
|
||
"rationale": "该客户为新客户且使用月付合同，根据模型分析，合同类型和客户任期是最重要的流失预测因素..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4️⃣ 开发心得
|
||
|
||
### 4.1 主要困难与解决方案
|
||
|
||
1. **数据类型处理**：TotalCharges 字段在原始数据中是字符串，包含空值
|
||
- 解决：使用 Polars 的条件表达式处理空字符串
|
||
|
||
2. **类别不平衡**：流失客户仅占 26.5%
|
||
- 解决：使用 `class_weight="balanced"` 参数
|
||
|
||
3. **Agent 输出稳定性**：LLM 有时不按要求调用工具
|
||
- 解决：在 instructions 中明确规定必须调用的工具顺序
|
||
|
||
### 4.2 对 AI 辅助编程的感受
|
||
|
||
- **有帮助的场景**：代码框架搭建、API 文档查询、错误调试
|
||
- **需要注意的地方**：AI 生成的代码需要仔细审查，特别是边界条件处理
|
||
|
||
### 4.3 局限与未来改进
|
||
|
||
1. 可以引入更多特征（如客户投诉记录、服务使用频率）
|
||
2. 可以实现阈值策略，针对不同风险等级采取不同挽留措施
|
||
3. 可以添加相似案例检索功能，提供历史成功挽留案例参考
|
||
|
||
---
|
||
|
||
## 📋 Checklist（提交前自检）
|
||
|
||
- [x] 使用 `uv sync` 安装依赖，无需手动创建虚拟环境
|
||
- [x] `.gitignore` 包含 `.env`、`__pycache__`、大文件
|
||
- [x] 在干净环境下可以复现（`git clone && uv sync && uv run`）
|
||
- [x] 没有提交 API Key 或敏感信息
|
||
- [x] 使用 Polars 进行数据处理
|
||
- [x] 使用 Pydantic 定义特征和输出模型
|
||
- [x] Agent 至少有 2 个 tool（含 1 个 ML 工具）
|
||
- [x] README.md 说明了数据切分策略
|
||
- [x] Demo 可以正常运行
|