智能银行营销系统 (Smart Marketing System)

机器学习 (Python) 课程设计 | Level 1：表格预测 + 行动建议闭环

👥 团队成员

姓名	学号	贡献
林嘉烨	2311511113	全栈开发 (Data, ML, Agent, Streamlit)

📝 项目简介

本项目旨在解决银行电话营销中的效率问题。利用 Bank Marketing Dataset，我们构建了一个**“预测 + 决策”**闭环系统。首先使用 LightGBM 预测客户购买定期存款的概率，然后通过 Agent 结合业务规则，自动生成针对不同意向客户的个性化营销策略（话术、渠道）。

核心亮点：

• ⚡ 高性能：使用 Polars 进行数据处理，LightGBM 进行建模。
• 🛡️ 高可靠：使用 Pandera 进行数据契约验证，Pydantic 保证 Agent 输出结构化。
• 🤖 智能化：Agent 不仅给分数，更给出可执行的行动清单。

🚀 快速开始

# 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
样本量	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)：

{
  "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
• Polars User Guide
• Pydantic Documentation
• Streamlit Documentation