sms-castle-walls/README.md

# 垃圾短信分类系统

## 项目概述

本项目是一个基于**传统机器学习 + 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**