Upload README.md with huggingface_hub

README.md

@@ -1,138 +1,135 @@
 ---
-language:
-- vi
+license: mit
+base_model: vinai/bartpho-syllable-base
 tags:
+- vietnamese
 - hate-speech-detection
-- vietnamese-nlp
 - text-classification
 - offensive-language-detection
-license: mit
 datasets:
-- vihsd
-base_model: vinai/bartpho-syllable-base
+- visolex/vihsd
+metrics:
+- accuracy
+- macro-f1
+- weighted-f1
+model-index:
+- name: bartpho-hsd
+  results:
+  - task:
+      type: text-classification
+      name: Hate Speech Detection
+    dataset:
+      name: ViHSD
+      type: hate-speech-detection
+    metrics:
+    - type: accuracy
+      value: 0.8985
+    - type: macro-f1
+      value: 0.6791
+    - type: weighted-f1
+      value: 0.8886
+    - type: macro-precision
+      value: 0.7664
+    - type: macro-recall
+      value: 0.6289
 ---
 
-# BARTpho
+# BARTpho: Hate Speech Detection for Vietnamese Text
 
-BARTpho fine-tuned cho bài toán phân loại Hate Speech tiếng Việt
+This model is a fine-tuned version of [vinai/bartpho-syllable-base](https://huggingface.co/vinai/bartpho-syllable-base) 
+on the **ViHSD (Vietnamese Hate Speech Detection Dataset)** for classifying Vietnamese text into three categories: CLEAN, OFFENSIVE, and HATE.
 
 ## Model Details
 
-### Model Type
-BARTpho (Bidirectional and Auto-Regressive Transformer cho tiếng Việt)
-
-### Base Model
-This model is fine-tuned from [vinai/bartpho-syllable-base](https://huggingface.co/vinai/bartpho-syllable-base)
+* **Base Model**: vinai/bartpho-syllable-base
+* **Description**: BARTpho fine-tuned cho bài toán phân loại Hate Speech tiếng Việt
+* **Architecture**: BARTpho (Bidirectional and Auto-Regressive Transformer cho tiếng Việt)
+* **Dataset**: ViHSD (Vietnamese Hate Speech Detection Dataset)
+* **Fine-tuning Framework**: HuggingFace Transformers + PyTorch
+* **Task**: Hate Speech Classification (3 classes)
 
-### Training Info
-- **Task**: Hate Speech Classification
-- **Language**: Vietnamese
-- **Labels**: 
-  - `0`: CLEAN (Normal content)
-  - `1`: OFFENSIVE (Mildly offensive content)
-  - `2`: HATE (Hate speech)
+### Hyperparameters
 
-## 📊 Model Performance
+* **Batch size**: `32`
+* **Learning rate**: `2e-5`
+* **Epochs**: `100`
+* **Max sequence length**: `256`
+* **Weight decay**: `0.01`
+* **Warmup steps**: `500`
+* **Early stopping patience**: `5`
+* **Optimizer**: AdamW
+* **Learning rate scheduler**: Cosine with warmup
 
-| Metric | Score |
-|--------|-------|
-| Accuracy | 0.8985 |
-| F1 Macro | 0.6791 |
-| F1 Weighted | 0.8886 |
+## Dataset
 
-## Model Description
+Model was trained on **ViHSD (Vietnamese Hate Speech Detection Dataset)** containing ~10,000 Vietnamese comments from social media.
 
-This model has been fine-tuned on the ViHSD (Vietnamese Hate Speech Dataset) to classify Vietnamese text into three categories: CLEAN, OFFENSIVE, and HATE.
+### Label Descriptions:
 
-### Architecture
-BARTpho (Bidirectional and Auto-Regressive Transformer cho tiếng Việt)
+* **CLEAN (0)**: Normal content without offensive language
+* **OFFENSIVE (1)**: Mildly offensive or inappropriate content  
+* **HATE (2)**: Hate speech, extremist language, severe threats
 
-The model combines the powerful pretrained representations with task-specific fine-tuning for effective hate speech detection in Vietnamese social media content.
+## Evaluation Results
 
-## How to Use
+The model was evaluated on test set with the following metrics:
 
-### 1. Using Transformers Pipeline
+* **Accuracy**: `0.8985`
+* **Macro-F1**: `0.6791`
+* **Weighted-F1**: `0.8886`
+* **Macro-Precision**: `0.7664`
+* **Macro-Recall**: `0.6289`
 
-```python
-from transformers import pipeline
-
-# Initialize the hate speech classifier
-classifier = pipeline(
-    "text-classification",
-    model="visolex/hate-speech-bartpho",
-    tokenizer="visolex/hate-speech-bartpho",
-    return_all_scores=True
-)
-
-# Classify text
-results = classifier("Văn bản tiếng Việt cần kiểm tra")
-print(results)
-```
+### Basic Usage
 
-### 2. Using AutoModel
+**⚠️ Important**: This model uses custom architecture. You must use `trust_remote_code=True` when loading.
 
 ```python
 from transformers import AutoTokenizer, AutoModelForSequenceClassification
 import torch
 
 # Load model and tokenizer
-model_name = "visolex/hate-speech-bartpho"
-tokenizer = AutoTokenizer.from_pretrained(model_name)
-model = AutoModelForSequenceClassification.from_pretrained(model_name)
-
-# Prepare text
-text = "Văn bản tiếng Việt cần kiểm tra"
-inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True, max_length=256)
-
-# Get predictions
-with torch.no_grad():
-    outputs = model(**inputs)
-    logits = outputs.logits
+model_name = "visolex/bartpho-hsd"
+
+# Load tokenizer
+# Note: For vocab-based models (bilstm, textcnn), use base model tokenizer or custom tokenization
+if "bartpho" in ["bilstm", "textcnn"]:
+    # These models use custom vocabulary - tokenizer from base model may not work
+    # You need to implement custom tokenization based on the model's vocabulary
+    print("⚠️  Note: This model uses custom vocabulary-based tokenization")
+    print("   Please refer to the model's documentation for tokenization details")
+    tokenizer = None
+else:
+    # Load tokenizer from the model repo (it will use base model's tokenizer)
+    tokenizer = AutoTokenizer.from_pretrained(model_name)
+
+# Load model with trust_remote_code=True (REQUIRED for custom models)
+model = AutoModelForSequenceClassification.from_pretrained(
+    model_name,
+    trust_remote_code=True  # ⚠️ REQUIRED: Allows loading custom model classes from models.py
+)
+
+# Classify text
+if tokenizer is not None:
+    text = "Văn bản tiếng Việt cần phân loại"
+    inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True)
     
-    # Get probabilities
-    probabilities = torch.nn.functional.softmax(logits, dim=-1)
+    with torch.no_grad():
+        outputs = model(**inputs)
+        predictions = torch.nn.functional.softmax(outputs.logits, dim=-1)
+        predicted_label = torch.argmax(predictions, dim=-1).item()
     
-    # Get predicted label
-    predicted_label = torch.argmax(probabilities, dim=-1).item()
-    confidence = probabilities[0][predicted_label].item()
-
-# Label mapping
-label_mapping = {
-    0: "CLEAN",
-    1: "OFFENSIVE",
-    2: "HATE"
-}
-
-print(f"Predicted: {label_mapping[predicted_label]} (Confidence: {confidence:.2%})")
-```
-
-### 3. Batch Processing
-
-```python
-from transformers import AutoTokenizer, AutoModelForSequenceClassification
-import torch
-
-model_name = "visolex/hate-speech-bartpho"
-tokenizer = AutoTokenizer.from_pretrained(model_name)
-model = AutoModelForSequenceClassification.from_pretrained(model_name)
-
-# List of texts to classify
-texts = [
-    "Bài viết rất hay và bổ ích",
-    "Đồ ngu người ta nói đúng mà",
-    "Cút đi đồ chó"
-]
-
-# Tokenize and predict
-inputs = tokenizer(texts, return_tensors="pt", padding=True, truncation=True, max_length=256)
-
-with torch.no_grad():
-    outputs = model(**inputs)
-    predictions = torch.argmax(outputs.logits, dim=-1)
-
-for text, pred in zip(texts, predictions):
-    label = ["CLEAN", "OFFENSIVE", "HATE"][pred.item()]
-    print(f"{text[:50]} -> {label}")
+    # Label mapping
+    label_names = {
+        0: "CLEAN",
+        1: "OFFENSIVE",
+        2: "HATE"
+    }
+    
+    print(f"Predicted label: {label_names[predicted_label]}")
+    print(f"Confidence scores: {predictions[0].tolist()}")
+else:
+    print("Please implement custom tokenization for this vocab-based model")
 ```
 
 ## Training Details
@@ -150,49 +147,10 @@ for text, pred in zip(texts, predictions):
 - **Learning Rate**: 2e-5
 - **Batch Size**: 32
 - **Max Length**: 256 tokens
-- **Epochs**: Optimized via early stopping
-
-### Preprocessing
-- Text normalization for Vietnamese
-- Special character handling
-- Emoji and slang processing
-
-## Evaluation Results
-
-Model evaluation metrics on the ViHSD test set: See Model Performance section above for details.
+- **Epochs**: 100 (with early stopping patience: 5)
+- **Weight Decay**: 0.01
+- **Warmup Steps**: 500
 
-### Label Distribution
-- **CLEAN (0)**: Normal content without offensive language
-- **OFFENSIVE (1)**: Mildly offensive or inappropriate content
-- **HATE (2)**: Hate speech, extremist language, severe threats
-
-## Use Cases
-
-- **Social Media Moderation**: Automatic detection of hate speech in Vietnamese social media platforms
-- **Content Filtering**: Filtering offensive content in Vietnamese text
-- **Research**: Studying hate speech patterns in Vietnamese online communities
-
-## Limitations and Considerations
-
-⚠️ **Important Limitations**:
-- Model trained primarily on social media data, may not generalize to formal text
-- Performance may vary with slang, code-switching, or regional dialects
-- Model reflects biases present in training data
-- Should be used as part of a larger moderation system, not sole decision-maker
-
-## Citation
-
-If you use this model in your research, please cite:
-
-```bibtex
-@software{vihsd_bartpho,
-  title = {BARTpho for Vietnamese Hate Speech Detection},
-  author = {ViSoLex Team},
-  year = {2024},
-  url = {https://huggingface.co/visolex/hate-speech-bartpho},
-  base_model = {vinai/bartpho-syllable-base}
-}
-```
 
 ## Contact & Support
 
@@ -206,6 +164,9 @@ This model is distributed under the MIT License.
 
 ## Acknowledgments
 
-- Base model trained by vinai
+- Base model: [vinai/bartpho-syllable-base](https://huggingface.co/vinai/bartpho-syllable-base)
 - Dataset: ViHSD (Vietnamese Hate Speech Detection Dataset)
 - Framework: [Hugging Face Transformers](https://huggingface.co/transformers)
+- ViSoLex Toolkit
+
+---