270 lines
8.8 KiB
Markdown
270 lines
8.8 KiB
Markdown
# 垃圾短信分类系统
|
||
|
||
|
||
> **机器学习 (Python) 课程设计**
|
||
|
||
|
||
## 👥 团队成员
|
||
|
||
|
||
| 姓名 | 学号 | 贡献 |
|
||
|------|------|------|
|
||
| 朱指乐 | 2311020135 | 数据处理、模型训练 |
|
||
| 肖康 | 2311020125 | Agent 开发、LLM 服务 |
|
||
| 龙思富 | 2311020114 | 可视化、优化streamlit应用、文档撰写|
|
||
|
||
|
||
## 📝 项目简介
|
||
|
||
|
||
本项目是一个基于**传统机器学习 + LLM + Agent**的垃圾短信分类系统，旨在实现可落地的智能预测与行动建议。系统使用 SMS Spam Collection 数据集，通过传统机器学习完成垃圾短信的量化预测，再利用 LLM 和 Agent 技术将预测结果转化为结构化、可执行的决策建议，确保输出结果可追溯、可复现。
|
||
|
||
|
||
## 🚀 快速开始
|
||
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone http://hblu.top:3000/MachineLearning2025/sms-castle-walls.git
|
||
cd sms-castle-walls
|
||
|
||
# 安装依赖
|
||
pip install uv -i https://mirrors.aliyun.com/pypi/simple/
|
||
uv config set index-url https://mirrors.aliyun.com/pypi/simple/
|
||
uv sync
|
||
|
||
# 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 填入 API Key
|
||
|
||
# 运行 Demo
|
||
uv run streamlit run src/streamlit_app.py
|
||
```
|
||
|
||
|
||
## 1️⃣ 问题定义与数据
|
||
|
||
|
||
### 1.1 任务描述
|
||
|
||
|
||
本项目是一个二分类任务，目标是自动识别垃圾短信（spam）和正常短信（ham）。业务目标是构建一个高准确率、可解释的垃圾短信分类系统，帮助用户有效过滤垃圾信息，提升信息安全和用户体验。
|
||
|
||
|
||
### 1.2 数据来源
|
||
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 数据集名称 | SMS Spam Collection |
|
||
| 数据链接 | `https://www.kaggle.com/datasets/uciml/sms-spam-collection-dataset` |
|
||
| 样本量 | 5,572 条 |
|
||
| 特征数 | 1 个（短信文本） |
|
||
|
||
### 1.3 批量分析测试数据
|
||
|
||
项目中提供了 [email_data.csv](file:///d:/sms-castle-walls/email_data.csv) 文件，该数据集包含多条中英文测试短信。该数据集可以用于系统的**批量文件分析处理**功能，验证系统对批量文件的自动化分析能力。
|
||
|
||
|
||
### 1.4 数据切分与防泄漏
|
||
|
||
|
||
数据按 8:2 比例分割为训练集和测试集，确保模型在独立的测试集上进行评估。在数据预处理和特征工程阶段，所有操作仅在训练集上进行，避免信息泄漏到测试集。使用 TF-IDF 进行文本向量化时，同样严格遵循先训练后应用的原则。
|
||
|
||
|
||
## 2️⃣ 机器学习流水线
|
||
|
||
|
||
### 2.1 基线模型
|
||
|
||
|
||
| 模型 | 指标 | 结果 |
|
||
|------|------|------|
|
||
| Logistic Regression | 准确率 | 0.978 |
|
||
| Logistic Regression | F1 分数（Macro） | 0.959 |
|
||
|
||
|
||
### 2.2 进阶模型
|
||
|
||
|
||
| 模型 | 指标 | 结果 |
|
||
|------|------|------|
|
||
| LightGBM | 准确率 | 0.985 |
|
||
| LightGBM | F1 分数（Macro） | 0.971 |
|
||
|
||
|
||
### 2.3 模型性能对比
|
||
|
||
|
||
#### 混淆矩阵对比
|
||
|
||
下面是两个模型在测试集上的混淆矩阵对比：
|
||
|
||
**Logistic Regression 混淆矩阵**
|
||
|
||
|
||
|
||
**LightGBM 混淆矩阵**
|
||
|
||
|
||
|
||
|
||
#### 对比分析
|
||
|
||
1. **Logistic Regression**：
|
||
- 真阳性（TP）：136（正确分类的垃圾短信）
|
||
- 真阴性（TN）：957（正确分类的正常短信）
|
||
- 假阳性（FP）：12（正常短信被误判为垃圾短信）
|
||
- 假阴性（FN）：9（垃圾短信被误判为正常短信）
|
||
|
||
2. **LightGBM**：
|
||
- 真阳性（TP）：129（正确分类的垃圾短信）
|
||
- 真阴性（TN）：960（正确分类的正常短信）
|
||
- 假阳性（FP）：9（正常短信被误判为垃圾短信）
|
||
- 假阴性（FN）：16（垃圾短信被误判为正常短信）
|
||
|
||
3. **性能差异**：
|
||
- LightGBM 在正常短信的分类上表现略好（TN 更高，FP 更低）
|
||
- Logistic Regression 在垃圾短信的分类上表现略好（TP 更高，FN 更低）
|
||
- 整体而言，两个模型的性能都非常优秀，准确率都在 97% 以上
|
||
|
||
|
||
### 2.4 误差分析
|
||
|
||
|
||
模型在以下类型的样本上表现相对较差：
|
||
1. 包含大量特殊字符或缩写的短信
|
||
2. 内容模糊、边界不清的促销短信
|
||
3. 混合中英文的短信
|
||
4. 模仿正常短信格式的垃圾短信
|
||
|
||
这主要是因为文本特征提取方法（TF-IDF）对语义理解有限，无法完全捕捉复杂的语言模式和上下文信息。
|
||
|
||
|
||
## 3️⃣ Agent 实现
|
||
|
||
|
||
### 3.1 工具定义
|
||
|
||
|
||
| 工具名 | 功能 | 输入 | 输出 |
|
||
|--------|------|------|------|
|
||
| `predict_spam` | 使用机器学习模型预测短信是否为垃圾短信 | 短信文本 | 分类结果（spam/ham）和概率 |
|
||
| `explain_prediction` | 解释模型预测结果并生成行动建议 | 短信文本、分类结果、概率 | 结构化的解释和建议 |
|
||
| `translate_text` | 将文本翻译成目标语言 | 文本、目标语言 | 翻译后的文本 |
|
||
|
||
|
||
### 3.2 决策流程
|
||
|
||
|
||
Agent 按照以下流程执行任务：
|
||
1. 接收用户提供的短信文本
|
||
2. 使用 `predict_spam` 工具进行分类预测
|
||
3. 使用 `explain_prediction` 工具解释分类结果并生成行动建议
|
||
4. 如果短信为英文，可选择使用 `translate_text` 工具翻译成中文
|
||
5. 向用户提供清晰、完整的分类结果、解释和建议
|
||
|
||
|
||
### 3.3 案例展示
|
||
|
||
|
||
**输入**：
|
||
```
|
||
Free entry in 2 a wkly comp to win FA Cup final tkts 21st May 2005. Text FA to 87121 to receive entry question(std txt rate)T&C's apply 08452810075over18's
|
||
```
|
||
|
||
**输出**：
|
||
```json
|
||
{
|
||
"classification": {
|
||
"label": "spam",
|
||
"probability": {
|
||
"spam": 0.98,
|
||
"ham": 0.02
|
||
}
|
||
},
|
||
"explanation": {
|
||
"content_summary": "这是一条关于免费赢取足总杯决赛门票的竞赛广告短信",
|
||
"classification_reason": "短信包含'Free entry'、'win'、'comp'等典型的垃圾短信关键词，且提供了需要用户回复的电话号码，符合垃圾短信的特征",
|
||
"confidence_level": "高",
|
||
"confidence_explanation": "模型以98%的概率将其分类为垃圾短信，基于文本中的垃圾短信特征词汇和结构",
|
||
"suggestions": ["不要回复此短信，避免产生额外费用", "将此号码加入黑名单", "删除该短信"]
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## 4️⃣ 系统特色
|
||
|
||
### 4.1 UI 界面风格
|
||
|
||
本系统的 Web 界面采用了独特的**欧洲中世纪风格**（Medieval Style）。通过精心设计的 CSS 样式，界面融合了深色古堡背景、金色边框以及复古的衬线字体，旨在为用户提供一种“在城堡中审阅密信”的沉浸式操作体验。
|
||
|
||
|
||
## 5️⃣ 开发心得
|
||
|
||
|
||
### 4.1 主要困难与解决方案
|
||
|
||
|
||
1. **文本特征提取**：原始文本数据难以直接用于机器学习模型，解决方案是使用 TF-IDF 进行文本向量化，将文本转化为数值特征。
|
||
2. **模型可解释性**：传统机器学习模型的预测结果缺乏可解释性，解决方案是集成 LLM 服务，对模型预测结果进行自然语言解释。
|
||
3. **API 集成与错误处理**：LLM API 调用可能会遇到各种错误，解决方案是实现完善的错误处理机制，确保系统稳定性。
|
||
|
||
|
||
### 4.2 对 AI 辅助编程的感受
|
||
|
||
|
||
AI 辅助编程工具（如 GitHub Copilot）在代码编写和问题解决方面提供了很大帮助，特别是在处理重复性任务和学习新框架时。它可以快速生成代码模板，提供解决方案建议，显著提高开发效率。但同时也需要注意，AI 生成的代码可能存在错误或不符合项目规范，需要人工仔细检查和调试。
|
||
|
||
|
||
### 4.3 局限与未来改进
|
||
|
||
|
||
1. **模型性能**：当前模型在处理复杂语言模式和上下文理解方面仍有提升空间，可以考虑使用更先进的文本表示方法（如 BERT）。
|
||
2. **多语言支持**：目前系统主要支持中英文短信，未来可以扩展到更多语言。
|
||
3. **实时性**：可以优化模型推理速度，实现实时分类功能。
|
||
4. **用户界面**：可以进一步改进 Streamlit 应用的用户体验，增加更多交互功能和可视化效果。
|
||
|
||
|
||
## 技术栈
|
||
|
||
|
||
| 组件 | 技术 | 版本要求 |
|
||
|------|------|----------|
|
||
| 项目管理 | 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>=2.0.0 |
|
||
| 可视化 | streamlit | >=1.20.0 |
|
||
| 文本处理 | nltk | >=3.8.0 |
|
||
|
||
|
||
## 许可证
|
||
|
||
|
||
MIT License
|
||
|
||
|
||
## 致谢
|
||
|
||
|
||
- 感谢 [DeepSeek](https://www.deepseek.com/) 提供的 LLM API
|
||
- 感谢 Kaggle 提供的 [SMS Spam Collection](https://www.kaggle.com/datasets/uciml/sms-spam-collection-dataset) 数据集
|
||
- 感谢所有开源库的贡献者
|
||
|
||
|
||
## 联系方式
|
||
|
||
|
||
如有问题或建议，欢迎通过以下方式联系：
|
||
|
||
- 项目地址：[http://hblu.top:3000/MachineLearning2025/CourseDesign](http://hblu.top:3000/MachineLearning2025/CourseDesign)
|
||
- 邮箱：xxxxxxxxxx@gmail.com
|
||
|
||
|
||
---
|
||
|
||
**© 2026 垃圾短信分类系统 | 基于传统机器学习 + LLM + Agent** |