453 lines
18 KiB
Markdown
453 lines
18 KiB
Markdown
# 机器学习 × LLM × Agent：课程设计
|
||
|
||
> **小组作业** | 2–3 人/组 | 构建一个「可落地的智能预测与行动建议系统」
|
||
|
||
用传统机器学习完成可量化的预测任务，再用 LLM + Agent 把预测结果变成可执行的决策/建议，并保证输出结构化、可追溯、可复现。
|
||
|
||
---
|
||
|
||
## 📑 目录
|
||
|
||
- [快速开始](#-快速开始)
|
||
- [技术栈要求](#0-技术栈要求强制)
|
||
- [选题指南](#1-选题三档难度任选其一)
|
||
- [Level 1：入门](#level-1入门表格预测--行动建议闭环)
|
||
- [Level 2：进阶](#level-2进阶文本任务--处置建议回复生成)
|
||
- [Level 3：高阶](#level-3高阶不平衡多表时序--多步决策-agent)
|
||
- [自选题目标准](#2-自选题目标准)
|
||
- [代码示例](#3-deepseek--pydantic-ai最小可运行示例)
|
||
- [代码规范](#4-代码规范)
|
||
- [项目结构](#5-建议项目结构)
|
||
- [交付物与评分](#6-交付物与评分)
|
||
- [参考资料](#7-参考资料)
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
```bash
|
||
# 1. 克隆/Fork 本模板仓库
|
||
git clone http://49.234.193.192:3000/MachineLearning2025/CourseDesign
|
||
cd CourseDesign
|
||
|
||
# 2. 创建虚拟环境并安装依赖
|
||
python -m venv .venv
|
||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
|
||
# 3. 配置 DeepSeek API Key（不要提交到仓库！）
|
||
# 复制示例配置
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填入你的 API Key
|
||
# DEEPSEEK_API_KEY="your-key-here"
|
||
|
||
# 4. 运行示例
|
||
# 方式 A：运行 Streamlit 可视化 Demo（推荐）
|
||
python -m streamlit run src/streamlit_app.py
|
||
|
||
# 方式 B：运行命令行 Agent Demo
|
||
python src/agent_app.py
|
||
```
|
||
|
||
---
|
||
|
||
## 0. 技术栈要求（强制）
|
||
|
||
| 组件 | 要求 |
|
||
|------|------|
|
||
| **人数** | 2–3 人/组 |
|
||
| **Agent 框架** | `pydantic-ai` |
|
||
| **LLM 提供方** | `DeepSeek`（OpenAI 兼容 API） |
|
||
|
||
### 必须包含的三块能力
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| **传统机器学习** | 可复现训练流程、离线评估指标、模型保存与加载 |
|
||
| **LLM** | 用于解释、归因、生成建议/回复、信息整合（不能凭空杜撰） |
|
||
| **Agent** | 用工具调用把系统串起来（至少 2 个 tool，其中 1 个必须是 ML 预测/评估相关工具） |
|
||
|
||
---
|
||
|
||
## 1. 选题：三档难度（任选其一）
|
||
|
||
你们可以先选难度档位，再从数据集列表里选一个；也可以自选（见「自选题目标准」）。
|
||
|
||
> ⚠️ **注意**：Level 1/2/3 **都可以拿满分**；高难度通常更容易体现"深度"，但不会因为选 Level 1 就被封顶。
|
||
|
||
---
|
||
|
||
### Level 1｜入门：表格预测 + 行动建议闭环
|
||
|
||
> 📌 **建议新手选择**
|
||
|
||
**目标**：做一个结构化数据的分类/回归模型，并让 Agent 基于模型输出给出可执行建议（如挽留、风控、营销、分诊）。
|
||
|
||
#### 交付的系统能力
|
||
|
||
- 训练并保存一个基线模型（如 `LogReg` / `LightGBM` / `RandomForest`）
|
||
- 提供 `predict_proba` / `predict` 工具给 Agent 调用
|
||
- Agent 输出**结构化决策**（Pydantic schema），并能说明建议与关键特征/规则的关联
|
||
|
||
#### 推荐数据集（任选其一）
|
||
|
||
| 数据集 | 链接 |
|
||
|--------|------|
|
||
| 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) |
|
||
|
||
#### 最低基准
|
||
|
||
| 任务类型 | 指标要求 |
|
||
|----------|----------|
|
||
| 二分类 | `F1 ≥ 0.70` 或 `ROC-AUC ≥ 0.75` |
|
||
| 回归 | `MAE/RMSE` 相对朴素基线（均值/中位数）**显著提升**，需在报告中说明 |
|
||
|
||
#### 参考练习清单
|
||
|
||
**传统 ML（必须）**：
|
||
- 做一条可复现的数据流水线：缺失值处理、类别编码、数值缩放、训练/验证切分（并写清"为什么这样切分"）
|
||
- 至少 2 个模型对比：一个可解释基线（如 Logistic Regression），一个更强模型（如 LightGBM/RandomForest）
|
||
- 做 1 次误差分析：Top 误判样本/分桶（例如按年龄段/合同类型）看哪里最容易错
|
||
|
||
**Agent（必须）**：
|
||
- 定义结构化输出（Pydantic）：`risk_score + decision + actions + rationale`
|
||
- 至少 2 个工具（tool），其中 1 个必须调用你们的 ML（例如 `predict_risk(features)`）
|
||
- 推荐再加 1 个解释类工具：`explain_top_features(features) -> list[str]`（可用系数/重要性/规则，不要求复杂 SHAP）
|
||
|
||
**系统闭环（建议做到）**：
|
||
- 阈值/策略选择：把"预测概率"变成"要不要干预/怎么干预"（例如：高风险→人工复核；中风险→短信挽留；低风险→不操作）
|
||
- 做一个简单"成本-收益"版本：每个动作给一个成本/收益假设，让 Agent 给出最划算的动作组合（在报告里写清假设）
|
||
|
||
---
|
||
|
||
### Level 2｜进阶：文本任务 + 处置建议/回复生成
|
||
|
||
> 📌 **NLP 向**
|
||
|
||
**目标**：做文本分类/情感/主题/工单分流等任务，并让 Agent 生成"可执行处置方案"（如回复、升级、分派、风险提示），且输出必须结构化并可审计。
|
||
|
||
#### 交付的系统能力
|
||
|
||
- 传统 ML NLP 基线（如 `TF-IDF + Linear Model`）或轻量深度模型（可选）
|
||
- 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) | 投诉分流（很适配 Agent） |
|
||
|
||
#### 最低基准
|
||
|
||
| 任务类型 | 指标要求 |
|
||
|----------|----------|
|
||
| 分类 | `Accuracy ≥ 0.85` 或 `Macro-F1 ≥ 0.80` |
|
||
|
||
#### 参考练习清单
|
||
|
||
**传统 ML NLP（必须）**：
|
||
- 基线：`TF-IDF + LogisticRegression/LinearSVC`，再加入至少一个更强的模型（如 `LightGBM`, `RandomForest`, 或轻量 BERT 模型）；并报告 `macro-F1`、混淆矩阵、典型错例
|
||
- 文本清洗要「克制」：说明你做了哪些预处理、为什么（不要把标签信息泄露进特征）
|
||
|
||
**Agent（必须）**：
|
||
- 工单/评论 → `classify_text(text)`（ML 工具）→ `draft_response(label, evidence)`（LLM）→ 输出结构化处置方案
|
||
- 建议加入 1 个「证据」工具：`extract_evidence(text) -> list[str]`（关键词/关键句/相似样本 id）
|
||
|
||
**更贴近真实（可选加分）**：
|
||
- **相似案例检索**：用 TF-IDF/Embedding 做 `retrieve_similar(text) -> top_k`，Agent 引用相似案例作为「可追溯证据」（禁止编造历史工单）
|
||
- **合规与安全**：对输出做规则检查（例如不得输出隐私信息/不得承诺无法兑现的政策），失败时让 Agent 重新生成
|
||
|
||
---
|
||
|
||
### Level 3｜高阶：不平衡/多表/时序 + 多步决策 Agent
|
||
|
||
> 📌 **真实世界约束**
|
||
|
||
**目标**：选择一个更接近真实业务约束的任务（极度不平衡、多表关联、时序预测等），实现更强的评估与更可靠的 Agent 决策链路。
|
||
|
||
#### 交付的系统能力
|
||
|
||
- 针对数据特性选择合适指标与训练策略（不平衡采样、阈值策略、时间切分、泄露防护等）
|
||
- 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) | 多表 + 召回/推荐 |
|
||
|
||
#### 最低基准
|
||
|
||
| 任务类型 | 指标要求 |
|
||
|----------|----------|
|
||
| 不平衡分类 | `PR-AUC` / `Recall@Precision` 等合理指标，并与 naive 基线对比 |
|
||
| 时序 | 必须使用时间切分评估（rolling/holdout），并与 naive 基线对比 |
|
||
|
||
#### 参考练习清单
|
||
|
||
**不平衡分类路线（如欺诈）**：
|
||
- 重点不在 Accuracy：用 `PR-AUC` / `Recall@Precision` / `Cost` 等指标，给出阈值选择依据
|
||
- 做 1 个「代价敏感」版本：例如漏报成本 > 误报成本，并让 Agent 基于代价输出策略
|
||
|
||
**多表路线（如电商/多表欺诈）**：
|
||
- 明确主键/外键与 join 规则，写出「数据泄露风险点清单」
|
||
- 做一个可复现的特征构建模块（统计聚合、时间窗特征等）
|
||
|
||
**时序路线（如 M5）**：
|
||
- 强制时间切分；至少对比 1 个朴素基线（naive/seasonal naive）
|
||
- 让 Agent 输出「补货/促销/库存」建议，并说明依据（趋势、季节性、置信区间）
|
||
|
||
**Agent（必须）**：
|
||
- 至少 3 步决策：例如 `评估风险/预测 → 解释与约束检查 → 生成行动计划`
|
||
- 在报告里画一张「决策链路图」
|
||
|
||
---
|
||
|
||
## 2. 自选题目标准
|
||
|
||
> 💡 **鼓励自选题目**，但必须满足以下硬标准，并先提交 1 页开题报告（Markdown 即可）
|
||
|
||
| 要求 | 说明 |
|
||
|------|------|
|
||
| **数据真实可获取** | 公开、可重复下载（Kaggle/UCI/OpenML/政府开放数据等），提供链接与数据说明 |
|
||
| **可量化预测任务** | 有明确标签/目标变量与评价指标；不得只做「聊天/生成」 |
|
||
| **业务闭环** | 能落到「下一步做什么」的决策/行动（由 Agent 负责） |
|
||
| **Agent 工具调用** | 至少 2 个 tools，其中 1 个必须是 ML 预测/评估/解释工具 |
|
||
| **规模与复杂度** | 样本量建议 ≥ 5,000（或能说明复杂性来自多表/长文本/时序）；不得低于 Level 1 |
|
||
| **合规性** | 禁止爬取受限数据；禁止提交包含密钥/个人隐私数据的仓库内容 |
|
||
|
||
---
|
||
|
||
## 3. DeepSeek + pydantic-ai：最小可运行示例
|
||
|
||
下面示例展示如何用 `pydantic-ai` 让 Agent 输出结构化结果，并通过 tool 调用你们训练好的模型。
|
||
|
||
```python
|
||
import os
|
||
from typing import Any
|
||
|
||
from pydantic import BaseModel, Field
|
||
from pydantic_ai import Agent, RunContext
|
||
|
||
|
||
class Decision(BaseModel):
|
||
"""Agent 输出的结构化决策"""
|
||
risk_score: float = Field(ge=0, le=1, description="预测风险/流失概率等，0~1")
|
||
decision: str = Field(description="建议采取的总体策略")
|
||
actions: list[str] = Field(description="可执行动作清单（3~8条）")
|
||
rationale: str = Field(description="基于哪些证据/特征做出建议（不要编造事实）")
|
||
|
||
|
||
# 使用 provider:model 简写（DeepSeek 是 OpenAI 兼容 API）
|
||
agent = Agent(
|
||
"deepseek:deepseek-chat", # 也可尝试 "deepseek:deepseek-reasoner"
|
||
output_type=Decision,
|
||
system_prompt=(
|
||
"你是业务决策助手。你必须先调用工具获取模型预测与可解释信息，"
|
||
"再给出结构化决策与可执行动作；不得编造数据集中不存在的事实。"
|
||
),
|
||
)
|
||
|
||
|
||
@agent.tool
|
||
def predict_risk(ctx: RunContext[Any], features: dict) -> float:
|
||
"""调用训练好的 ML 模型，返回 0~1 的风险分数。
|
||
|
||
Args:
|
||
ctx: 运行上下文
|
||
features: 特征字典，如 {"age": 35, "contract": "month-to-month", ...}
|
||
|
||
Returns:
|
||
风险概率值 (0~1)
|
||
"""
|
||
# TODO: 加载模型并预处理特征
|
||
# model = joblib.load("models/model.pkl")
|
||
# X = preprocess(features)
|
||
# proba = model.predict_proba(X)[0, 1]
|
||
# return float(proba)
|
||
raise NotImplementedError("请实现模型调用逻辑")
|
||
|
||
|
||
@agent.tool
|
||
def explain_top_features(ctx: RunContext[Any], features: dict) -> list[str]:
|
||
"""解释对预测结果影响最大的特征。
|
||
|
||
Args:
|
||
ctx: 运行上下文
|
||
features: 特征字典
|
||
|
||
Returns:
|
||
影响最大的特征列表，如 ["合同类型: 月付 (+0.25)", "任期: 2个月 (+0.15)"]
|
||
"""
|
||
# TODO: 实现特征重要性解释
|
||
raise NotImplementedError("请实现特征解释逻辑")
|
||
```
|
||
|
||
### API Key 配置
|
||
|
||
> ⚠️ **重要**：不要把 Key 写进代码、不要提交到仓库！
|
||
|
||
```bash
|
||
# macOS / Linux (zsh/bash)
|
||
export DEEPSEEK_API_KEY="your-key-here"
|
||
|
||
# Windows (PowerShell)
|
||
$env:DEEPSEEK_API_KEY="your-key-here"
|
||
```
|
||
|
||
建议在项目根目录创建 `.env.example` 文件（提交到仓库），内容如下：
|
||
|
||
```
|
||
DEEPSEEK_API_KEY=your-key-here
|
||
```
|
||
|
||
然后复制为 `.env` 并填入真实 Key（`.env` 已在 `.gitignore` 中排除）。
|
||
|
||
---
|
||
|
||
## 4. 代码规范
|
||
|
||
本作业**不使用 CI/CD 作为评分项**，但代码质量会被严格检查。
|
||
|
||
| 要求 | 说明 |
|
||
|------|------|
|
||
| **可运行** | 在「干净环境」按 README 步骤能跑通训练与 demo |
|
||
| **可复现** | 固定随机种子；训练/评估脚本可重复得到同级别指标；关键超参可配置 |
|
||
| **结构清晰** | 模块划分合理；避免超长脚本；核心逻辑放 `src/`；数据处理、训练、推理、Agent 分离 |
|
||
| **类型提示与文档** | 对外 API 必须写 type hints 与 docstring |
|
||
| **不泄露** | 避免数据泄露（特别是时序/多表任务）；报告中说明切分策略 |
|
||
| **安全** | 密钥用环境变量；仓库中提供 `.env.example` 但不得提交真实 `.env` |
|
||
|
||
---
|
||
|
||
## 5. 建议项目结构
|
||
|
||
```
|
||
ml_course_design_template/
|
||
├── REPORT.md # 项目报告
|
||
├── requirements.txt # Python 依赖
|
||
├── .env.example # 环境变量模板（不含真实密钥）
|
||
├── .gitignore # Git 忽略规则
|
||
│
|
||
├── data/ # 数据目录
|
||
│ └── README.md # 数据来源说明（原始大数据不要提交）
|
||
│
|
||
├── models/ # 训练产物（模型文件）
|
||
│ └── .gitkeep
|
||
│
|
||
├── notebooks/ # 探索性分析（可选）
|
||
│ └── eda.ipynb
|
||
│
|
||
├── src/ # 核心代码
|
||
│ ├── __init__.py
|
||
│ ├── data.py # 数据读取/清洗/特征工程
|
||
│ ├── train.py # 训练与离线评估
|
||
│ ├── infer.py # 推理接口（给 Agent 的 tool 调用）
|
||
│ └── agent_app.py # pydantic-ai Agent 入口
|
||
│ └── streamlit_app.py # Streamlit demo 入口
|
||
│
|
||
└── tests/ # 测试（建议至少覆盖 3 个关键函数）
|
||
├── __init__.py
|
||
├── test_data.py
|
||
├── test_model.py
|
||
└── test_agent.py
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 交付物与评分
|
||
|
||
### 必交材料
|
||
|
||
| 材料 | 说明 |
|
||
|------|------|
|
||
| **代码仓库链接** | 组长提交 |
|
||
| **项目报告** REPORT.md | 4–8 页 Markdown/PDF：问题定义、数据说明、特征/模型、评估、Agent 设计、局限与改进 |
|
||
| **演示** | 5–8 分钟 demo（Streamlit / Gradio / Next.js + FastAPI 等），展示端到端流程 |
|
||
|
||
### 评分标准（总分 100）
|
||
|
||
> ⚠️ **评分核心依据**：所有分析、对比、决策逻辑都必须在 `REPORT.md` 中有清晰体现。仅有代码但无报告说明将导致严重扣分。
|
||
|
||
#### A. 问题与数据（10 分）
|
||
|
||
| 维度 | 分值 | 要求 |
|
||
|------|------|------|
|
||
| 任务定义清晰 | 5 | 标签/目标是什么、为什么重要、输入输出边界 |
|
||
| 数据说明与切分 | 5 | 来源链接、字段含义；明确的随机/时间切分与防泄露措施 |
|
||
|
||
#### B. 传统机器学习（30 分）
|
||
|
||
| 维度 | 分值 | 要求 |
|
||
|------|------|------|
|
||
| 基线与可复现训练 | 10 | 固定随机种子、训练脚本能跑通、基线合理 |
|
||
| 指标与对比 | 10 | 指标选择正确，并与至少 1 个强/弱基线对比 |
|
||
| 误差分析 | 10 | 展示错误样本/分桶/特征影响，给出改进方向 |
|
||
|
||
#### C. LLM + Agent（30 分）
|
||
|
||
| 维度 | 分值 | 要求 |
|
||
|------|------|------|
|
||
| 工具调用 | 10 | 至少 2 个 tools，能稳定调用 ML 工具（不是「假调用」） |
|
||
| 结构化输出 | 10 | Pydantic schema 清晰；字段有约束；失败能重试/兜底 |
|
||
| 建议可执行且有证据 | 10 | 能落地的动作清单，并能引用依据（禁止编造事实） |
|
||
|
||
#### D. 工程与演示（30 分）
|
||
|
||
| 维度 | 分值 | 要求 |
|
||
|------|------|------|
|
||
| **Streamlit 演示** | **20** | **交互流畅；能完整展示「预测→分析→建议」全流程；UI 美观** |
|
||
| 代码质量与规范 | 10 | 结构清晰、模块化、有类型提示与文档；干净环境可一键运行 |
|
||
|
||
### ❌ 常见扣分项
|
||
|
||
- 训练/推理无法在助教环境跑通；或需要手动改很多路径/参数
|
||
- 数据泄露（尤其是时序/多表）；或评估切分不合理但未说明
|
||
- Agent 输出「看似合理但无证据」的内容，或编造数据集不存在的事实
|
||
- **把密钥提交进仓库（严重扣分）**
|
||
|
||
### ✅ 常见加分项
|
||
|
||
> 不额外加分栏，但会让你们更容易拿到高分
|
||
|
||
- 做了可解释性/阈值策略/代价敏感分析，并与业务动作闭环
|
||
- 做了检索增强（RAG/相似案例）且引用可追溯证据
|
||
- 做了消融/对比实验，结论清晰且能指导下一步优化
|
||
|
||
---
|
||
|
||
## 7. 参考资料
|
||
|
||
| 资源 | 链接 |
|
||
|------|------|
|
||
| pydantic-ai 文档 | https://ai.pydantic.dev/ |
|
||
| DeepSeek API | https://api.deepseek.com （OpenAI 兼容） |
|
||
| DeepSeek 模型 | `deepseek-chat` / `deepseek-reasoner` |
|
||
|
||
---
|
||
|
||
## 📋 Checklist（提交前自检）
|
||
|
||
- [ ] 代码仓库可正常访问
|
||
- [ ] REPORT 包含完整的运行步骤
|
||
- [ ] 在干净环境下可以复现训练和推理
|
||
- [ ] 没有提交 API Key 或敏感信息
|
||
- [ ] 没有提交大型数据文件
|
||
- [ ] Agent 至少有 2 个 tool（含 1 个 ML 工具）
|
||
- [ ] 输出使用 Pydantic 结构化
|
||
- [ ] 报告说明了数据切分策略
|
||
- [ ] Demo 可以正常运行
|
||
|
||
---
|
||
|
||
> 💬 **有问题？** 请在课程群/Issue 中提问，我们会尽快回复。
|