机器学习 × LLM × Agent：课程设计（5 天）

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

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

---

📅 课程安排概览

天数	主题	内容
Day 1	项目启动	技术栈介绍 + 演示 + 选题分组
Day 2	自主设计	分组开发
Day 3	答疑 + Git 指导	集中答疑 + Git 提交教学
Day 4	自主设计	继续开发 + 准备展示
Day 5	小组展示	教师机运行 + 评分

---

📑 目录

• Day 1：项目启动
  • 快速开始
  • 技术栈要求
  • 选题指南
  • 可选扩展思路
• Day 2：自主设计
• Day 3：答疑 + Git 指导
  • Git 安装
  • Git 基础操作
  • .gitignore 详解
• Day 4：自主设计
• Day 5：小组展示
  • 展示流程
  • 跨机运行检查清单
  • 评分标准
• 附录
  • 代码示例
  • 项目结构
  • 参考资料

---

Day 1：项目启动

🚀 快速开始

2026 最佳实践：使用 uv 替代 pip/venv/poetry 进行全流程项目管理

# 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 <package>	添加依赖（自动更新 pyproject.toml 和 uv.lock）
uv add --dev <package>	添加开发依赖（如 pytest, ruff）
uv run <command>	在项目环境中运行命令
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
German Credit Risk	Kaggle
Bank Marketing	Kaggle
Heart Failure Prediction	Kaggle

✅ 必做部分

模块	要求
数据处理	使用 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	航空公司情感分析
IMDB 50K Movie Reviews	Kaggle	电影评论情感
SMS Spam Collection	Kaggle	垃圾短信分类
Consumer Complaints	Kaggle	投诉分流

✅ 必做部分

模块	要求
数据处理	文本清洗要「克制」，说明预处理策略；使用 Pandera 定义 Schema
机器学习	基线 TF-IDF + LogReg；达到 Accuracy ≥ 0.85 或 Macro-F1 ≥ 0.80
Agent	实现「分类 → 解释 → 生成处置方案」流程；输出结构化（Pydantic）

---

Level 3｜高阶：不平衡/多表/时序 + 多步决策

📌 真实世界约束

目标：处理更复杂的数据特性（极度不平衡、多表关联、时序预测），实现多步决策 Agent。

推荐数据集

数据集	链接	特点
Credit Card Fraud Detection	Kaggle	极度不平衡
IEEE-CIS Fraud Detection	Kaggle	多表/特征工程复杂
M5 Forecasting - Accuracy	Kaggle	时序预测
Instacart Market Basket	Kaggle	多表 + 推荐

✅ 必做部分

模块	要求
数据处理	明确主键/外键与 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

# 方法 A：Xcode 命令行工具（推荐）
xcode-select --install

# 方法 B：Homebrew
brew install git

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install git

验证安装

git --version
# 输出类似：git version 2.43.0

---

Git 基础操作

首次配置

# 设置用户名和邮箱（提交记录会显示）
git config --global user.name "你的姓名"
git config --global user.email "你的邮箱@example.com"

克隆仓库

# 组长创建仓库后，所有组员克隆
git clone http://hblu.top:3000/<用户名>/<项目名>.git
cd <项目名>

日常开发流程

# 1. 拉取最新代码（每次开始工作前）
git pull

# 2. 查看当前状态
git status

# 3. 添加修改的文件
git add .                    # 添加所有修改
git add src/train.py         # 或只添加特定文件

# 4. 提交修改
git commit -m "feat: 添加数据预处理模块"

# 5. 推送到远程仓库
git push

常用命令速查

命令	说明
git clone <url>	克隆远程仓库
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 文件，内容如下：

# ===== 环境变量（绝对不能提交！）=====
.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 是否生效

# 查看哪些文件会被 Git 忽略
git status --ignored

# 如果之前已经提交了不应提交的文件，需要先从 Git 中移除
git rm --cached .env          # 从 Git 移除但保留本地文件
git rm --cached -r __pycache__
git commit -m "chore: 移除不应提交的文件"

---

作业提交流程

1. 账号信息

账号已统一创建，请登录 hblu.top:3000/MachineLearning2025

项目	说明
用户名	st + 学号（如 st2024001）
初始密码	12345678（请登录后修改）
组织	MachineLearning2025

⚠️ 首次登录后请立即修改密码

2. 组长创建仓库

在 MachineLearning2025 组织下创建新仓库，命名格式：组号-项目名称（如 G01-ChurnPredictor）

3. 添加组员

Settings → Collaborators → 添加其他组员（使用 st+学号 搜索）

4. 提交检查清单

• .gitignore 已创建且包含必要规则
• .env.example 已提交，.env 未提交
• 没有提交 API Key 或敏感信息
• 没有提交大于 50MB 的文件

---

Day 4：自主设计

今日任务：

• 继续完善项目
• 完成 Agent 集成
• 准备 Streamlit Demo
• 撰写项目报告

建议里程碑：

• ML 模型完成并保存
• Agent 工具调用测试通过
• Streamlit Demo 可运行
• REPORT.md 初稿完成

---

Day 5：小组展示

展示流程

1. 教师机克隆你的仓库

   git clone http://hblu.top:3000/MachineLearning2025/<项目名>.git
   cd <项目名>
   

2. 安装依赖并运行

   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	锁文件已提交	依赖版本不确定

提交前测试方法

# 模拟干净环境测试
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）

⚠️ 所有分析、对比、决策逻辑都必须在 REPORT.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 最佳实践

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

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)$")

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

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 示例

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                 # 说明文档
├── REPORT.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 中包含以下内容：

## 团队成员

| 姓名 | 学号 | 贡献 |
|------|------|------|
| 张三 | 2024001 | 数据处理、模型训练 |
| 李四 | 2024002 | Agent 开发、Streamlit |
| 王五 | 2024003 | 报告撰写、测试 |

## 项目简介

（1-2 段描述项目目标、选用的数据集、解决的问题）

## 快速开始

（如何安装依赖、运行 demo）

## 开发心得

（遇到的主要困难、解决方案、对 AI 辅助编程的感受）

---

参考资料

核心工具文档

资源	链接	说明
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 工具）
• REPORT.md 说明了数据切分策略
• Demo 可以正常运行

---

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