From 67e3361b04cbf971451e68e8a25b219d7e347a46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9E=97=E5=98=89=E7=83=A8?= <st2311511113@gitea.local>
Date: Fri, 16 Jan 2026 19:39:17 +0800
Subject: [PATCH] =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E6=96=87=E4=BB=B6=E8=87=B3?=
 =?UTF-8?q?=20/?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example |   1 +
 .gitignore   |  26 ++++++++++
 README.md    | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 164 insertions(+)
 create mode 100644 .env.example
 create mode 100644 .gitignore
 create mode 100644 README.md

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..8e61fc7
--- /dev/null
+++ b/.env.example
@@ -0,0 +1 @@
+DEEPSEEK_API_KEY=your-key-here
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d497164
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,26 @@
+# ===== 环境变量（绝对不能提交！）=====
+.env
+
+# ===== Python 虚拟环境 =====
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+
+# ===== IDE 配置 =====
+.vscode/
+.idea/
+*.swp
+
+# ===== macOS 系统文件 =====
+.DS_Store
+
+# ===== Jupyter =====
+.ipynb_checkpoints/
+
+# ===== 超大文件（超过 10MB 需手动添加）=====
+# 如果你的数据或模型文件超过 10MB，请在下面添加：
+# data/large_dataset.csv
+# models/large_model.pkl
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f508a07
--- /dev/null
+++ b/README.md
@@ -0,0 +1,137 @@
+# 智能银行营销系统 (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/)