telco-customer-churn-prediction/README.md

# 项目名称

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

## 👥 团队成员

| 姓名 | 学号 | 贡献 |
|------|------|------|
|柘黎思 | 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 的工具集（如接入客户历史交互数据），生成更个性化的留存建议。