202 lines
6.7 KiB
Markdown
202 lines
6.7 KiB
Markdown
# 垃圾短信分类系统
|
||
|
||
## 项目概述
|
||
|
||
本项目是一个基于**传统机器学习 + 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. 安装依赖
|
||
|
||
```bash
|
||
# 安装 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 密钥
|
||
|
||
```bash
|
||
# 复制环境变量示例文件
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，填入你的 DeepSeek API Key
|
||
# DEEPSEEK_API_KEY="your-key-here"
|
||
```
|
||
|
||
### 3. 运行应用
|
||
|
||
#### 方式 A：Streamlit 可视化应用（推荐）
|
||
|
||
```bash
|
||
uv run streamlit run src/streamlit_app.py
|
||
```
|
||
|
||
#### 方式 B：命令行 Agent Demo
|
||
|
||
```bash
|
||
uv run python src/agent_app.py
|
||
```
|
||
|
||
#### 方式 C：运行模型训练
|
||
|
||
```bash
|
||
uv run python src/models/train.py
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
### 1. Streamlit 应用
|
||
|
||
启动 Streamlit 应用后，你可以：
|
||
|
||
- **单条短信分类**：在左侧输入框中输入短信内容，点击「开始分类」按钮，系统将返回分类结果、解释和建议
|
||
- **批量分类**：上传包含 `text` 列的 CSV 文件，系统将自动对所有短信进行分类
|
||
- **模型选择**：在侧边栏选择使用 LightGBM 或 Logistic Regression 模型
|
||
- **语言选择**：在侧边栏选择输出结果的语言（中文/英文）
|
||
- **重新训练模型**：在「模型训练」展开栏中点击「重新训练模型」按钮
|
||
|
||
### 2. 命令行使用
|
||
|
||
```python
|
||
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](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)
|
||
- 邮箱：your-email@example.com
|
||
|
||
---
|
||
|
||
**© 2026 垃圾短信分类系统 | 基于传统机器学习 + LLM + Agent** |