MachineLearning2025/CourseDesign
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
957ba5ad2e
CourseDesign/README.md

18 KiB
Raw Blame History

机器学习 × LLM × Agent：课程设计

小组作业 | 2–3 人/组 | 构建一个「可落地的智能预测与行动建议系统」

用传统机器学习完成可量化的预测任务，再用 LLM + Agent 把预测结果变成可执行的决策/建议，并保证输出结构化、可追溯、可复现。

📑 目录

🚀 快速开始

# 1. 克隆/Fork 本模板仓库
git clone http://hblu.top: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
German Credit Risk Kaggle
Bank Marketing Kaggle
Heart Failure Prediction Kaggle

最低基准

任务类型 指标要求
二分类 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 航空公司情感分析
IMDB 50K Movie Reviews Kaggle 电影评论情感
SMS Spam Collection Kaggle 垃圾短信分类
Consumer Complaints Kaggle 投诉分流（很适配 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 极度不平衡
IEEE-CIS Fraud Detection Kaggle 多表/特征工程复杂
M5 Forecasting - Accuracy Kaggle 时序预测 + 补货决策
Instacart Market Basket Kaggle 多表 + 召回/推荐

最低基准

任务类型 指标要求
不平衡分类 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 调用你们训练好的模型。

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 写进代码、不要提交到仓库！

# 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 中提问，我们会尽快回复。