Isa0/hatespeech

Hate Speech & Offensive Language Classifier (ONNX & INT8)

A lightweight, high-performance text classification model fine-tuned to distinguish between targeted hate speech, offensive language (profanity), and neutral content.

Both the Full Precision ONNX (FP32) and an ultra-compact Dynamic INT8 Quantized (8q) model are included for production-ready, ultra-low latency inference on CPUs and edge devices.

---

Key Features

• Fine-Grained Distinction: Accurately differentiates between general offensive language/profanity and genuinely dangerous hate speech.
• Dual ONNX Models:
  • model/hatespeech.onnx (FP32, ~255 MB)
  • model/hatespeech_int8.onnx (INT8 Quantized, ~64 MB, ~75% size reduction)
• Ultra-Low Latency: ~17 ms per sample on standard CPU with ONNX Runtime.
• Balanced Class Weighting: Trained with normalized inverse-frequency class weights to combat severe class imbalance (Hate speech is only ~5.8% of the training dataset).
• Anti-Overfitting Protection: Stratified split, weight decay ($0.01$), dropout ($0.2$), and early stopping monitoring Validation Macro F1.

---

Classes

Class ID	Label	Description
0	Hate Speech	Targeted hostility, incitement of violence, or dehumanization against protected groups.
1	Offensive Language	Swear words, slang, insults, and vulgarity without targeted hatred.
2	Neither	Neutral, positive, benign, or conversational language.

---

Benchmark & Model Specifications

Property	Raw ONNX	INT8 Quantized (Recommended)
File	model/hatespeech.onnx	model/hatespeech_int8.onnx
Precision	Float32	Quantized Int8 (Weights)
File Size	~255 MB	64.27 MB
Inference Engine	ONNX Runtime	ONNX Runtime
Average Latency (CPU)	~28 ms	~17 ms
Dynamic Inputs	Dynamic Batch & Sequence Length	Dynamic Batch & Sequence Length

---

Quickstart

1. Installation

Install dependencies using pip or uv:

pip install onnxruntime transformers numpy
# or using uv:
uv add onnxruntime transformers numpy

2. Standalone Inference with ONNX Runtime

You can run predictions with just ONNX Runtime and Hugging Face's AutoTokenizer:

import numpy as np
import onnxruntime as ort
from transformers import AutoTokenizer

LABEL_NAMES = {0: "Hate Speech", 1: "Offensive Language", 2: "Neither"}

# 1. Load ONNX model and tokenizer
model_path = "./model/hatespeech_int8.onnx"
session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
tokenizer = AutoTokenizer.from_pretrained("./model")

# 2. Tokenize input text
text = "I really love this community, everyone is so supportive and kind!"
inputs = tokenizer(text, padding=True, truncation=True, max_length=128, return_tensors="np")

# 3. Run inference
ort_inputs = {
    "input_ids": inputs["input_ids"].astype(np.int64),
    "attention_mask": inputs["attention_mask"].astype(np.int64),
}
logits = session.run(None, ort_inputs)[0]

# 4. Softmax probabilities
exp_logits = np.exp(logits - np.max(logits, axis=-1, keepdims=True))
probs = exp_logits / np.sum(exp_logits, axis=-1, keepdims=True)

pred_id = int(np.argmax(probs, axis=-1)[0])
print(f"Prediction: {LABEL_NAMES[pred_id]} ({probs[0][pred_id] * 100:.2f}%)")

---

CLI & Interactive Usage

This repository includes hatespeech.py for easy command-line testing:

# Run benchmark examples
python hatespeech.py

# Predict a custom sentence
python hatespeech.py --text "Stop being so annoying!"

# Start live interactive prompt
python hatespeech.py --interactive

# Use raw FP32 model instead of INT8
python hatespeech.py --raw

---

Training & Architecture

• Base Model: distilbert-base-uncased
• Dataset: Davidson et al. (2017) Automated Hate Speech and Offensive Language Detection (~24,783 annotated samples).
• Data Split: Stratified 80% Train, 10% Validation, 10% Holdout Test.
• Loss Function: nn.CrossEntropyLoss with balanced class weights: $$w_c = \frac{N_{\text{total}}}{N_{\text{classes}} \times N_c}$$
• Optimizer: AdamW (learning rate: $2 \times 10^{-5}$, weight decay: $0.01$).
• LR Scheduler: Linear warmup ($10%$ of steps) followed by linear decay.
• Early Stopping: Monitored on validation Macro F1 score with patience of 2 epochs.
• Quantization: Dynamic INT8 quantization executed using onnxruntime.quantization.quantize_dynamic.

To reproduce training:

python train.py --epochs 3 --batch_size 32

---

Citation

If you use this model or dataset in your research, please cite the underlying dataset by Davidson et al.:

@inproceedings{davidson2017automated,
  title={Automated Hate Speech Detection and the Problem of Offensive Language},
  author={Davidson, Thomas and Warmsley, Dana and Macy, Michael and Weber, Ingmar},
  booktitle={Proceedings of the 11th International AAAI Conference on Web and Social Media},
  series={ICWSM '17},
  pages={512--515},
  year={2017}
}

---

License

This repository and model card are released under the Creative Commons Zero v1.0 Universal (CC0-1.0) license.