| --- |
| title: AvisSense |
| emoji: "🎬" |
| colorFrom: blue |
| colorTo: red |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| short_description: Analyse de sentiment d'avis cinema en francais. |
| --- |
| # 🎬 AvisSense — Analyse de sentiment d'avis cinéma (français) |
|
|
| > Projet de fin de module **M106 — Intro ML/DL** · Sujet : analyse de sentiment d'avis en français (secteur culture) |
|
|
| Classification binaire d'avis de cinéma : **on colle un avis en français, le modèle prédit positif ou négatif avec un score de confiance** (la consigne du sujet, mot pour mot). Un **DistilCamemBERT** est fine-tuné (transfer learning) sur le dataset **Allociné**, **servi par une API FastAPI** avec un **petit front** intégré, le tout déployé sur **Hugging Face Spaces** — toute la chaîne, sans usine à gaz. |
|
|
| > Le repo inclut un **front minimal** (HTML/CSS/JS, servi par l'API à `GET /`) qui garantit la chaîne complète déployée. Un front plus complet est développé séparément par un autre membre de l'équipe : il consommera les mêmes endpoints (contrat d'API en section 8, Swagger sur `/docs`, CORS déjà activé). |
|
|
| ``` |
| POST /predict {"text": "Ce film est incroyable"} |
| -> {"label": "positif", "confidence": 0.94, ...} |
| ``` |
|
|
| --- |
|
|
| ## 1. Objectif |
|
|
| - Fine-tuner un modèle de langage pré-entraîné (transfer learning) pour classer des avis de cinéma en français : positif / négatif. |
| - Trancher la **décision architect** : geler le modèle et n'entraîner qu'une tête, ou fine-tuner entièrement ? (section 4) |
| - **Servir** le modèle via une API REST (FastAPI) + un petit front « colle un avis → résultat ». |
| - Déployer publiquement la chaîne complète sur Hugging Face Spaces. |
|
|
| ### Conformité aux consignes du module |
|
|
| | Consigne | Où c'est respecté | |
| |---|---| |
| | Orienté Deep Learning (fine-tuning d'un modèle de texte) | `scripts/train.py` — DistilCamemBERT fine-tuné sur Allociné | |
| | Modèle **servi** avec FastAPI | `api/main.py` — `POST /predict` | |
| | **Petit front** | `frontend/` — servi par l'API à `GET /` | |
| | Déployé (HF Spaces ou équivalent) | `Dockerfile` — Space Docker, section 9 | |
| | Secteur ≠ démos du cours | culture / cinéma | |
| | Décisions défendues (modèle, stratégie de transfer) | sections 3 et 4 — les **deux** stratégies sont implémentées et comparées | |
| | Livrables | code + README (ce fichier) + lien du modèle déployé (section 9) + vidéo ≤ 10 min sur Teams **avant vendredi 13h** | |
|
|
| ## 2. Dataset — Allociné (avis ciné uniquement) |
|
|
| - **Source** : [`allocine`](https://huggingface.co/datasets/allocine) sur le Hugging Face Hub. |
| - **Contenu** : ~200 000 avis de films en français, étiquetés `0` (négatif) ou `1` (positif), labels dérivés des notes utilisateurs (donc fiables). Classes équilibrées ~50/50. |
| - **Splits fournis** : train (160k) / validation (20k) / test (20k) — déjà séparés, aucun risque de fuite de données. |
| - **Colonnes** : `review` (texte) et `label`. |
| - **Sous-échantillonnage** : entraînement sur **8 000 avis** (validation 2 000, test 2 000) pour rester rapide (~20 min sur GPU Colab gratuit). Le modèle pré-entraîné connaît déjà le français : il n'apprend que la frontière positif/négatif, et la performance sature vite — les 160k complets n'apporteraient que 1-2 points de F1 pour 20× plus de calcul. Ajustable via `--max-train`. |
|
|
| ## 3. Modèle — DistilCamemBERT |
|
|
| | Modèle | Langue | Paramètres | Vitesse | Performance FR | |
| |---|---|---|---|---| |
| | CamemBERT-base | Français | 110M | 1× | Excellente | |
| | **DistilCamemBERT** ✅ | Français | 68M | ~2× | ~97 % de CamemBERT | |
| | DistilBERT multilingual | 104 langues | 134M | ~1.5× | Moyenne (capacité diluée) | |
|
|
| **Choix : [`cmarkea/distilcamembert-base`](https://huggingface.co/cmarkea/distilcamembert-base)** — spécialisé français (un modèle multilingue dilue sa capacité sur 104 langues et tokenise moins bien le français), 2× plus rapide que CamemBERT à l'entraînement comme en inférence, pour une perte négligeable sur une tâche binaire. Crucial pour servir le modèle sur le CPU gratuit de Spaces. |
|
|
| ## 4. Décision Architect — geler le backbone ou fine-tuner ? |
|
|
| C'est l'arbitrage central du projet, et **les deux stratégies sont implémentées** dans `train.py` pour le trancher avec des chiffres plutôt qu'une intuition : |
|
|
| | | Stratégie A — fine-tuning complet (défaut) | Stratégie B — backbone gelé (`--freeze-backbone`) | |
| |---|---|---| |
| | Paramètres entraînés | 68M (100 %) | ~0.6M (~1 %, la tête seule) | |
| | Learning rate | 2e-5 (faible : on ajuste sans détruire) | 1e-3 (la tête part de zéro) | |
| | Coût d'entraînement | ~20 min (GPU Colab) | ~3× plus rapide, envisageable sur CPU | |
| | F1 attendu (test) | **≈ 0.93–0.96** | ≈ 0.85–0.89 | |
|
|
| ```bash |
| # Stratégie A — fine-tuning complet |
| python scripts/train.py |
| |
| # Stratégie B — backbone gelé, tête seule |
| python scripts/train.py --freeze-backbone --learning-rate 1e-3 |
| ``` |
|
|
| Chaque run écrit ses métriques dans `model/sentiment_model/training_metrics.json` (avec le champ `strategy`) : comparer les deux JSON donne l'arbitrage chiffré. |
|
|
| **Décision retenue : fine-tuning complet.** Le gel du backbone utilise les features génériques du pré-entraînement (masked language modeling), qui ne sont pas optimisées pour discriminer le sentiment ; laisser le backbone s'adapter au vocabulaire des critiques de cinéma gagne ~5-8 points de F1. Le surcoût de calcul (20 min de Colab gratuit) est négligeable, et le coût d'**inférence est identique** dans les deux cas — l'argument "économie" du gel ne vaut que pour l'entraînement. Le gel resterait pertinent avec très peu de données (< 1 000 exemples, risque d'overfitting) ou sans aucun GPU disponible — ce n'est pas notre cas. |
|
|
| ## 5. Architecture du projet |
|
|
| ``` |
| AvisSense/ |
| ├── api/ |
| │ └── main.py # API FastAPI : front sur /, /info, /health, POST /predict |
| ├── frontend/ |
| │ ├── index.html # Front minimal : zone de texte + bouton + résultat |
| │ ├── style.css # Style (label coloré + barre de confiance) |
| │ └── script.js # fetch() vers POST /predict |
| ├── model/ |
| │ └── sentiment_model/ # Modèle fine-tuné (créé par train.py, non versionné) |
| ├── scripts/ |
| │ ├── train.py # Entraînement : les 2 stratégies (gel / fine-tuning) |
| │ ├── predict.py # Prédiction en CLI (inférence manuelle détaillée) |
| │ ├── evaluate.py # Évaluation test set + analyse des erreurs |
| │ └── push_model_to_hub.py # Upload du modèle sur le HF Hub |
| ├── Dockerfile # Déploiement Hugging Face Spaces (Docker) |
| ├── requirements.txt # Dépendances Python |
| ├── .gitignore |
| └── README.md |
| ``` |
|
|
| **Rôle des dossiers** : |
| - `scripts/` — cycle de vie du modèle (entraînement, évaluation, publication). Séparé de l'API : on peut ré-entraîner sans toucher au serveur. |
| - `api/` — le serveur. Charge le modèle une fois au démarrage (lifespan), expose les endpoints, sert le front, CORS activé pour le futur front externe. |
| - `frontend/` — le petit front demandé par les consignes : fichiers statiques servis par FastAPI, aucune dépendance supplémentaire. Remplaçable par le front complet de l'équipe sans toucher à l'API. |
| - `model/` — artefact produit par l'entraînement. Ignoré par git (270 Mo) : les poids sont stockés sur le HF Hub, le code sur GitHub. |
|
|
| ## 6. Installation |
|
|
| ```bash |
| git clone https://github.com/VOTRE_PSEUDO/AvisSense.git |
| cd AvisSense |
| |
| python -m venv .venv |
| .venv\Scripts\activate # Windows |
| # source .venv/bin/activate # Linux / macOS |
| |
| pip install -r requirements.txt |
| ``` |
|
|
| ## 7. Entraînement et évaluation |
|
|
| ```bash |
| # Entraînement standard (fine-tuning complet, 8000 avis, 2 époques) |
| python scripts/train.py |
| |
| # Comparaison avec le backbone gelé (décision architect, section 4) |
| python scripts/train.py --freeze-backbone --learning-rate 1e-3 |
| |
| # Version rapide pour tester le pipeline sur CPU (~10 min) |
| python scripts/train.py --max-train 2000 --max-val 500 --max-test 500 --epochs 1 |
| ``` |
|
|
| Sur **Google Colab** (GPU gratuit, recommandé) : uploader le dossier, puis : |
| ```python |
| !pip install -q transformers datasets accelerate scikit-learn |
| !python scripts/train.py |
| ``` |
|
|
| Le script affiche l'exploration du dataset, la progression, puis les métriques finales sur le **test set** avec matrice de confusion, et sauvegarde le modèle dans `model/sentiment_model/`. |
|
|
| ```bash |
| # Prédiction en CLI (--verbose : tokens, logits, softmax ; sans argument : mode interactif) |
| python scripts/predict.py "Ce film est un chef-d'œuvre absolu !" |
| |
| # Évaluation détaillée : rapport par classe, matrice de confusion, |
| # et les erreurs où le modèle était le plus confiant (analyse des limites) |
| python scripts/evaluate.py --max-test 2000 --show-errors 5 |
| ``` |
|
|
| ## 8. Lancement : API + front |
|
|
| ```bash |
| uvicorn api.main:app --reload |
| # Front : http://127.0.0.1:8000 |
| # Swagger : http://127.0.0.1:8000/docs |
| ``` |
|
|
| | Méthode | Route | Description | |
| |---|---|---| |
| | GET | `/` | Le front minimal : coller un avis → prédiction + confiance | |
| | GET | `/info` | Informations sur l'API (JSON) | |
| | GET | `/health` | `{"status": "ok", "model_loaded": true, ...}` | |
| | POST | `/predict` | Prédiction de sentiment | |
|
|
| **POST /predict** — requête : |
| ```json |
| { "text": "Ce film est incroyable" } |
| ``` |
|
|
| Réponse `200` : |
| ```json |
| { |
| "label": "positif", |
| "confidence": 0.9812, |
| "probabilities": { "négatif": 0.0188, "positif": 0.9812 }, |
| "processing_time_ms": 47.3 |
| } |
| ``` |
|
|
| Erreurs : |
| | Code | Cas | Corps | |
| |---|---|---| |
| | 400 | texte vide / espaces | `{"detail": "Le texte ne peut pas être vide."}` | |
| | 400 | texte > 5000 caractères | `{"detail": "Texte trop long (...)"}` | |
| | 422 | JSON malformé ou champ `text` manquant | détail Pydantic automatique | |
| | 503 | modèle pas encore chargé | `{"detail": "Modèle en cours de chargement."}` | |
|
|
| Exemples d'appel : |
| ```bash |
| # PowerShell |
| Invoke-RestMethod -Uri http://127.0.0.1:8000/predict -Method Post ` |
| -ContentType "application/json" -Body '{"text": "Ce film est incroyable"}' |
| |
| # curl |
| curl -X POST http://127.0.0.1:8000/predict \ |
| -H "Content-Type: application/json" \ |
| -d '{"text": "Ce film est incroyable"}' |
| ``` |
|
|
| CORS est activé (`allow_origins=["*"]`) pour que le frontend hébergé ailleurs puisse appeler l'API ; à restreindre au domaine réel en production. |
|
|
| ## 9. Déploiement sur Hugging Face Spaces |
|
|
| Deux artefacts, deux destinations : **les poids sur le Hub**, **l'API sur un Space Docker** (qui télécharge les poids au démarrage). |
|
|
| ### Étape A — Pousser le modèle sur le Hub |
| ```bash |
| huggingface-cli login # token "Write" depuis Settings > Access Tokens |
| python scripts/push_model_to_hub.py --repo VOTRE_PSEUDO/avissense-distilcamembert |
| ``` |
|
|
| ### Étape B — Créer le Space |
| 1. https://huggingface.co/new-space : SDK **Docker**, hardware **CPU basic (gratuit)**. |
| 2. Dans **Settings > Variables** du Space : `MODEL_ID = VOTRE_PSEUDO/avissense-distilcamembert` |
| 3. Pousser le code : |
| ```bash |
| git remote add space https://huggingface.co/spaces/VOTRE_PSEUDO/avissense |
| git push space main |
| ``` |
|
|
| La chaîne complète est alors visible à l'URL publique du Space : `https://VOTRE_PSEUDO-avissense.hf.space/` ouvre directement le front « colle un avis → résultat » (et `/docs` la documentation de l'API). **C'est ce lien qu'on remet comme livrable « modèle déployé ».** La première requête après un réveil du Space est lente (téléchargement + chargement du modèle) ; `/health` permet de vérifier que le modèle est prêt — à faire avant la démo vidéo. |
|
|
| ## 10. Limites |
|
|
| - **Domaine ciné** : entraîné sur des avis de films — les performances baissent hors domaine (produits, restaurants) car le vocabulaire diffère (« lourd » est négatif pour un film, neutre pour un plat). |
| - **Binaire** : pas de classe « neutre » — un avis mitigé est forcé dans un camp, généralement avec une confiance plus faible (~0.5-0.7). |
| - **Ironie / sarcasme** : « Bravo, 2 h de ma vie perdues » contient des mots positifs avec un sens négatif. |
| - **Confiance non calibrée** : le score softmax est souvent sur-confiant ; 0.94 ne signifie pas « 94 % de chances d'avoir raison » au sens statistique. |
| - **Troncature à 256 tokens** : la fin des très longs avis est ignorée. |
|
|
| ## 11. Améliorations futures |
|
|
| - Classe **neutre** (3 classes, autre dataset). |
| - Entraînement sur les **160k avis** complets (+1-2 points de F1). |
| - **Calibration** du score de confiance (temperature scaling). |
| - Endpoint **batch** (`POST /predict/batch`) pour analyser plusieurs avis en un appel. |
| - Export **ONNX + quantization int8** : inférence 2-4× plus rapide sur CPU. |
| - **Monitoring** : logger les prédictions à faible confiance pour ré-annotation (amélioration continue). |
|
|
| ## 12. Interface Gradio optionnelle |
|
|
| En plus de l'API FastAPI et de son front statique, une interface Gradio est |
| disponible : |
|
|
| ```bash |
| python app.py |
| ``` |
|
|
| FastAPI, Gradio et le script de prediction utilisent tous `src/inference.py`. |
| Le modele est charge depuis `model/sentiment_model/` en local, ou depuis le |
| repo Hugging Face indique par la variable d'environnement `MODEL_ID`. |
|
|
| Le rapport de fusion des branches est disponible dans |
| `docs/merge_report.md`. |
|
|
| --- |
|
|
| *Projet réalisé dans le cadre du module M106 — Intro ML/DL.* |
|
|
