138 lines
5.2 KiB
Markdown
138 lines
5.2 KiB
Markdown
# 智能银行营销系统 (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/)
|