Vietnamese Review Intelligence Platform

Vietnamese Review Intelligence Platform - Hệ thống phân tích và dự đoán sentiment cho review thương mại điện tử Shopee/e-commerce tiếng Việt.

---

Mô tả bài toán

Trong thương mại điện tử, review sản phẩm là nguồn thông tin quan trọng giúp người mua và người bán hiểu rõ hơn về chất lượng sản phẩm/dịch vụ. Tuy nhiên, với hàng nghìn review mỗi ngày, việc phân tích thủ công là không khả thi.

Bài toán này xây dựng một hệ thống tự động:

• Phân loại sentiment: Positive (tích cực) vs Negative (tiêu cực)
• Nhận diện aspect: Giao hàng, đóng gói, chất lượng, giá cả,...
• API dự đoán: Cung cấp REST API cho ứng dụng khác sử dụng
• Dashboard trực quan: Trình bày kết quả phân tích

---

Mục tiêu project

1. Làm sạch dữ liệu review tiếng Việt (preprocessing pipeline)
2. Khám phá dữ liệu (EDA)
3. Train baseline sentiment classification model (TF-IDF + ML)
4. Nhận diện aspect trong review (keyword-based)
5. Xây dựng FastAPI để dự đoán sentiment
6. Tạo Streamlit dashboard để demo
7. Lưu model, viết docs, chuẩn bị đưa lên GitHub/CV

---

Dataset

File	Mô tả	Dòng
data/raw/reviews_accent.csv	Review gốc (có dấu tiếng Việt)	~9,591
data/raw/reviews_no_accent.csv	Review không dấu	~1,340
data/processed/cleaned_reviews.csv	Review đã làm sạch	~9,599
data/processed/final_reviews.csv	Review + aspect	~9,599

Các cột chính:

Cột	Mô tả
id	ID duy nhất của review
review	Văn bản review gốc
rating	Điểm đánh giá (1-5 sao)
label	Nhãn sentiment: positive hoặc negative
clean_review	Review đã được làm sạch
aspect	Danh sách aspect (trong final_reviews.csv)

Lưu ý: Dataset không có nhãn neutral. Rating 3 được gán theo heuristic.

---

Pipeline

data/raw/                    ← Raw data
    ↓ [01_data_understanding]
data/raw/                    ← Exploratory analysis
    ↓ [02_data_cleaning]
data/processed/cleaned_reviews.csv
    ↓ [04_baseline_model]
models/sentiment_model.pkl   ← Linear SVM model
models/tfidf_vectorizer.pkl  ← TF-IDF vectorizer
    ↓ [03_eda]
reports/figures/             ← EDA charts
    ↓ [05_model_evaluation]
reports/error_analysis.csv
    ↓ [06_aspect_detection]
data/processed/final_reviews.csv
    ↓ [src/predict.py]
API + Dashboard

---

Project Structure

vietnamese-review-intelligence/
├── api/
│   ├── main.py          # FastAPI app
│   └── schemas.py       # Request/Response schemas
├── dashboard/
│   └── app.py           # Streamlit dashboard
├── data/
│   ├── external/         # Tài nguyên bên ngoài
│   │   ├── aspect_keywords.csv     # Từ khóa aspect
│   │   ├── slang_dictionary.csv   # Từ điển slang
│   │   └── vietnamese_stopwords.txt
│   ├── processed/        # Dữ liệu đã xử lý
│   │   ├── cleaned_reviews.csv
│   │   └── final_reviews.csv      # + aspect
│   └── raw/              # Dữ liệu gốc
├── docs/                 # Tài liệu dự án
│   ├── api.md
│   ├── aspect_detection.md
│   ├── baseline_model.md
│   ├── dashboard.md
│   ├── data_cleaning.md
│   ├── data_understanding.md
│   ├── eda_report.md
│   ├── model_evaluation.md
│   └── prediction_module.md
├── models/               # Model artifacts
│   ├── sentiment_model.pkl
│   └── tfidf_vectorizer.pkl
├── notebooks/            # Jupyter notebooks
│   ├── 01_data_understanding.ipynb
│   ├── 02_data_cleaning.ipynb
│   ├── 03_eda.ipynb
│   ├── 04_baseline_model.ipynb
│   ├── 05_model_evaluation.ipynb
│   └── 06_aspect_detection.ipynb
├── reports/
│   ├── figures/          # Biểu đồ
│   │   ├── aspect_distribution.png
│   │   ├── confusion_matrix.png
│   │   ├── label_distribution.png
│   │   ├── rating_distribution.png
│   │   ├── review_length_by_label.png
│   │   ├── top_words_overall.png
│   │   └── word_count_by_label.png
│   ├── error_analysis.csv
│   └── model_comparison.csv
├── src/
│   ├── aspect_detection.py   # Aspect detection module
│   ├── convert_json_to_csv.py # JSON → CSV converter
│   ├── data_preprocessing.py  # Preprocessing functions
│   ├── evaluate_model.py      # Model evaluation script
│   ├── predict.py            # Prediction module
│   └── train_baseline.py     # Baseline training script
├── .gitignore
├── README.md
└── requirements.txt

---

Các bước đã làm

1. Data Understanding (notebooks/01_data_understanding.ipynb)

• Khám phá schema dữ liệu, kiểu dữ liệu từng cột.
• Chọn dataset có dấu (reviews_accent.csv) làm dữ liệu chính.

2. Data Cleaning (notebooks/02_data_cleaning.ipynb + src/data_preprocessing.py)

• Loại bỏ dòng trùng lặp, dòng thiếu.
• Chuẩn hóa text: lowercase, bỏ ký tự đặc biệt (giữ tiếng Việt).
• Chuẩn hóa từ viết tắt (slang) bằng từ điển.
• Chuẩn hóa ký tự lặp (okkkk → ok).
• Lưu cleaned_reviews.csv.

3. EDA (notebooks/03_eda.ipynb + docs/eda_report.md)

• Phân tích phân bố label, rating.
• Word count analysis theo sentiment.
• Top words visualization.
• Nhận xét: class imbalance (negative nhiều hơn positive).

4. Baseline Model (notebooks/04_baseline_model.ipynb + src/train_baseline.py)

• TF-IDF vectorization (5000 features, ngram 1-2).
• Train 3 model: Logistic Regression, Naive Bayes, Linear SVM.
• So sánh bằng accuracy, macro F1, weighted F1.
• Chọn Linear SVM làm model tốt nhất.

5. Model Evaluation (notebooks/05_model_evaluation.ipynb + src/evaluate_model.py)

• Accuracy: 94.06%
• Macro F1: 93.66%
• Confusion matrix visualization.
• Error analysis (114 lỗi / 1920 test samples).

6. Aspect Detection (notebooks/06_aspect_detection.ipynb + src/aspect_detection.py)

• 8 nhóm aspect: giao_hang, dong_goi, chat_luong, gia_ca, shop_service, bao_hanh, sai_mo_ta, hang_gia.
• Keyword rule-based detection.
• Tạo final_reviews.csv với cột aspect.

7. FastAPI (api/main.py)

• Endpoint POST /predict: Dự đoán sentiment + aspect.
• Endpoint GET /: Thông tin project.
• Endpoint GET /health: Health check.
• Swagger UI tại /docs.

8. Streamlit Dashboard (dashboard/app.py)

• KPI cards: tổng số review, rating TB, positive count, số aspect.
• Biểu đồ: Sentiment pie, Rating bar, Aspect distribution, Top words.
• Bộ lọc: theo sentiment, rating, aspect.
• Phần prediction: nhập review mới để dự đoán.

---

Kỹ thuật sử dụng

Kỹ thuật	Mô tả
Vietnamese NLP Preprocessing	Làm sạch text tiếng Việt, giữ dấu, chuẩn hóa slang
TF-IDF	Chuyển text thành vector số (5000 features, unigrams + bigrams)
Logistic Regression	Baseline classifier (accuracy: 93.18%)
Naive Bayes	Baseline classifier (accuracy: 92.40%)
Linear SVM	Best baseline classifier (accuracy: 94.06%)
Sentiment Classification	Phân loại positive/negative
Aspect Detection	Keyword rule-based, 8 nhóm aspect
FastAPI	REST API endpoint
Streamlit	Interactive dashboard
Plotly Express	Biểu đồ trực quan

---

Cách chạy project

1. Cài đặt thư viện

cd vietnamese-review-intelligence
pip install -r requirements.txt

2. Train / Retrain model

python src/train_baseline.py

3. Đánh giá model

python src/evaluate_model.py

4. Chạy Aspect Detection

python src/aspect_detection.py

5. Test Prediction Module

python src/predict.py

6. Chạy FastAPI

cd vietnamese-review-intelligence
uvicorn api.main:app --reload

API chạy tại: http://localhost:8000 Swagger UI: http://localhost:8000/docs

7. Chạy Dashboard

cd vietnamese-review-intelligence
streamlit run dashboard/app.py

Dashboard chạy tại: http://localhost:8501

---

Kết quả Model

So sánh các Model

Model	Accuracy	Macro F1	Weighted F1
Linear SVM	94.06%	93.66%	94.05%
Logistic Regression	93.18%	92.69%	93.15%
Naive Bayes	92.40%	91.95%	92.41%

Best Model: Linear SVM với accuracy 94.06% và macro F1 93.66%.

Classification Report (Linear SVM)

Label	Precision	Recall	F1-Score	Support
negative	0.95	0.96	0.95	1193
positive	0.93	0.91	0.92	727

Confusion Matrix

	Pred Negative	Pred Positive
Actual Negative	1144	49
Actual Positive	65	662

Phân bố Aspect

Aspect	Số lượng	Tỷ lệ
giao_hang	4,263	44.4%
chat_luong	4,073	42.4%
dong_goi	4,008	41.8%
shop_service	2,797	29.1%
gia_ca	1,836	19.1%
khac	1,492	15.5%
sai_mo_ta	897	9.3%
bao_hanh	161	1.7%
hang_gia	144	1.5%

---

Biểu đồ

Một số biểu đồ đã được tạo trong reports/figures/:

• confusion_matrix.png - Ma trận nhầm lẫn
• aspect_distribution.png - Phân bố aspect
• label_distribution.png - Phân bố sentiment
• rating_distribution.png - Phân bố rating
• top_words_overall.png - Top từ phổ biến
• word_count_by_label.png - Số từ theo sentiment

---

Hướng phát triển

Ngắn hạn

• PhoBERT: Fine-tune PhoBERT cho sentiment classification (thường đạt 95%+ accuracy trên tiếng Việt)
• Aspect-Level Sentiment: Xác định sentiment riêng cho từng aspect trong review
• Neutral Label: Thêm nhãn trung lập cho rating 3 hoặc sử dụng 3-class classification
• Stopword Removal: Thêm bước loại bỏ stopwords trong preprocessing

Trung hạn

• RAG Chatbot: Xây dựng chatbot hỏi đáp về sản phẩm dựa trên reviews (Retrieval Augmented Generation)
• Model Monitoring: Theo dõi độ chính xác model theo thời gian, phát hiện data drift
• Aspect Summary: Tự động tổng hợp ý kiến theo từng aspect (positive/negative %)

Dài hạn

• Deploy lên Cloud: Heroku, Render, AWS, hoặc Google Cloud Platform
• API Documentation: Thêm rate limiting, authentication (JWT)
• Multi-language Support: Mở rộng sang tiếng Anh, tiếng Trung
• Real-time Dashboard: Kết nối API với data stream từ Shopee

---

Ghi chú quan trọng khi push lên GitHub

Không push lên GitHub (đã có trong .gitignore)

• data/ - Dữ liệu lớn
• models/*.pkl - Model artifacts (nặng)
• reports/figures/ - Biểu đồ có thể regenerate
• __pycache__/

Khuyến nghị

Nếu muốn push model lên GitHub, có thể dùng Git LFS:

git lfs install
git lfs track "*.pkl"

Hoặc lưu model trên Google Drive / Hugging Face Hub và chia sẻ link trong README.

---

License

MIT License

Author

Vietnamese Review Intelligence Platform - Data Science + AI Engineering + Vietnamese NLP Project