From 3f0d2ef149f1c3f740ea2fb5b59dfecdca61d20d Mon Sep 17 00:00:00 2001
From: zhelisi <zhelisi2004@qq.com>
Date: Thu, 15 Jan 2026 08:54:44 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)

diff --git a/README.md b/README.md
index e69de29..1f3593c 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,139 @@
+# 项目名称
+
+> **机器学习 (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 的工具集（如接入客户历史交互数据），生成更个性化的留存建议。
\ No newline at end of file