README.md

# ViClickbait-2025 – Vietnamese Clickbait Detection

Phân lớp clickbait tiếng Việt trên dataset ViClickbait-2025 (3.414 tin tức).
Baseline: **PhoBERT** · Model chính: **openai/gpt-oss-20b** (LoRA + BF16)

## Cấu trúc dự án

```
scripts/
├── prepare_data.py        ← Chia split 80/10/10 stratified, tạo cột text
├── train_phobert.py       ← Fine-tune PhoBERT baseline
├── train_gpt_oss_20b.py   ← Fine-tune openai/gpt-oss-20b với LoRA SFT
└── compare_results.py     ← So sánh kết quả 2 model
run_all.sh                 ← Chạy toàn bộ pipeline 1 lệnh
data/splits/               ← train.csv / val.csv / test.csv (tự sinh)
outputs/
├── phobert/               ← Checkpoint + test_results.json
└── gpt20b/                ← LoRA adapter + test_results.json
```

## Dataset

| | |
|---|---|
| Nguồn | [Mendeley Data – 3wc46bfcjc](https://data.mendeley.com/datasets/3wc46bfcjc/1) |
| Tổng mẫu | 3.414 tin tức tiếng Việt |
| Nhãn | `non-clickbait` (2349) / `clickbait` (1065) |
| Split | Train **2.731** / Val **341** / Test **342** (stratified 80/10/10) |
| Text input | `title [SEP] lead_paragraph` |

## Cài đặt

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
```

## Chạy nhanh – Toàn bộ pipeline

```bash
# Đặt đường dẫn CSV
export CSV_PATH=/tmp/dataset_nlp/clickbait_dataset_vietnamese.csv

# Full pipeline: PhoBERT + GPT-OSS-20B + So sánh
bash run_all.sh

# Chỉ PhoBERT (nếu GPU nhỏ)
bash run_all.sh --skip_gpt
```

## Demo Streamlit (PhoBERT + GPT-OSS-20B local)

### A. Clone repo tu Hugging Face

```bash
git clone https://huggingface.co/minhy112/ViClickbait-2025
cd ViClickbait-2025
```

Neu repo private/gated:

```bash
git clone https://user:HF_TOKEN@huggingface.co/minhy112/ViClickbait-2025
cd ViClickbait-2025
```

### B. Tao moi truong va cai dat dependencies

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install torchvision
```

### C. Khoi chay demo tren server/Vast

```bash
export HF_TOKEN=your_hf_token
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

streamlit run streamlit_app.py \
    --server.address 0.0.0.0 \
    --server.port 8501 \
    --server.fileWatcherType none
```

### D. Mo demo tren Mac local

Neu port 8501 da mo public, co the mo truc tiep:

```text
http://SERVER_IP:8501
```

Khuyen nghi dung SSH tunnel:

```bash
ssh -N -p SSH_PORT root@SERVER_IP -L 8501:localhost:8501
```

Sau do mo tren Mac:

```text
http://localhost:8501
```

Neu muon map sang cong local khac:

```bash
ssh -N -p SSH_PORT root@SERVER_IP -L 8080:localhost:8501
```

Mo:

```text
http://localhost:8080
```

### E. Cau hinh trong app

- PhoBERT path mac dinh: `outputs/phobert/checkpoint-430`
- GPT base model id mac dinh: `openai/gpt-oss-20b`
- GPT adapter path mac dinh: `outputs/gpt20b/checkpoint-430`
- GPT score hien thi dang xac suat 0-1 (softmax tren 2 log-score)
- Co the nap sample nhanh tu `data/splits/test.csv`

### F. Troubleshooting nhanh

1. Loi CUDA out of memory:

```bash
pkill -f "streamlit run streamlit_app.py" || true
pkill -f "python.*streamlit_app.py" || true
nvidia-smi
```

Sau do chay lai lenh Streamlit o buoc C.

2. Loi model dang nam o CPU/GPU khac nhau:
- Ban code hien tai da ep GPT len cung 1 GPU de tranh mismatch.

3. Khong load duoc base model GPT:
- Them `HF_TOKEN` hop le neu model bi gated.

4. Khong vao duoc web tu Mac:
- Kiem tra dung SSH port cua Vast.
- Kiem tra tunnel dang mo va khong bi xung dot cong local.

### G. Push thay doi len Hugging Face repo

```bash
git add README.md streamlit_app.py requirements.txt
git commit -m "Add Streamlit local demo for PhoBERT + GPT-OSS-20B and setup docs"
git push
```

## Chạy từng bước

### 1. Chuẩn bị dữ liệu
```bash
python3 scripts/prepare_data.py \
    --csv  /tmp/dataset_nlp/clickbait_dataset_vietnamese.csv \
    --out_dir data/splits
```

### 2. Huấn luyện PhoBERT baseline
```bash
python3 scripts/train_phobert.py \
    --data_dir   data/splits \
    --output_dir outputs/phobert \
    --model_name vinai/phobert-base-v2 \
    --batch_size 32 --lr 2e-5 --epochs 10 \
    --patience 5
```

### 3. Huấn luyện GPT-OSS-20B (LoRA SFT)
```bash
python3 scripts/train_gpt_oss_20b.py \
    --data_dir   data/splits \
    --output_dir outputs/gpt20b \
    --batch_size 4 --grad_accum 8 \
    --lr 2e-5 --epochs 10 \
    --patience 3 --lora_r 32 --lora_alpha 64
```

### 4. So sánh kết quả
```bash
python3 scripts/compare_results.py \
    --phobert_dir outputs/phobert \
    --gpt_dir     outputs/gpt20b
```

## Thông số kỹ thuật

| | PhoBERT | GPT-OSS-20B |
|---|---|---|
| Model | `vinai/phobert-base-v2` | `openai/gpt-oss-20b` |
| Phương pháp | Full fine-tune (SeqCls) | LoRA SFT (Generative, BF16) |
| LoRA | Không | r=32, alpha=64 |
| VRAM cần | ~4 GB | ~40 GB (BF16) |
| Batch hiệu quả | 32 | 32 (4 × grad_accum 8) |
| LR | 2e-5 | 2e-5 |
| Epochs (max) | 10 | 10 |
| Optimizer | AdamW | AdamW |
| Metrics | Accuracy, F1, Precision, Recall | ← như nhau |
| Early stopping | patience=5 | patience=3 |