README.md

---
language: fr
license: mit
tags:
- token-classification
- named-entity-recognition
- french
- camembert
- distillation
- pruning
- fp16
- medical
- social-work
base_model: Jean-Baptiste/camembert-ner
datasets:
- custom-medical-social-corpus
metrics:
- f1
- precision
- recall
model-index:
- name: CamemBERT-NER-Distilled-Pruned-FP16
  results:
  - task:
      type: token-classification
      name: Named Entity Recognition
    metrics:
    - name: F1
      type: f1
      value: 0.859
    - name: Precision
      type: precision
      value: 0.861
    - name: Recall
      type: recall
      value: 0.858
---

# CamemBERT-NER Distilled + Pruned + FP16

**Modèle optimisé pour la reconnaissance d'entités nommées (NER) dans les rapports sociaux français**

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Model](https://img.shields.io/badge/Model-CamemBERT-green.svg)](https://huggingface.co/camembert-base)

## 📋 Description

Ce modèle est une version optimisée triple de CamemBERT pour la reconnaissance d'entités nommées (NER) dans le domaine du travail social français. Il combine :

1. **Distillation** : 11 couches (vs 12 du teacher) = -8.3% paramètres
2. **Pruning non-structurel** : 20% magnitude-based = 15.14% sparsity effective
3. **Quantization FP16** : Half-precision = -50% taille mémoire

### 🎯 Objectifs

- **Taille réduite** : 196 MB (vs 210 MB baseline, vs 420 MB FP32 original)
- **Vitesse accrue** : ~15-20% plus rapide (distillation + FP16)
- **Performance maintenue** : F1 85.9% (seuil acceptable >85%)
- **Mémoire optimisée** : -50% RAM avec FP16

### 📊 Résultats d'évaluation

**Test set** : 447 entités gold standard

| Métrique | Score | vs Baseline (FP16 Teacher 12L) |
|----------|-------|--------------------------------|
| **F1 Score** | **85.9%** | -1.3% (87.3% → 85.9%) |
| **Precision** | **86.1%** | -2.2% (88.2% → 86.1%) |
| **Recall** | **85.8%** | -0.5% (86.3% → 85.8%) |
| **Weighted Score** | **96.4%** | -0.2% (96.6% → 96.4%) |
| **False Positives** | 64 | +11 (53 → 64) |
| **Missed Entities** | 52 | +2 (50 → 52) |

**✅ Trade-off accepté** : -1.3% F1 pour -6.7% taille + ~15-20% vitesse

### 🏷️ Catégories d'entités détectées

Le modèle de base détecte **4 catégories principales** :

- **PER** (Person) : Personnes, noms, prénoms
- **LOC** (Location) : Lieux, villes, pays, régions  
- **ORG** (Organization) : Organisations, entreprises, institutions
- **MISC** (Miscellaneous) : Entités diverses (dates, événements, etc.)

> **Note** : Ce modèle est le composant NER de base du pipeline LaPlume. Les catégories fines (39 types spécialisés comme `ETAB_MECS`, `ID_RSA`, `LOC_CITY`, etc.) sont ajoutées par les post-traitements du pipeline complet (règles regex, gazetteers, reclassification).

### 🎯 Cas d'usage

Ce modèle est optimisé pour :
- **Rapports sociaux** : évaluations, suivis, comptes-rendus
- **Documents médico-sociaux** : dossiers patients, orientations
- **Anonymisation** : détection d'entités pour pseudonymisation
- **Environnements contraints** : serveurs avec RAM limitée, déploiement edge
- `ETAB_MAS`, `ETAB_FAM`, `ETAB_ESAT`, `ETAB_SAVS`, `ETAB_SAMSAH` : Handicap adulte
- `ETAB_CHRS` : Hébergement d'urgence
- `ETAB_CMS` : Centres médico-sociaux
- `ETAB_SCOLAIRE` : Établissements scolaires
- etc. (voir documentation complète)

## 🔧 Architecture technique

### Modèle de base

- **Base** : CamemBERT (RoBERTa français)
- **Vocabulary** : 32,000 tokens (SentencePiece BPE)
- **Hidden size** : 768
- **Attention heads** : 12
- **Layers** : **11** (distilled from 12-layer teacher)

### Optimisations appliquées

#### 1. Knowledge Distillation (11 layers)

```python
Teacher: camembert-ner (12 layers, F1 87.3%)
Student: 11 layers, distilled with temperature=2.0
Loss: α * CE_loss + (1-α) * KD_loss
Result: F1 81.25% on training → 85.9% final
```

#### 2. Magnitude-based Pruning (20%)

```python
Target: 20% sparsity (magnitude-based)
Effective: 15.14% (15.6M params zeroed / 102.9M total)
Method: Iterative pruning during distillation
```

#### 3. FP16 Quantization

```python
Conversion: torch.float32 → torch.float16
Size reduction: 392.71 MB → 196.36 MB (-50.0%)
Quality impact: Minimal (<0.1% F1 degradation)
```

### 📦 Spécifications

- **Paramètres totaux** : 102,947,333
- **Paramètres non-zéro** : 87,350,000 (~85%)
- **Taille mémoire** : 196.36 MB (FP16)
- **Temps d'inférence** : ~15-20% plus rapide que baseline
- **Compatibilité** : Transformers ≥ 4.30.0, PyTorch ≥ 2.0.0

## 🚀 Usage

### Dataset d'entraînement

Le modèle student distillé a été entraîné sur **50 000 phrases** provenant de trois sources complémentaires :

1. **Contexte médico-social français** :
   - Rapports sociaux fictifs mais réalistes (générés pour l'entraînement)
   - Rapports publics sur l'organisation médico-sociale et bonnes pratiques
2. **Narratif littéraire** : Grands romans français du XXe siècle (dialogues, descriptions de personnages)
3. **Articles Wikipedia français** : Contenu encyclopédique général

Cette diversité de sources permet une bonne généralisation tout en conservant une spécialisation pour le domaine médico-social, **sans utiliser de données confidentielles réelles**.

### Installation

```bash
pip install transformers torch
```

### Chargement du modèle

```python
from transformers import AutoTokenizer, AutoModelForTokenClassification
import torch

# Charger le modèle et le tokenizer
model_name = "jmdanto/titibongbong_camemBERT_NER"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForTokenClassification.from_pretrained(
    model_name,
    torch_dtype=torch.float16  # Force FP16 pour bénéficier des optimisations
)

# Exemple d'inférence
text = "Marie Dupont habite à Paris et travaille à l'Hôpital Sainte-Anne."
inputs = tokenizer(text, return_tensors="pt")

with torch.no_grad():
    outputs = model(**inputs)
    predictions = torch.argmax(outputs.logits, dim=-1)

# Décoder les prédictions
tokens = tokenizer.convert_ids_to_tokens(inputs["input_ids"][0])
labels = [model.config.id2label[p.item()] for p in predictions[0]]

for token, label in zip(tokens, labels):
    if label != "O":
        print(f"{token}: {label}")

# Résultat attendu :
# Marie: B-PER
# Dupont: I-PER
# Paris: B-LOC
# Hôpital: B-ORG
# Sainte: I-ORG
# -: I-ORG
# Anne: I-ORG
```

### Pipeline complet avec post-traitement

```python
from transformers import pipeline

# Créer le pipeline NER
ner_pipeline = pipeline(
    "ner",
    model=model_name,
    tokenizer=model_name,
    aggregation_strategy="simple",  # Fusionne les sous-tokens
    device=0 if torch.cuda.is_available() else -1
)

# Analyser un texte
text = """
Rapport social concernant M. Bernard Martin, 
domicilié au 23 rue de la Paix, 69000 Lyon.
Suivi par le Centre Médico-Social de Lyon-Confluence.
"""

entities = ner_pipeline(text)

for entity in entities:
    print(f"{entity['entity_group']}: {entity['word']} (score: {entity['score']:.2f})")

# Résultat attendu :
# PER: Bernard Martin (score: 0.99)
# LOC: rue de la Paix (score: 0.95)
# LOC: Lyon (score: 0.98)
# ORG: Centre Médico-Social de Lyon-Confluence (score: 0.92)
```

## 📈 Benchmarks

### Comparaison des modèles

| Modèle | Taille | F1 | Précision | Rappel | FP | Manqués |
|--------|--------|----|-----------  |--------|-------|---------|
| **Baseline FP16** (Teacher 12L) | 210 MB | 87.3% | 88.2% | 86.3% | 53 | 50 |
| **Distilled FP32** (Student 11L) | 393 MB | 85.8% | 85.9% | 85.8% | 65 | 52 |
| **Distilled FP16** (Ce modèle) | **196 MB** | **85.9%** | **86.1%** | **85.8%** | **64** | **52** |

**Trade-offs** :
- ✅ **Taille** : -6.7% vs baseline, meilleure efficacité
- ✅ **Vitesse** : ~15-20% plus rapide (distillation + FP16)
- ⚠️ **Qualité** : -1.3% F1 (acceptable, >85% seuil requis)

### Performance par criticité

| Criticité | Rappel | Précision | F1 | Entités |
|-----------|--------|-----------|----|----|
| **CRIT** (NIR, etc.) | 96.8% | 100% | 98.4% | 19 |
| **HIGH** (PER, ID) | 93.0% | 95.7% | 94.4% | 176 |
| **MED** (ORG, ETAB) | 81.4% | 77.4% | 79.3% | 199 |
| **LOW** (LOC, DATE) | 69.4% | 74.5% | 71.9% | 49 |

**✅ Points forts** :
- Excellente détection des données critiques 
- Précision élevée sur les personnes
- Bon équilibre précision/rappel global

## 🎓 Entraînement

### Dataset

- **Domaine** : Rapports sociaux français (ASE, RSA, handicap, hébergement)
- **Taille** : 10 fichiers d'entraînement annotés manuellement
- **Annotations** : Format IOB2 avec 39 catégories d'entités
- **Augmentation** : Gazetteers spécialisés (FINESS, prénoms, associations)

### Hyperparamètres

```yaml
# Distillation
teacher: camembert-ner-12layers-fp16
student_layers: 11
temperature: 2.0
alpha: 0.5

# Pruning
method: magnitude_based
target_sparsity: 0.20
effective_sparsity: 0.1514

# Training
learning_rate: 2e-5
batch_size: 16
epochs: 10
optimizer: AdamW
warmup_ratio: 0.1

# Quantization
dtype: float16
method: torch.half()
```

## ⚠️ Limitations

1. **Domaine spécialisé** : Optimisé pour les rapports sociaux français, performances moindres sur d'autres domaines
2. **Trade-off qualité** : -1.3% F1 vs baseline pour gain taille/vitesse
3. **Faux positifs** : +11 FP vs baseline (64 vs 53), vérification recommandée
4. **Entités rares** : Performance réduite sur catégories peu fréquentes (LOC, DATE)
5. **Hardware** : FP16 nécessite GPU compatible (Pascal+) ou CPU moderne

## 📄 Licence

Apache 2.0

## 🤝 Citation

```bibtex
@model{camembert-ner-distilled-pruned-fp16,
  title={CamemBERT-NER Distilled + Pruned + FP16},
  author={Danto, Patrick},
  year={2024},
  publisher={HuggingFace},
  url={https://huggingface.co/jmdanto/titibongbong_camemBERT_NER}
}

@model{camembert-ner-teacher,
  title={CamemBERT-NER: Fine-tuned CamemBERT for NER task},
  author={Pollé, Jean-Baptiste},
  year={2020},
  publisher={HuggingFace},
  url={https://huggingface.co/Jean-Baptiste/camembert-ner}
}
```

## 📞 Contact

- **Email** : patrick.danto@outlook.fr

## 🔄 Versions

- **v1.0** (Nov 2024) : Version initiale distillée + prunée + FP16
  - 11 layers, 20% pruning, FP16 quantization
  - F1: 85.9%, Size: 196 MB
  - Évalué sur 447 entités gold standard

---

**Note** : Ce modèle fait partie du projet **La Plume**, un pipeline de pseudonymisation pour documents médico-sociaux français. Le pipeline complet est un projet privé protégé au titre de la propriété intellectuelle, mais ce modèle est publié sous licence MIT.