generated from Python-2026Spring/assignment-05-final-project-template
139 lines
5.1 KiB
Markdown
139 lines
5.1 KiB
Markdown
# 项目名称
|
||
|
||
>电信客户流失预测系统
|
||
|
||
## 👥 团队成员
|
||
|
||
| 姓名 | 学号 | 贡献 |
|
||
|------|------|------|
|
||
|柘黎思 | 2211020146 | 数据处理、模型训练,Agent 开发、Streamlit,测试、文档撰写 |
|
||
|
||
## 📝 项目简介
|
||
|
||
## 项目简介
|
||
本项目聚焦电信行业的客户流失问题，目标是通过机器学习模型预测客户的流失风险，并基于预测结果生成可落地的留存建议。
|
||
|
||
项目选用公开的电信客户数据集（包含7043条客户记录、19个特征），覆盖客户的合约类型、消费金额、服务开通情况等信息，最终解决“如何提前识别高流失风险客户并针对性挽留”的业务痛点。
|
||
|
||
## 🚀 快速开始
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone http://hblu.top:3000/zhelisi/telco-customer-churn-prediction.git
|
||
cd telco-customer-churn-prediction
|
||
|
||
# 安装依赖
|
||
uv sync
|
||
|
||
# 运行 Demo
|
||
uv run streamlit run app.py
|
||
|
||
---
|
||
|
||
## 1️⃣ 问题定义与数据
|
||
|
||
### 1.1 任务描述
|
||
|
||
预测任务类型：二分类任务（预测客户 “是否会流失”）。
|
||
业务目标：通过客户属性识别高流失风险群体，输出可落地的留存建议，帮助电信企业降低客户流失率。
|
||
|
||
### 1.2 数据来源
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 数据集名称 |电信客户流失数据集（Telco Customer Churn Dataset） |
|
||
| 数据链接 |已内置到项目仓库，路径：data/telco_churn.csv |
|
||
| 样本量 | 7,043 条 |
|
||
| 特征数 | 19 个（含客户属性、消费信息、服务开通情况等）|
|
||
|
||
### 1.3 数据切分与防泄漏
|
||
|
||
数据切分：按 7:3 比例将数据集随机切分为训练集与测试集，固定随机种子 random_state=42 保证结果可复现；未单独划分验证集，训练过程中使用模型内置的交叉验证（RandomForest 的cv参数）。
|
||
防泄漏措施：
|
||
所有特征工程（如缺失值填充、编码）仅在训练集上拟合，再应用到测试集；
|
||
模型训练过程中未使用测试集的任何信息，避免数据泄漏。
|
||
|
||
## 2️⃣ 机器学习流水线
|
||
|
||
### 2.1 基线模型
|
||
|
||
| 模型 | 指标 | 结果 |
|
||
|Logistic Regression|ROC-AUC|0.78|
|
||
|-------------------|准确率|0.78|
|
||
|--------- ---------|F1-score|0.65|
|
||
|
||
|
||
### 2.2 进阶模型
|
||
|
||
| 模型 | 指标 | 结果 |
|
||
|------|------|------|
|
||
|随机森林（Random Forest）|ROC-AUC|0.86 |
|
||
|------------------------|准确率|0.85|
|
||
|------------------------|F1-score|0.76|
|
||
|
||
### 2.3 误差分析
|
||
误差分析
|
||
表现不佳的样本特征：高月消费 + 月付合约 + 在网时长 < 3 个月的客户（实际流失但模型预测为 “不流失”）。
|
||
原因：
|
||
这类客户的特征组合在训练集中占比少，模型学习不足；
|
||
“月付合约” 与 “高月消费” 的特征关联度在训练集中未充分体现，导致模型对该群体的风险识别能力弱。
|
||
|
||
|
||
## 3️⃣ Agent 实现
|
||
|
||
### 3.1 工具定义
|
||
|
||
| 工具名 | 功能 | 输入 | 输出 |
|
||
|--------|------|------|------|
|
||
| predict_risk| 调用随机森林模型预测客户流失概率| CustomerFeatures（客户特征字典） | float |
|
||
|explain_features|输出影响该客户流失的关键特征| CustomerFeatures（客户特征字典） | list [str]（关键特征列表，如 ["MonthlyCharges", "Contract"]） |
|
||
|
||
### 3.2 决策流程
|
||
|
||
Agent 的决策流程为 “预测→解释→建议” 三步：
|
||
1.调用predict_risk工具：输入客户特征，获取流失概率；
|
||
2.调用explain_features工具：基于同一特征，获取影响流失的关键特征；
|
||
3.生成决策结果：结合流失概率（如≥0.7 判定为高风险）与关键特征，输出对应的留存建议。
|
||
|
||
### 3.3 案例展示
|
||
|
||
**输入**：
|
||
```
|
||
请分析这位客户的流失风险：年龄 35，在网时长 2 个月，月消费 89.99，合约类型 月付
|
||
```
|
||
|
||
**输出**：
|
||
```json
|
||
{
|
||
"risk_score": 0.72,
|
||
"decision": "高风险，建议主动挽留",
|
||
"actions": ["发送1年合约立减50元优惠短信", "专属客服1对1回访"],
|
||
"rationale": "该客户属于“在网时长<3个月+月付合约+高月消费”群体，是流失高风险特征组合"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4️⃣ 开发心得
|
||
|
||
### 4.1 主要困难与解决方案
|
||
|
||
最大困难：跨机运行时出现 “文件找不到” 错误（如app.py未上传仓库、路径使用绝对路径）。
|
||
解决方案：
|
||
确保所有核心文件（app.py、数据、模型）上传至仓库；
|
||
改用Path(__file__).parent获取相对路径，避免依赖本地绝对路径。
|
||
|
||
### 4.2 对 AI 辅助编程的感受
|
||
|
||
体验：效率提升明显，能快速解决语法、工具使用（如uv依赖管理）等问题。
|
||
帮助场景：
|
||
1.编写README.md的结构化内容；
|
||
2.排查跨机运行的错误（如终端命令、路径问题）。
|
||
注意点：AI 给出的代码可能存在 “本地适配性” 问题（如 Windows/Linux 命令差异），需要结合实际环境验证。
|
||
|
||
### 4.3 局限与未来改进
|
||
|
||
当前局限：模型对 “高月消费 + 月付合约” 的样本识别精度不足；Agent 的建议多样性有限。
|
||
未来改进：
|
||
1.针对高风险样本增加特征工程（如计算 “月消费 / 在网时长” 比值）；
|
||
2.扩展 Agent 的工具集（如接入客户历史交互数据），生成更个性化的留存建议。 |