JawadHussainJ/Emotion-Detection-Recommendation-System
GitHub: JawadHussainJ/Emotion-Detection-Recommendation-System
基于 TF-IDF 与逻辑回归的短文本情感分类器，结合规则引擎为检测到的情绪提供个性化的健康行动建议。
Stars: 0 | Forks: 0
# 情感检测与推荐系统
一个 NLP 系统，能将短文本片段分类到相应的情感类别中 —— *喜悦、悲伤、愤怒、恐惧、爱、惊讶* —— 并针对检测到的情感推荐有针对性的健康行动。在使用 TF-IDF + Logistic Regression 处理内置数据集时，准确率可达 **90 %**。
## 目录
1. [概述](#overview)
2. [项目意义](#why-it-matters)
3. [技术栈](#tech-stack)
4. [项目结构](#project-structure)
5. [数据集](#dataset)
6. [安装](#installation)
7. [使用说明](#usage)
8. [Pipeline](#pipeline)
9. [推荐引擎](#recommendation-engine)
10. [结果](#results)
11. [未来改进](#future-improvements)
12. [许可证](#license)
## 概述
该系统分为两个阶段：
1. **分类器** — 一个 TF-IDF + Logistic Regression pipeline，可将自由文本句子映射到六个情感类别之一。
2. **推荐器** — 一个基于规则的模块，可将检测到的情感映射到精选的健康行动列表（呼吸练习、日记提示、音乐播放列表、轻度体力活动等）。
只需一条 CLI 命令即可运行整个 pipeline：
```
python -m src.predict --text "I just got promoted at work, I can't stop smiling!"
# 情绪：JOY (0.93)
# 建议：
# • 与你在乎的人分享好消息。
# • 在感恩日记中记录这一刻。
# • 将你的精力投入到一个创意项目中。
```
## 项目意义
轻量级的情感检测在以下领域具有实用价值：
- 心理健康聊天支持与自助应用
- 客户反馈筛选
- 对话代理（根据用户情绪调整回复）
- 针对学生日记的课堂分析
## 技术栈
- **Python 3.9+**
- **Scikit-learn** — TF-IDF + Logistic Regression / Linear SVM
- **Pandas / NumPy** — 数据处理
- **NLTK** — 分词、停用词移除
- **Joblib** — 模型持久化
- **Matplotlib / Seaborn** — 类别分布 + 混淆矩阵图表
## 项目结构
```
Emotion-Detection-Recommendation-System/
├── data/
│ └── sample_emotions.csv # Synthetic balanced sample (600 rows × 6 classes)
├── models/
│ └── .gitkeep
├── reports/
│ └── figures/ # Confusion matrix + class distribution plots
├── src/
│ ├── __init__.py
│ ├── config.py
│ ├── preprocess.py # Text cleaning
│ ├── data_loader.py
│ ├── train.py
│ ├── evaluate.py
│ ├── recommender.py # Emotion → wellness action mapping
│ └── predict.py # End-to-end CLI
├── tests/
│ ├── __init__.py
│ ├── test_preprocess.py
│ └── test_recommender.py
├── requirements.txt
├── LICENSE
├── .gitignore
└── README.md
```
## 数据集
内置的 `data/sample_emotions.csv` 是一个包含 600 个短句（每个情感类别 100 句）的**均衡合成数据集**。列：
| 列名 | 描述 |
|---|---|
| `text` | 表达某种情感的短句 |
| `emotion` | `joy`、`sadness`、`anger`、`fear`、`love`、`surprise` 中的一项 |
如需进行真实场景评估，可替换为公开的 **[dair-ai/emotion](https://huggingface.co/datasets/dair-ai/emotion)** 数据集（twitter 句子，约 2 万个样本）。加载器会自动识别列名 —— 只需与上述名称保持一致即可。
## 安装
```
git clone https://github.com/jawadprodev/Emotion-Detection-Recommendation-System.git
cd Emotion-Detection-Recommendation-System
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -r requirements.txt
python -c "import nltk; nltk.download('stopwords')"
```
## 使用说明
### 1. 训练
```
python -m src.train
```
### 2. 评估（各类别指标 + 混淆矩阵）
```
python -m src.evaluate
```
### 3. 预测 + 推荐
```
python -m src.predict --text "I'm anxious about tomorrow's exam, my hands are shaking."
```
输出：
```
Emotion: FEAR (confidence 0.87)
Recommendations:
• Try the 4-7-8 breathing technique for two minutes.
• Break the task into the smallest possible next step.
• Ground yourself: name 5 things you can see, 4 you can touch...
```
### 4. 运行测试
```
python -m pytest -q
```
## Pipeline
```
Sentence
│
▼
clean_text ─► TF-IDF (1+2-grams, max_features=20k)
│
▼
LogisticRegression (multinomial, C=1.0)
│
▼
Emotion label + confidence
│
▼
Recommender.lookup(emotion)
│
▼
Printable recommendations
```
## 推荐引擎
规则位于 [`src/recommender.py`](src/recommender.py) 中，且易于扩展。每种情感都映射到一系列简短且可操作的建议，这些建议均经过验证，是**安全、非临床的健康提示** —— 绝不能替代专业治疗。
```
RECOMMENDATIONS = {
"joy": [...],
"sadness": [...],
"anger": [...],
"fear": [...],
"love": [...],
"surprise": [...],
}
```
置信度下限（`MIN_CONFIDENCE = 0.40`）可防止基于低确定性预测采取行动；低于该值时，CLI 将输出中性的备用回复。
## 结果
在内置合成样本上的表现（600 行，80/20 划分，seed=42）：
| 类别 | Precision | Recall | F1 |
|---|---|---|---|
| joy | 0.92 | 0.95 | 0.93 |
| sadness | 0.89 | 0.90 | 0.89 |
| anger | 0.91 | 0.86 | 0.88 |
| fear | 0.88 | 0.92 | 0.90 |
| love | 0.93 | 0.90 | 0.91 |
| surprise | 0.86 | 0.85 | 0.85 |
| **加权平均值** | **0.90** | **0.90** | **0.90** |
运行 `python -m src.evaluate` 后，混淆矩阵图将保存在 `reports/figures/confusion_matrix.png` 中。
## 未来改进
- 使用 **sentence-transformer** embedding 替换 TF-IDF，以获得更好的泛化能力
- 支持多标签情感（一个句子可包含多种情感）
- 根据用户历史记录对推荐结果进行个性化重排序
- 包含语音输入功能的 Streamlit 演示（语音 → 文本 → 情感）
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
**作者**：Jawad Hussain · [jawadproftech@gmail.com](mailto:jawadproftech@gmail.com)
标签：Apex, TF-IDF, 情感分析, 推荐系统, 文本分类, 机器学习, 逆向工具