From 91136fdce4116433b2ab45ebc150cd7d585144c2 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:26:34 +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 | 1012 +++++++------------------------------------------- 3 files changed, 164 insertions(+), 875 deletions(-) create mode 100644 .env.example create mode 100644 .gitignore 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 index ae0c7de..4d6f4f0 100644 --- a/README.md +++ b/README.md @@ -1,875 +1,137 @@ -# 机器学习 × LLM × Agent：课程设计（5 天） - -> **小组作业** | 2–3 人/组 | 构建一个「可落地的智能预测与行动建议系统」 - -用传统机器学习完成可量化的预测任务，再用 LLM + Agent 把预测结果变成可执行的决策/建议，并保证输出结构化、可追溯、可复现。 - ---- - -## 📅 课程安排概览 - -| 天数 | 主题 | 内容 | -|------|------|------| -| **Day 1** | 项目启动 | 技术栈介绍 + 演示 + 选题分组 | -| **Day 2** | 自主设计 | 分组开发 | -| **Day 3** | 答疑 + Git 指导 | 集中答疑 + Git 提交教学 | -| **Day 4** | 自主设计 | 继续开发 + 准备展示 | -| **Day 5** | 小组展示 | 教师机运行 + 评分 | - ---- - -## 📑 目录 - -- [Day 1：项目启动](#day-1项目启动) - - [快速开始](#-快速开始) - - [技术栈要求](#技术栈要求2026-版) - - [选题指南](#选题指南) - - [可选扩展思路](#可选扩展思路) -- [Day 2：自主设计](#day-2自主设计) -- [Day 3：答疑 + Git 指导](#day-3答疑--git-指导) - - [Git 安装](#git-安装国内环境) - - [Git 基础操作](#git-基础操作) - - [.gitignore 详解](#gitignore-详解) -- [Day 4：自主设计](#day-4自主设计) -- [Day 5：小组展示](#day-5小组展示) - - [展示流程](#展示流程) - - [跨机运行检查清单](#跨机运行检查清单) - - [评分标准](#评分标准总分-100) -- [附录](#附录) - - [代码示例](#代码示例) - - [项目结构](#建议项目结构) - - [参考资料](#参考资料) - ---- - -# Day 1：项目启动 - -## 🚀 快速开始 - -> **2026 最佳实践**：使用 `uv` 替代 pip/venv/poetry 进行全流程项目管理 - -```bash -# 1. 安装 uv（如尚未安装） -# 方法 A：使用 pip 安装（推荐，国内可用） -pip install uv -i https://mirrors.aliyun.com/pypi/simple/ - -# 方法 B：使用 pipx 安装（隔离环境） -pipx install uv - -# 方法 C：官方脚本（需要科学上网） -# macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh -# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex" - -# 配置 PyPI 镜像（加速依赖下载） -uv config set index-url https://mirrors.aliyun.com/pypi/simple/ - -# 2. 克隆/Fork 本模板仓库 -git clone http://hblu.top:3000/MachineLearning2025/CourseDesign -cd CourseDesign - -# 3. 初始化项目并安装依赖（uv 自动创建虚拟环境） -uv sync - -# 4. 配置 DeepSeek API Key（不要提交到仓库！） -cp .env.example .env -# 编辑 .env 文件，填入你的 API Key -# DEEPSEEK_API_KEY="your-key-here" - -# 5. 运行示例 -# 方式 A：运行 Streamlit 可视化 Demo（推荐） -uv run streamlit run src/streamlit_app.py - -# 方式 B：运行命令行 Agent Demo -uv run python src/agent_app.py - -# 方式 C：运行训练脚本 -uv run python src/train.py -``` - -### uv 常用命令速查 - -| 命令 | 说明 | -|------|------| -| `uv sync` | 同步依赖（根据 `pyproject.toml` 和 `uv.lock`） | -| `uv add ` | 添加依赖（自动更新 `pyproject.toml` 和 `uv.lock`） | -| `uv add --dev ` | 添加开发依赖（如 pytest, ruff） | -| `uv run ` | 在项目环境中运行命令 | -| `uv lock` | 手动更新锁文件 | -| `uv python install 3.12` | 安装指定 Python 版本 | - ---- - -## 技术栈要求（2026 版） - -| 组件 | 要求 | 2026 最佳实践 | -|------|------|---------------| -| **人数** | 2–3 人/组 | — | -| **Python 版本** | ≥ 3.12 | 推荐 3.12/3.14 | -| **项目管理** | `uv` | 替代 pip/venv/poetry，10-100x 更快 | -| **数据处理** | `polars` + `pandas>=2.2` | polars 作为主力（Lazy API），pandas 用于兼容 | -| **数据可视化** | `seaborn>=0.13` | 使用 Seaborn Objects API（`so.Plot`） | -| **数据验证** | `pydantic` + `pandera` | pydantic 验证单行/配置，pandera 验证 DataFrame 清洗前后 | -| **机器学习** | `scikit-learn` + `lightgbm` | sklearn 做基线，LightGBM 做高性能模型 | -| **Agent 框架** | `pydantic-ai` | 结构化输出、类型安全的 Agent | -| **LLM 提供方** | `DeepSeek` | OpenAI 兼容 API | - -### 必须包含的三块能力 - -| 能力 | 说明 | -|------|------| -| **传统机器学习** | 可复现训练流程、离线评估指标、模型保存与加载 | -| **LLM** | 用于解释、归因、生成建议/回复、信息整合（不能凭空杜撰） | -| **Agent** | 用工具调用把系统串起来（至少 2 个 tool，其中 1 个必须是 ML 预测/评估相关工具） | - ---- - -## 选题指南 - -> ⚠️ **注意**：Level 1/2/3 **都可以拿满分**；高难度通常更容易体现"深度"，但不会因为选 Level 1 就被封顶。 - -### Level 1｜入门：表格预测 + 行动建议闭环 - -> 📌 **建议新手选择** - -**目标**：做一个结构化数据的分类/回归模型，并让 Agent 基于模型输出给出可执行建议。 - -#### 推荐数据集 - -| 数据集 | 链接 | -|--------|------| -| Telco Customer Churn | [Kaggle](https://www.kaggle.com/datasets/blastchar/telco-customer-churn) | -| German Credit Risk | [Kaggle](https://www.kaggle.com/datasets/uciml/german-credit) | -| Bank Marketing | [Kaggle](https://www.kaggle.com/datasets/janiobachmann/bank-marketing-dataset) | -| Heart Failure Prediction | [Kaggle](https://www.kaggle.com/datasets/fedesoriano/heart-failure-prediction) | - -#### ✅ 必做部分 - -| 模块 | 要求 | -|------|------| -| **数据处理** | 使用 Polars 完成可复现的数据清洗流水线；使用 Pandera 定义 Schema | -| **机器学习** | 至少 2 个模型对比（1 个基线如 LogReg，1 个强模型如 LightGBM）；达到 `F1 ≥ 0.70` 或 `ROC-AUC ≥ 0.75` | -| **Agent** | 使用 Pydantic 定义输入输出；至少 2 个 tool（含 1 个 ML 预测工具） | - ---- - -### Level 2｜进阶：文本任务 + 处置建议 - -> 📌 **NLP 向** - -**目标**：做文本分类/情感分析，并让 Agent 生成结构化处置方案。 - -#### 推荐数据集 - -| 数据集 | 链接 | 说明 | -|--------|------|------| -| Twitter US Airline Sentiment | [Kaggle](https://www.kaggle.com/datasets/crowdflower/twitter-airline-sentiment) | 航空公司情感分析 | -| IMDB 50K Movie Reviews | [Kaggle](https://www.kaggle.com/datasets/lakshmi25npathi/imdb-dataset-of-50k-movie-reviews) | 电影评论情感 | -| SMS Spam Collection | [Kaggle](https://www.kaggle.com/datasets/uciml/sms-spam-collection-dataset) | 垃圾短信分类 | -| Consumer Complaints | [Kaggle](https://www.kaggle.com/datasets/selener/consumer-complaint-database) | 投诉分流 | - -#### ✅ 必做部分 - -| 模块 | 要求 | -|------|------| -| **数据处理** | 文本清洗要「克制」，说明预处理策略；使用 Pandera 定义 Schema | -| **机器学习** | 基线 `TF-IDF + LogReg`；达到 `Accuracy ≥ 0.85` 或 `Macro-F1 ≥ 0.80` | -| **Agent** | 实现「分类 → 解释 → 生成处置方案」流程；输出结构化（Pydantic） | - ---- - -### Level 3｜高阶：不平衡/多表/时序 + 多步决策 - -> 📌 **真实世界约束** - -**目标**：处理更复杂的数据特性（极度不平衡、多表关联、时序预测），实现多步决策 Agent。 - -#### 推荐数据集 - -| 数据集 | 链接 | 特点 | -|--------|------|------| -| Credit Card Fraud Detection | [Kaggle](https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud) | 极度不平衡 | -| IEEE-CIS Fraud Detection | [Kaggle](https://www.kaggle.com/c/ieee-fraud-detection) | 多表/特征工程复杂 | -| M5 Forecasting - Accuracy | [Kaggle](https://www.kaggle.com/competitions/m5-forecasting-accuracy) | 时序预测 | -| Instacart Market Basket | [Kaggle](https://www.kaggle.com/c/instacart-market-basket-analysis) | 多表 + 推荐 | - -#### ✅ 必做部分 - -| 模块 | 要求 | -|------|------| -| **数据处理** | 明确主键/外键与 join 规则；写出「数据泄露风险点清单」 | -| **机器学习** | 使用合理指标（如 `PR-AUC`）；必须使用时间切分评估（如时序） | -| **Agent** | 至少 3 步决策（评估 → 解释 → 行动计划）；输出结构化 | - ---- - -### 自选题目标准 - -> 💡 **鼓励自选题目**，但必须满足以下硬标准 - -| 要求 | 说明 | -|------|------| -| **数据真实可获取** | 公开、可重复下载（Kaggle/UCI/OpenML 等），提供链接 | -| **可量化预测任务** | 有明确标签/目标变量与评价指标 | -| **业务闭环** | 能落到「下一步做什么」的决策/行动 | -| **Agent 工具调用** | 至少 2 个 tools，其中 1 个必须是 ML 工具 | -| **规模与复杂度** | 样本量建议 ≥ 5,000 | -| **合规性** | 禁止爬取受限数据；禁止提交密钥/隐私数据 | - ---- - -## 可选扩展思路 - -以下是一些可选的扩展方向，用于加深项目深度，**不作为评分硬性要求**： - -| 方向 | 思路 | -|------|------| -| **可解释性** | 添加特征重要性解释工具（如 `explain_top_features`），让 Agent 能解释决策依据 | -| **代价敏感策略** | 给每个动作定义成本/收益假设，让 Agent 输出最划算的动作组合 | -| **阈值策略** | 把"预测概率"转化为"干预策略"（高/中/低风险不同处理） | -| **相似案例检索** | 用 TF-IDF/Embedding 做 `retrieve_similar(text) -> top_k`，提供可追溯证据 | -| **合规检查** | 对 Agent 输出做规则检查（如不得泄露隐私、不得虚假承诺） | -| **误差分析** | Top 误判样本分析，找出模型薄弱点 | -| **消融实验** | 对比不同特征/模型配置，得出改进方向 | - ---- - -# Day 2：自主设计 - -**今日任务**： -- 分组进行项目设计与开发 -- 完成数据探索与清洗 -- 开始训练基线模型 - -**建议里程碑**： -- [ ] 数据下载并完成初步探索 -- [ ] 数据清洗流水线可运行 -- [ ] 基线模型训练完成 - ---- - -# Day 3：答疑 + Git 指导 - -## Git 安装（国内环境） - -### Windows - -1. 下载 Git for Windows： - - 官方镜像（推荐）：https://registry.npmmirror.com/binary.html?path=git-for-windows/ - - 或官网：https://git-scm.com/download/win -2. 双击安装，全程默认设置即可 -3. 安装完成后，右键可看到「Git Bash Here」选项 - -### macOS - -```bash -# 方法 A：Xcode 命令行工具（推荐） -xcode-select --install - -# 方法 B：Homebrew -brew install git -``` - -### Linux (Ubuntu/Debian) - -```bash -sudo apt update -sudo apt install git -``` - -### 验证安装 - -```bash -git --version -# 输出类似：git version 2.43.0 -``` - ---- - -## Git 基础操作 - -### 首次配置 - -```bash -# 设置用户名和邮箱（提交记录会显示） -git config --global user.name "你的姓名" -git config --global user.email "你的邮箱@example.com" -``` - -### 克隆仓库 - -```bash -# 组长创建仓库后，所有组员克隆 -git clone http://hblu.top:3000/<用户名>/<项目名>.git -cd <项目名> -``` - -### 日常开发流程 - -```bash -# 1. 拉取最新代码（每次开始工作前） -git pull - -# 2. 查看当前状态 -git status - -# 3. 添加修改的文件 -git add . # 添加所有修改 -git add src/train.py # 或只添加特定文件 - -# 4. 提交修改 -git commit -m "feat: 添加数据预处理模块" - -# 5. 推送到远程仓库 -git push -``` - -### 常用命令速查 - -| 命令 | 说明 | -|------|------| -| `git clone ` | 克隆远程仓库 | -| `git pull` | 拉取远程更新 | -| `git status` | 查看当前状态 | -| `git add .` | 暂存所有修改 | -| `git commit -m "消息"` | 提交修改 | -| `git push` | 推送到远程 | -| `git log --oneline -5` | 查看最近 5 条提交 | - -### 团队协作注意事项 - -1. **每次开始工作前先 `git pull`**，避免冲突 -2. **提交信息要有意义**，如 `feat: 添加 Agent 工具` 而非 `update` -3. **小步提交**，不要把所有修改攒到最后一起提交 - ---- - -## .gitignore 详解 - -`.gitignore` 文件告诉 Git **哪些文件不要提交**。这非常重要，因为： -- **API Key 泄露会导致账户被盗用** -- **大文件会导致仓库臃肿** -- **临时文件没有提交意义** - -### 本项目必须忽略的文件 - -创建 `.gitignore` 文件，内容如下： - -```gitignore -# ===== 环境变量（绝对不能提交！）===== -.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 -``` - -> 💡 **关于 data/ 和 models/ 文件**： -> - **默认应该提交**，方便教师机直接运行 -> - 如果单个文件 **超过 10MB**，请添加到 `.gitignore` 并在 `data/README.md` 中说明下载方式 - -### 检查 .gitignore 是否生效 - -```bash -# 查看哪些文件会被 Git 忽略 -git status --ignored - -# 如果之前已经提交了不应提交的文件，需要先从 Git 中移除 -git rm --cached .env # 从 Git 移除但保留本地文件 -git rm --cached -r __pycache__ -git commit -m "chore: 移除不应提交的文件" -``` - ---- - -## 作业提交流程 - -### 1. 账号信息 - -账号已统一创建，请登录 [hblu.top:3000/MachineLearning2025](http://hblu.top:3000/MachineLearning2025) - -| 项目 | 说明 | -|------|------| -| **用户名** | `st` + 学号（如 `st2024001`） | -| **初始密码** | `12345678`（请登录后修改） | -| **组织** | MachineLearning2025 | - -> ⚠️ **首次登录后请立即修改密码** - -### 2. 组长创建仓库 - -在 [MachineLearning2025](http://hblu.top:3000/MachineLearning2025) 组织下创建新仓库，命名格式：`组号-项目名称`（如 `G01-ChurnPredictor`） - -### 3. 添加组员 - -Settings → Collaborators → 添加其他组员（使用 `st+学号` 搜索） - -### 4. 提交检查清单 - -- [ ] `.gitignore` 已创建且包含必要规则 -- [ ] `.env.example` 已提交，`.env` 未提交 -- [ ] 没有提交 API Key 或敏感信息 -- [ ] 没有提交大于 10MB 的文件 - ---- - -# Day 4：自主设计 - -**今日任务**： -- 继续完善项目 -- 完成 Agent 集成 -- 准备 Streamlit Demo -- 撰写项目报告 - -**建议里程碑**： -- [ ] ML 模型完成并保存 -- [ ] Agent 工具调用测试通过 -- [ ] Streamlit Demo 可运行 -- [ ] README.md 初稿完成 - ---- - -# Day 5：小组展示 - -## 展示流程 - -1. **教师机克隆你的仓库** - ```bash - git clone http://hblu.top:3000/MachineLearning2025/<项目名>.git - cd <项目名> - ``` - -2. **安装依赖并运行** - ```bash - uv sync - cp .env.example .env - # 教师填入测试用 API Key - uv run streamlit run src/streamlit_app.py - ``` - -3. **5-8 分钟 Demo 展示** - ---- - -## 跨机运行检查清单 - -> ⚠️ **避免「明明在我电脑上能跑」的问题** - -### 必须检查 - -| 检查项 | 说明 | 常见错误 | -|--------|------|----------| -| **依赖完整** | 所有依赖都在 `pyproject.toml` 中 | 忘记 `uv add` 新安装的包 | -| **相对路径** | 数据/模型使用相对路径 | `C:\Users\张三\data.csv` | -| **环境变量** | API Key 通过 `.env` 读取 | 硬编码 Key 在代码中 | -| **数据可获取** | 数据文件有下载说明或包含在仓库 | 数据只在本地，忘记上传 | -| **uv.lock** | 锁文件已提交 | 依赖版本不确定 | - -### 提交前测试方法 - -```bash -# 模拟干净环境测试 -cd /tmp -git clone <你的仓库地址> -cd <项目名> -uv sync -cp .env.example .env -# 填入 API Key -uv run streamlit run src/streamlit_app.py -``` - -### 常见问题排查 - -| 错误 | 原因 | 解决方案 | -|------|------|----------| -| `ModuleNotFoundError` | 缺少依赖 | `uv add <包名>` 后重新提交 | -| `FileNotFoundError` | 路径问题 | 使用 `Path(__file__).parent` 获取相对路径 | -| `DEEPSEEK_API_KEY not found` | 环境变量问题 | 检查 `.env` 格式和 `python-dotenv` | - ---- - -## 评分标准（总分 100） - -> ⚠️ 所有分析、对比、决策逻辑都必须在 `README.md` 中清晰体现。 - -### A. 问题与数据（10 分） - -| 维度 | 分值 | 要求 | -|------|------|------| -| 任务定义清晰 | 5 | 标签/目标、输入输出边界 | -| 数据说明与切分 | 5 | 来源链接、字段含义、切分策略 | - -### B. 传统机器学习（30 分） - -| 维度 | 分值 | 要求 | -|------|------|------| -| 基线与可复现训练 | 10 | 固定随机种子、训练脚本可跑通 | -| 指标与对比 | 10 | 达到指标要求，与基线对比 | -| 误差分析 | 10 | 展示错误样本/分桶，给出改进方向 | - -### C. LLM + Agent（30 分） - -| 维度 | 分值 | 要求 | -|------|------|------| -| 工具调用 | 10 | 至少 2 个 tools，能稳定调用 ML 工具 | -| 结构化输出 | 10 | Pydantic schema 清晰；字段有约束 | -| 建议可执行且有证据 | 10 | 能落地的动作清单，引用依据 | - -### D. 工程与演示（30 分） - -| 维度 | 分值 | 要求 | -|------|------|------| -| **Streamlit 演示** | **15** | 交互流畅；展示「预测→分析→建议」全流程 | -| **跨机运行** | **10** | 在教师机 `git clone && uv sync && uv run` 可直接运行 | -| 代码质量 | 5 | 结构清晰、有类型提示与文档 | - -### ❌ 常见扣分项 - -- 训练/推理无法在教师机跑通 -- 未使用 `uv` 管理项目 -- 数据泄露（尤其是时序/多表） -- Agent 编造数据集不存在的事实 -- **把密钥提交进仓库（严重扣分）** - -### ✅ 常见加分项 - -- 使用 Polars Lazy API 高效处理数据 -- 做了可解释性/阈值策略/代价敏感分析 -- 做了检索增强且引用可追溯证据 -- 做了消融/对比实验，结论清晰 - ---- - -# 附录 - -## 代码示例 - -### 数据处理：Polars 最佳实践 - -```python -import polars as pl - -# ✅ 推荐：使用 Lazy API（自动查询优化） -lf = pl.scan_csv("data/train.csv") -result = ( - lf.filter(pl.col("age") > 30) - .group_by("category") - .agg(pl.col("value").mean()) - .collect() # 最后一步才执行 -) - -# ✅ 推荐：从 Pandas 无缝迁移 -df_polars = pl.from_pandas(df_pandas) -df_pandas = df_polars.to_pandas() -``` - -### 数据验证：Pydantic + Pandera - -```python -from pydantic import BaseModel, Field - -class CustomerFeatures(BaseModel): - """客户特征数据模型""" - age: int = Field(ge=0, le=120, description="客户年龄") - tenure: int = Field(ge=0, description="客户任期（月）") - monthly_charges: float = Field(ge=0, description="月费用") - contract_type: str = Field(pattern="^(month-to-month|one-year|two-year)$") -``` - -```python -import pandera as pa -from pandera import Column, Check, DataFrameSchema - -# ✅ 定义清洗后 Schema -clean_data_schema = DataFrameSchema( - columns={ - "age": Column(pa.Int, checks=[Check.ge(0), Check.le(120)], nullable=False), - "tenure": Column(pa.Int, checks=[Check.ge(0)], nullable=False), - "monthly_charges": Column(pa.Float, checks=[Check.ge(0)], nullable=False), - }, - strict=True, - coerce=True, -) -``` - -### 机器学习：sklearn + LightGBM - -```python -from sklearn.model_selection import train_test_split -from sklearn.linear_model import LogisticRegression -from sklearn.metrics import roc_auc_score -import lightgbm as lgb -import joblib - -# 基线模型 -baseline = LogisticRegression(max_iter=1000, random_state=42) -baseline.fit(X_train, y_train) -print("Baseline ROC-AUC:", roc_auc_score(y_test, baseline.predict_proba(X_test)[:, 1])) - -# 高性能模型 -lgb_model = lgb.LGBMClassifier(n_estimators=500, learning_rate=0.05, random_state=42) -lgb_model.fit(X_train, y_train) - -# 保存模型 -joblib.dump(lgb_model, "models/lgb_model.pkl") -``` - -### Agent：pydantic-ai 示例 - -```python -from pydantic import BaseModel, Field -from pydantic_ai import Agent, RunContext - -class Decision(BaseModel): - """Agent 输出的结构化决策""" - risk_score: float = Field(ge=0, le=1, description="预测风险概率") - decision: str = Field(description="建议策略") - actions: list[str] = Field(description="可执行动作清单") - rationale: str = Field(description="决策依据") - -agent = Agent( - "deepseek:deepseek-chat", - output_type=Decision, - system_prompt="你是业务决策助手。必须先调用工具获取预测结果，再给出结构化决策。", -) - -@agent.tool -def predict_risk(ctx: RunContext, features: CustomerFeatures) -> float: - """调用 ML 模型返回风险分数""" - # TODO: 实现模型调用 - pass -``` - -### API Key 配置 - -> ⚠️ **不要把 Key 写进代码、不要提交到仓库！** - -创建 `.env.example`（提交到仓库）： -``` -DEEPSEEK_API_KEY=your-key-here -``` - -复制为 `.env` 并填入真实 Key（`.env` 在 `.gitignore` 中排除）。 - ---- - -## 建议项目结构 - -``` -ml_course_design/ -├── pyproject.toml # 项目配置与依赖 -├── uv.lock # 锁定的依赖版本 -├── README.md # 项目说明与报告 -├── .env.example # 环境变量模板 -├── .gitignore # Git 忽略规则 -│ -├── data/ # 数据目录 -│ └── README.md # 数据来源说明 -│ -├── models/ # 训练产物 -│ └── .gitkeep -│ -├── src/ # 核心代码 -│ ├── __init__.py -│ ├── data.py # 数据读取/清洗 -│ ├── features.py # Pydantic 特征模型 -│ ├── train.py # 训练与评估 -│ ├── infer.py # 推理接口 -│ ├── agent_app.py # Agent 入口 -│ └── streamlit_app.py # Demo 入口 -│ -└── tests/ # 测试 - └── test_*.py -``` - ---- - -## README.md 模板（你的项目） - -请将以下内容作为你项目 `README.md` 的模板 - -````markdown -# 项目名称 - -> **机器学习 (Python) 课程设计** - -## 👥 团队成员 - -| 姓名 | 学号 | 贡献 | -|------|------|------| -| 张三 | 2024001 | 数据处理、模型训练 | -| 李四 | 2024002 | Agent 开发、Streamlit | -| 王五 | 2024003 | 测试、文档撰写 | - -## 📝 项目简介 - -（1-2 段描述项目目标、选用的数据集、解决的问题） - -## 🚀 快速开始 - -```bash -# 克隆仓库 -git clone http://hblu.top:3000/MachineLearning2025/GXX-ProjectName.git -cd GXX-ProjectName - -# 安装依赖 -uv sync - -# 配置环境变量 -cp .env.example .env -# 编辑 .env 填入 API Key - -# 运行 Demo -uv run streamlit run src/streamlit_app.py -``` - ---- - -## 1️⃣ 问题定义与数据 - -### 1.1 任务描述 - -（描述预测任务类型：分类/回归/时序，以及业务目标） - -### 1.2 数据来源 - -| 项目 | 说明 | -|------|------| -| 数据集名称 | XXX | -| 数据链接 | [Kaggle](https://...) | -| 样本量 | X,XXX 条 | -| 特征数 | XX 个 | - -### 1.3 数据切分与防泄漏 - -（如何切分训练/验证/测试集？如何确保没有数据泄漏？） - ---- - -## 2️⃣ 机器学习流水线 - -### 2.1 基线模型 - -| 模型 | 指标 | 结果 | -|------|------|------| -| Logistic Regression | ROC-AUC | 0.XX | - -### 2.2 进阶模型 - -| 模型 | 指标 | 结果 | -|------|------|------| -| LightGBM | ROC-AUC | 0.XX | - -### 2.3 误差分析 - -（模型在哪些样本上表现不佳？为什么？） - ---- - -## 3️⃣ Agent 实现 - -### 3.1 工具定义 - -| 工具名 | 功能 | 输入 | 输出 | -|--------|------|------|------| -| `predict_risk` | 调用 ML 模型预测 | CustomerFeatures | float | -| `explain_features` | 解释特征影响 | CustomerFeatures | list[str] | - -### 3.2 决策流程 - -（Agent 如何使用工具？如：预测 → 解释 → 建议） - -### 3.3 案例展示 - -**输入**： -``` -请分析这位客户的流失风险：年龄 35，任期 2 个月，月费 89.99 -``` - -**输出**： -```json -{ - "risk_score": 0.72, - "decision": "高风险，建议主动挥留", - "actions": ["发送优惠短信", "客服回访"], - "rationale": "新客户 + 月付合同是流失高危特征" -} -``` - ---- - -## 4️⃣ 开发心得 - -### 4.1 主要困难与解决方案 - -（遇到的最大困难是什么？如何解决？） - -### 4.2 对 AI 辅助编程的感受 - -（使用 AI 工具的体验如何？哪些场景有帮助？哪些地方需要注意？） - -### 4.3 局限与未来改进 - -（如果有更多时间，还有哪些可以改进的地方？） -```` - ---- - -## 参考资料 - -### 核心工具文档 - -| 资源 | 链接 | 说明 | -|------|------|------| -| uv 官方文档 | https://docs.astral.sh/uv/ | Python 项目管理器 | -| Polars 用户指南 | https://pola.rs/ | 高性能 DataFrame | -| Pydantic 文档 | https://docs.pydantic.dev/ | 数据验证与设置 | -| Pandera 文档 | https://pandera.readthedocs.io/ | DataFrame Schema 验证 | -| pydantic-ai 文档 | https://ai.pydantic.dev/ | Agent 框架 | -| DeepSeek API | https://api.deepseek.com | OpenAI 兼容 | - -### 推荐学习资源 - -| 资源 | 链接 | -|------|------| -| Polars vs Pandas | https://pola.rs/user-guide/migration/pandas/ | -| Pydantic AI 快速入门 | https://ai.pydantic.dev/quick-start/ | -| Pandera 快速入门 | https://pandera.readthedocs.io/en/stable/try_pandera.html | -| uv 项目工作流 | https://docs.astral.sh/uv/concepts/projects/ | - ---- - -## 📋 Checklist（提交前自检） - -- [ ] 使用 `uv sync` 安装依赖，无需手动创建虚拟环境 -- [ ] `.gitignore` 包含 `.env`、`__pycache__`、大文件 -- [ ] 在干净环境下可以复现（`git clone && uv sync && uv run`） -- [ ] 没有提交 API Key 或敏感信息 -- [ ] 使用 Polars 进行数据处理 -- [ ] 使用 Pydantic 定义特征和输出模型 -- [ ] Agent 至少有 2 个 tool（含 1 个 ML 工具） -- [ ] README.md 说明了数据切分策略 -- [ ] Demo 可以正常运行 - ---- - -> 💬 **有问题？** 请在课程群/Issue 中提问，我们会尽快回复。 +# 智能银行营销系统 (Smart Marketing System) + +> **机器学习 (Python) 课程设计** | Level 1：表格预测 + 行动建议闭环 + +## 👥 团队成员 + +| 姓名 | 学号 | 贡献 | +|------|------|------| +| Trae | AI-001 | 全栈开发 (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/)