垃圾短信分类系统

项目概述

本项目是一个基于传统机器学习 + LLM + Agent的垃圾短信分类系统，旨在实现可落地的智能预测与行动建议。系统使用传统机器学习完成可量化的垃圾短信预测任务，再用 LLM + Agent 把预测结果变成可执行的决策/建议，并保证输出结构化、可追溯、可复现。

技术栈

组件	技术	版本要求
项目管理	uv	最新版
数据处理	polars + pandas	polars>=0.20.0, pandas>=2.2.0
数据验证	pandera	>=0.18.0
机器学习	scikit-learn + lightgbm	sklearn>=1.3.0, lightgbm>=4.0.0
LLM 框架	openai	>=1.0.0
Agent 框架	pydantic + pydantic-ai	pydantic>=2.0.0
可视化	streamlit	>=1.20.0
文本处理	nltk	>=3.8.0

项目结构

├── src/
│   ├── data/              # 数据处理模块
│   │   ├── __init__.py
│   │   ├── preprocess.py  # 数据预处理
│   │   └── validation.py  # 数据验证
│   ├── models/            # 机器学习模型
│   │   ├── __init__.py
│   │   ├── train.py       # 模型训练
│   │   ├── evaluate.py    # 模型评估
│   │   └── predict.py     # 模型预测
│   ├── agent/             # Agent 模块
│   │   ├── __init__.py
│   │   ├── agent.py       # Agent 核心逻辑
│   │   └── tools.py       # Agent 工具定义
│   ├── llm/               # LLM 服务
│   │   ├── __init__.py
│   │   └── llm_service.py # DeepSeek API 集成
│   ├── main.py            # 主程序入口
│   └── streamlit_app.py   # Streamlit 可视化应用
├── data/                  # 数据集目录
│   └── spam.csv           # 垃圾短信数据集
├── models/                # 模型保存目录
├── .env.example           # 环境变量示例
├── .gitignore             # Git 忽略文件
├── pyproject.toml         # 项目配置
└── README.md              # 项目说明文档

快速开始

1. 安装依赖

# 安装 uv（如果尚未安装）
pip install uv -i https://mirrors.aliyun.com/pypi/simple/

# 配置 PyPI 镜像
uv config set index-url https://mirrors.aliyun.com/pypi/simple/

# 同步依赖
uv sync

2. 配置 API 密钥

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，填入你的 DeepSeek API Key
# DEEPSEEK_API_KEY="your-key-here"

3. 运行应用

方式 A：Streamlit 可视化应用（推荐）

uv run streamlit run src/streamlit_app.py

方式 B：命令行 Agent Demo

uv run python src/agent_app.py

方式 C：运行模型训练

uv run python src/models/train.py

使用说明

1. Streamlit 应用

启动 Streamlit 应用后，你可以：

• 单条短信分类：在左侧输入框中输入短信内容，点击「开始分类」按钮，系统将返回分类结果、解释和建议
• 批量分类：上传包含 text 列的 CSV 文件，系统将自动对所有短信进行分类
• 模型选择：在侧边栏选择使用 LightGBM 或 Logistic Regression 模型
• 语言选择：在侧边栏选择输出结果的语言（中文/英文）
• 重新训练模型：在「模型训练」展开栏中点击「重新训练模型」按钮

2. 命令行使用

from src.agent import agent

# 分类并解释短信
result = agent.classify_and_explain("Free entry in 2 a wkly comp to win FA Cup final tkts 21st May 2005.")

print(f"分类结果: {result['classification']['label']}")
print(f"分类概率: {result['classification']['probability']}")
print(f"解释: {result['explanation']['classification_reason']}")
print(f"建议: {result['explanation']['suggestions']}")

模型训练

训练流程

1. 数据加载：使用 Polars 加载 data/spam.csv 数据集
2. 数据预处理：
   • 清洗文本（去除 HTML 实体、特殊字符、多余空格）
   • 转换标签（spam → 1，ham → 0）
   • 数据验证（使用 Pandera 验证数据质量）
3. 数据分割：按 8:2 比例分割训练集和测试集
4. 特征工程：使用 TF-IDF 进行文本向量化
5. 模型训练：
   • 基线模型：Logistic Regression
   • 强模型：LightGBM
6. 模型评估：计算准确率、精确率、召回率、F1 分数
7. 模型保存：将训练好的模型保存到 models/ 目录

评估结果

模型	准确率	精确率（Macro）	召回率（Macro）	F1 分数（Macro）
Logistic Regression	0.978	0.964	0.954	0.959
LightGBM	0.985	0.974	0.968	0.971

系统架构

1. 数据层

• 数据加载：使用 Polars 高效加载和处理大规模数据
• 数据清洗：实现可复现的数据清洗流水线
• 数据验证：使用 Pandera 定义数据 Schema，确保数据质量

2. 模型层

• 特征工程：TF-IDF 文本向量化
• 模型训练：支持多种模型（LightGBM、Logistic Regression）
• 模型评估：全面的评估指标和可视化
• 模型管理：模型保存、加载和版本控制

3. LLM 层

• 文本翻译：将英文短信翻译成中文
• 结果解释：解释模型分类结果的原因
• 行动建议：根据分类结果生成可执行的建议
• 模式分析：分析垃圾短信的常见模式

4. Agent 层

• 工具定义：
  • predict_spam：使用机器学习模型预测短信是否为垃圾短信
  • explain_prediction：使用 LLM 解释分类结果并生成行动建议
  • translate_text：将文本翻译成目标语言
• Agent 逻辑：实现工具调用、结果整合和自然语言生成
• 结构化输出：确保输出结果可追溯、可复现

贡献指南

1. 朱指乐-仓库创建-项目初始化-数据获取-数据预处理-模型训练-模型评估-模型保存
2. 肖康-LLM服务-实现文本解释和建议生成功能-agent实现-工具调用-结构化输出
3. 龙思富-可视化-交互式可视化应用-文档编写

许可证

MIT License

致谢

• 感谢 DeepSeek 提供的 LLM API
• 感谢 Kaggle 提供的 SMS Spam Collection 数据集
• 感谢所有开源库的贡献者

联系方式

如有问题或建议，欢迎通过以下方式联系：

• 项目地址：http://hblu.top:3000/MachineLearning2025/CourseDesign
• 邮箱：your-email@example.com

---

© 2026 垃圾短信分类系统 | 基于传统机器学习 + LLM + Agent