Solayman-Sameh's picture
Upload README.md with huggingface_hub
6f44509 verified
|
Raw History Blame Contribute Delete
3.01 kB
---
language:
- en
license: mit
tags:
- token-classification
- distilbert
- pytorch
- ner
- conll2003
datasets:
- conll2003
metrics:
- f1
pipeline_tag: token-classification
widget:
- text: "Alice works at Microsoft in London."
- text: "Sara works at Google in Cairo."
- text: "Mohamed studies at MIT in USA."
- text: "Apple opened an office in Paris."
- text: "An Egyptian student moved to Paris."
---
# ๐Ÿท๏ธ Named Entity Recognition โ€” Fine-Tuned DistilBERT
This is the fine-tuned **cased DistilBERT** model for English Named Entity Recognition (NER) trained on the **CoNLL-2003** corpus. It detects and classifies tokens into four entity categories:
- **PER** (Person)
- **ORG** (Organization)
- **LOC** (Location / Place)
- **MISC** (Miscellaneous, e.g. nationalities, events)
It achieved the winning score in an architectural comparison against LSTM, BiLSTM, and BiLSTM + CRF models.
## ๐Ÿ“Š Performance (Strict CoNLL-2003 Evaluation)
Evaluated with `seqeval` in strict IOB2 mode (requiring exact boundary and category match):
| Entity Type | Precision | Recall | Strict F1 |
|---|---:|---:|---:|
| **Overall** | **89.39%** | **90.98%** | **90.18%** |
| Person (`PER`) | 95.34% | 95.03% | **95.18%** |
| Organization (`ORG`) | 86.81% | 88.75% | **87.77%** |
| Location (`LOC`) | 92.51% | 92.23% | **92.37%** |
| Miscellaneous (`MISC`) | 78.43% | 80.57% | **79.49%** |
- **Validation Macro F1:** 93.92%
- **Test Strict F1:** 90.18%
## ๐Ÿš€ Quick Usage
### Using Hugging Face Pipeline
```python
from transformers import pipeline
ner = pipeline("ner", model="Solayman-Sameh/named-entity-recognition", aggregation_strategy="simple")
text = "Sara works at Google in Cairo."
entities = ner(text)
for ent in entities:
print(f"{ent['word']} -> {ent['entity_group']} ({ent['score']:.2%})")
```
### Using PyTorch Directly
```python
import torch
from transformers import AutoTokenizer, AutoModelForTokenClassification
model_id = "Solayman-Sameh/named-entity-recognition"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForTokenClassification.from_pretrained(model_id).eval()
text = "Mohamed studies at MIT in USA."
inputs = tokenizer(text, return_tensors="pt")
with torch.inference_mode():
outputs = model(**inputs)
predictions = outputs.logits.argmax(dim=-1)[0].tolist()
tokens = tokenizer.convert_ids_to_tokens(inputs["input_ids"][0])
for token, pred in zip(tokens, predictions):
if token not in [tokenizer.cls_token, tokenizer.sep_token, tokenizer.pad_token]:
print(f"{token}: {model.config.id2label[pred]}")
```
## ๐Ÿ’ป Full Project & Web App
The complete source code, exploratory data analysis, architectural comparison (LSTM, BiLSTM, BiLSTM+CRF vs. DistilBERT), test reports, and an interactive Gradio web demo are available at:
๐Ÿ‘‰ [GitHub: Solayman-Sameh/named-entity-recognition](https://github.com/Solayman-Sameh/named-entity-recognition)