From a6469b1790db51f99976d71f1fc0321028d7ca29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9E=97=E5=98=89=E7=83=A8?= Date: Fri, 16 Jan 2026 19:34:08 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 137 ------------------------------------------------------ 1 file changed, 137 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index f508a07..0000000 --- a/README.md +++ /dev/null @@ -1,137 +0,0 @@ -# 智能银行营销系统 (Smart Marketing System) - -> **机器学习 (Python) 课程设计** | Level 1：表格预测 + 行动建议闭环 - -## 👥 团队成员 - -| 姓名 | 学号 | 贡献 | -|------|------|------| -| 林嘉烨 | 2311511113 | 全栈开发 (Data, ML, Agent, Streamlit) | - -## 📝 项目简介 - -本项目旨在解决银行电话营销中的效率问题。利用 **Bank Marketing Dataset**，我们构建了一个**“预测 + 决策”**闭环系统。首先使用 **LightGBM** 预测客户购买定期存款的概率，然后通过 **Agent** 结合业务规则，自动生成针对不同意向客户的个性化营销策略（话术、渠道）。 - -**核心亮点：** -- ⚡ **高性能**：使用 Polars 进行数据处理，LightGBM 进行建模。 -- 🛡️ **高可靠**：使用 Pandera 进行数据契约验证，Pydantic 保证 Agent 输出结构化。 -- 🤖 **智能化**：Agent 不仅给分数，更给出可执行的行动清单。 - -## 🚀 快速开始 - -```bash -# 1. 进入项目目录 -cd ml_course_design - -# 2. 安装依赖 (推荐使用 uv，也可以直接 pip) -# pip install polars lightgbm pandera streamlit pydantic python-dotenv -# 或者如果使用 uv: -# uv sync - -# 3. 配置环境变量 -# 复制 .env.example 为 .env (Mock 模式下无需真实 Key) -cp .env.example .env - -# 4. 训练模型 (这一步会生成 models/model_artifacts.pkl) -# 注意：Windows 下请确保 PYTHONPATH 包含当前目录 -$env:PYTHONPATH="."; python src/train.py - -# 5. 运行 Agent Demo -python src/agent_app.py - -# 6. 启动 Streamlit 可视化界面 -streamlit run src/streamlit_app.py -``` - ---- - -## 1️⃣ 问题定义与数据 - -### 1.1 任务描述 -- **任务类型**：二分类 (Binary Classification) -- **目标**：预测客户是否会订阅定期存款 (term deposit)。 -- **业务价值**：精准定位高意向客户，减少对低意向客户的骚扰，提高营销 ROI。 - -### 1.2 数据来源 - -| 项目 | 说明 | -|------|------| -| 数据集名称 | Bank Marketing Dataset | -| 数据链接 | [UCI Machine Learning Repository](https://archive.ics.uci.edu/ml/datasets/Bank+Marketing) | -| 样本量 | 11,162 条 (bank.csv) | -| 特征数 | 16 个 (含 label) | - -### 1.3 数据切分与防泄漏 -- **切分策略**：80% 训练集，20% 测试集 (`train_test_split`, random_state=42)。 -- **防泄漏处理**：**移除 `duration` 字段**。该字段在执行电话营销前未知，且与结果高度相关（通话时间越长越可能成功），属于典型的“未来信息泄漏”。 - ---- - -## 2️⃣ 机器学习流水线 - -### 2.1 模型对比 - -| 模型 | F1-Score | ROC-AUC | 说明 | -|------|----------|---------|------| -| **Logistic Regression (Baseline)** | 0.6554 | 0.7329 | 简单线性模型，作为基准 | -| **LightGBM (Advanced)** | **0.6917** | **0.8030** | 梯度提升树，显著优于基线 | - -### 2.2 误差分析 -- LightGBM 在 AUC 上提升了约 **7个百分点**，说明其排序能力更强，更适合用于生成概率评分。 -- F1 分数受限于类别不平衡（deposit=yes 的样本较少），未来可尝试 SMOTE 或 Class Weight 优化。 - ---- - -## 3️⃣ Agent 实现 - -### 3.1 工具定义 - -| 工具名 | 功能 | 输入 | 输出 | -|--------|------|------|------| -| `predict_risk` | 调用 ML 模型预测购买概率 | `CustomerFeatures` (Pydantic) | `dict` (score, top_features) | -| `get_strategy` | 规则引擎检索营销策略 | `float` (score) | `dict` (segment, action, templates) | - -### 3.2 决策流程 -1. **感知 (Perception)**: Agent 接收客户画像，调用 `predict_risk` 获取购买概率。 -2. **规划 (Planning)**: 根据概率调用 `get_strategy` 匹配对应的客户分群和营销渠道。 -3. **行动 (Action)**: 整合信息，输出 `Decision` 对象，包含具体的行动清单（话术、渠道）。 - -### 3.3 案例展示 - -**输入**： -> 35岁, 管理层(management), 余额 2000, 以前没有参加过活动 - -**输出 (JSON)**： -```json -{ - "risk_score": 0.4524, - "customer_segment": "潜在客户", - "decision": "建议采取 自动化营销", - "actions": [ - "使用话术: 你好，近期理财活动...", - "使用话术: 点击领取加息券" - ], - "rationale": "模型预测概率为 45.2%，属于潜在客户。该群体对自动化营销转化率较高。" -} -``` - ---- - -## 4️⃣ 开发心得 - -### 4.1 主要困难与解决方案 -- **数据泄露识别**：一开始模型准确率异常高（接近100%），排查发现是 `duration` 导致的。解决方案是果断移除该特征。 -- **环境配置**：Windows 下 Python 路径问题导致模块导入失败。解决方案是通过 `$env:PYTHONPATH` 显式指定路径。 - -### 4.2 对 AI 辅助编程的感受 -- AI 在生成样板代码（如 Pydantic 模型定义、Streamlit UI 布局）方面效率极高。 -- 对于复杂的业务逻辑（如 Agent 的决策树设计），仍需人工介入进行微调和规则定义。 - ---- - -## 参考资料 - -- [LightGBM Documentation](https://lightgbm.readthedocs.io/) -- [Polars User Guide](https://pola.rs/) -- [Pydantic Documentation](https://docs.pydantic.dev/) -- [Streamlit Documentation](https://docs.streamlit.io/)