CourseDesign/README.md

# 机器学习 × 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 <your-repo-url>
cd ml_course_design_template

# 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 页 proposal（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/
├── README.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 入口
│
└── tests/                    # 测试（建议至少覆盖 3 个关键函数）
    ├── __init__.py
    ├── test_data.py
    ├── test_model.py
    └── test_agent.py
```

---

## 6. 交付物与评分

### 必交材料

| 材料 | 说明 |
|------|------|
| **代码仓库链接** | 组长提交 |
| **项目报告** | 4–8 页 Markdown/PDF：问题定义、数据说明、特征/模型、评估、Agent 设计、局限与改进 |
| **演示** | 5–8 分钟 demo（Streamlit / Gradio / Next.js + FastAPI 等），展示端到端流程 |

### 评分标准（总分 100）

#### A. 问题与数据（15 分）

| 维度 | 分值 | 要求 |
|------|------|------|
| 任务定义清晰 | 5 | 标签/目标是什么、为什么重要、输入输出边界 |
| 数据说明完整 | 5 | 来源链接、字段含义、样本量、潜在偏差/缺失 |
| 切分与泄露防护 | 5 | 随机/分层/时间切分说明；明确避免目标泄露 |

#### B. 传统机器学习（35 分）

| 维度 | 分值 | 要求 |
|------|------|------|
| 基线与可复现训练 | 10 | 固定随机种子、训练脚本能跑通、基线合理 |
| 指标与对比 | 10 | 指标选择正确，并与至少 1 个强/弱基线对比 |
| 误差分析 | 10 | 展示错误样本/分桶/特征影响，给出改进方向 |
| 结果可信度 | 5 | 阈值/校准/稳定性（任选其一做到位即可） |

#### C. LLM + Agent（35 分）

| 维度 | 分值 | 要求 |
|------|------|------|
| 工具调用 | 10 | 至少 2 个 tools，能稳定调用 ML 工具（不是「假调用」） |
| 结构化输出 | 10 | Pydantic schema 清晰；字段有约束；失败能重试/兜底 |
| 建议可执行且有证据 | 10 | 能落地的动作清单，并能引用依据（禁止编造事实） |
| 边界与安全 | 5 | 能处理异常输入；对敏感输出做规则约束 |

#### D. 工程与规范（15 分）

| 维度 | 分值 | 要求 |
|------|------|------|
| 可运行与可复现 | 5 | README 步骤清楚；干净环境可复现；依赖明确 |
| 代码结构与风格 | 5 | 模块化、命名清晰、类型提示/Docstring 到位 |
| 演示质量 | 5 | demo 端到端连贯；能说明架构与关键取舍 |

### ❌ 常见扣分项

- 训练/推理无法在助教环境跑通；或需要手动改很多路径/参数
- 数据泄露（尤其是时序/多表）；或评估切分不合理但未说明
- Agent 输出「看似合理但无证据」的内容，或编造数据集不存在的事实
- **把密钥提交进仓库（严重扣分）**

### ✅ 常见加分项

> 不额外加分栏，但会让你们更容易拿到高分

- 做了可解释性/阈值策略/代价敏感分析，并与业务动作闭环
- 做了检索增强（RAG/相似案例）且引用可追溯证据
- 做了消融/对比实验，结论清晰且能指导下一步优化

---

## 7. 参考资料

| 资源 | 链接 |
|------|------|
| pydantic-ai 文档 | https://ai.pydantic.dev/ |
| DeepSeek API | https://api.deepseek.com （OpenAI 兼容） |
| DeepSeek 模型 | `deepseek-chat` / `deepseek-reasoner` |

---

## 📋 Checklist（提交前自检）

- [ ] 代码仓库可正常访问
- [ ] README 包含完整的运行步骤
- [ ] 在干净环境下可以复现训练和推理
- [ ] 没有提交 API Key 或敏感信息
- [ ] 没有提交大型数据文件
- [ ] Agent 至少有 2 个 tool（含 1 个 ML 工具）
- [ ] 输出使用 Pydantic 结构化
- [ ] 报告说明了数据切分策略
- [ ] Demo 可以正常运行

---

> 💬 **有问题？** 请在课程群/Issue 中提问，我们会尽快回复。