Air Paradis Sentiment Analysis API

🚀 API FastAPI d'analyse de sentiment pour les tweets - Modèle BiLSTM avec Word2Vec

Cette API constitue le livrable principal du Projet 7 : "Réaliser une analyse de sentiments grâce au Deep Learning" dans le cadre du parcours Ingénieur IA d'OpenClassrooms. Le projet simule une mission de conseil pour la compagnie aérienne fictive "Air Paradis" visant à développer un système d'analyse de sentiment des tweets pour anticiper les bad buzz sur les réseaux sociaux.

Objectifs pédagogiques :

Maîtriser les techniques de Deep Learning pour l'analyse de sentiment
Comparer différentes approches (modèles classiques vs avancés vs BERT)
Implémenter une démarche MLOps complète (expérimentation, déploiement, monitoring)
Déployer un modèle en production sur le Cloud avec pipeline CI/CD

🏗️ Architecture

google_air-paradis-api/
├── .github/workflows/
│   ├── ci-cd.yml               # Pipeline API
│   └── deploy-frontend.yml     # Pipeline Frontend
├── app/
│   ├── __init__.py
│   └── main.py                 # API FastAPI principale
├── config/
│   ├── __init__.py
│   └── settings.py             # Configuration de l'application
├── frontend/                   # Interface Next.js
│   ├── app/
│   │   ├── page.tsx            # Page principale
│   │   ├── layout.tsx          # Layout global
│   │   ├── globals.css         # Styles avec animations
│   │   └── api/logging/        # API route pour Google Cloud Logging
│   ├── components/
│   │   ├── AnimatedHeader.tsx  # En-tête avec logo animé
│   │   ├── SentimentForm.tsx   # Formulaire d'analyse
│   │   ├── SentimentResult.tsx # Affichage des résultats
│   │   └── ui/                 # Composants UI réutilisables
│   ├── lib/
│   │   ├── api.ts              # Fonctions d'API et monitoring
│   │   └── utils.ts            # Utilitaires
│   │── public/
│   │   └── logo.png            # Logo de l'API
│   ├── Dockerfile              # Image Docker pour le frontend
│   └── README.md               # Documentation frontend
├── models/
│   ├── best_advanced_model_BiLSTM_Word2Vec.h5    # Modèle TensorFlow
│   ├── best_advanced_model_tokenizer.pickle      # Tokenizer
│   └── best_advanced_model_config.pickle         # Configuration du modèle
├── monitoring/
│   ├── __init__.py
│   └── gcp_monitor.py          # Monitoring Google Cloud
├── tests/
│   ├── __init__.py
│   └── test_api.py             # Tests unitaires
├── requirements.txt            # Dépendances Python
├── requirements-windows.txt    # Dépendances Python pour Windows
├── Dockerfile                  # Image Docker API
├── Dockerfile.frontend         # Image Docker Frontend
├── .dockerignore               # Exclusions Docker
└── README.md                   # Cette documentation

📦 Prérequis

Python 3.10+
Docker (pour le déploiement)
Compte Google Cloud avec les APIs activées :
- Cloud Run API
- Artifact Registry API
- Cloud Monitoring API
- Cloud Logging API
MLflow pour le tracking des expérimentations
Modèles pré-entraînés du notebook 3_modele_avance.py

Installation locale 🔧

1. Cloner le repository

git clone https://github.com/berch-t/air-paradis-sentiment-api
cd air-paradis-sentiment-api

2. Créer un environnement virtuel

python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate     # Windows

3. Installer les dépendances

# Pour le développement local Windows
pip install -r requirements-windows.txt

# Pour déploiement Linux/Docker
pip install -r requirements.txt

4. Modèles pré-entraînés

Les modèles sont automatiquement téléchargés depuis Google Cloud Storage au démarrage de l'API :

best_advanced_model_BiLSTM_Word2Vec.h5 (338.9 MB)
best_advanced_model_tokenizer.pickle (12.9 MB)
best_advanced_model_config.pickle (142 B)

Bucket GCS : gs://air-paradis-models/

Note : Les modèles sont hébergés sur Google Cloud Storage pour éviter les limitations de GitHub LFS.

5. Démarrer MLflow (dans un terminal séparé)

mlflow ui --host 0.0.0.0 --port 5000

MLflow sera accessible à : http://localhost:5000

6. Lancer l'API

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

L'API sera accessible à : http://localhost:8000

☁️ Déploiement sur Google Cloud

Étape 1 : Configuration du projet Google Cloud

Créer un projet Google Cloud :
- Aller sur Google Cloud Console
- Créer un nouveau projet : air-paradis-sentiment

Activer les APIs nécessaires :

gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable logging.googleapis.com

Créer un bucket Google Cloud Storage :

gsutil mb -c STANDARD -l europe-west1 gs://air-paradis-models
gsutil iam ch allUsers:objectViewer gs://air-paradis-models

Uploader les modèles :

gsutil cp models/*.h5 gs://air-paradis-models/
gsutil cp models/*.pickle gs://air-paradis-models/

Étape 2 : Configuration des secrets GitHub

Dans votre repository GitHub, aller dans Settings > Secrets and variables > Actions et ajouter :

GCP_SA_KEY : Clé JSON du compte de service Google Cloud avec les permissions :
- Cloud Run Admin
- Artifact Registry Admin
- Monitoring Admin
- Logging Admin

Étape 3 : Déploiement via GitHub Actions

Push vers la branche main :

git add .
git commit -m "First Commit: Deploy Air Paradis Sentiment API"
git push origin main

Vérifier le déploiement :
- Aller dans l'onglet Actions de votre repository GitHub
- Vérifier que le pipeline s'exécute sans erreur

Étape 4 : Vérification du déploiement

Une fois déployé, l'API sera accessible via l'URL Cloud Run :

https://air-paradis-sentiment-api-[hash]-ew.a.run.app

Test de santé :

curl https://your-service-url/health

📊 Configuration MLflow

Démarrage local de MLflow

# Dans le dossier du projet
mlflow ui --host 0.0.0.0 --port 5000

Accès aux expérimentations

Interface MLflow : http://localhost:5000
Expériment : air_paradis_sentiment_production
Modèles trackés : Chaque prédiction et feedback est automatiquement enregistré

Exemple de tracking

with mlflow.start_run(run_name="prediction_example"):
    mlflow.log_param("text_length", len(text))
    mlflow.log_metric("confidence", confidence)
    mlflow.log_param("sentiment", sentiment)

📈 Monitoring et alertes

Google Cloud Monitoring

L'API utilise Google Cloud Logging et Google Cloud Monitoring pour :

Logs structurés :
- Prédictions réussies
- Erreurs de prédiction
- Feedback utilisateur
Métriques personnalisées :
- Nombre d'erreurs
- Temps de réponse
- Feedback de qualité
Alertes automatiques :
- Email envoyé à [email protected] (Admin)
- Déclenchement : 3 erreurs en 5 minutes

Configuration des alertes

Les alertes sont automatiquement configurées dans le code. Pour personnaliser :

# Dans monitoring/gcp_monitor.py
self.error_threshold = 3  # Nombre d'erreurs
self.time_window_minutes = 5  # Fenêtre de temps
self.alert_email = "[email protected]"

🧪 Tests

Lancer les tests unitaires

python -m pytest tests/ -v

Tests avec couverture

pip install coverage
coverage run -m pytest tests/
coverage report -m

Tests d'intégration

# Test de l'API locale
curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{"text": "I love Air Paradis, great service!"}'

🔌 API Endpoints

GET `/` - Informations de l'API

{
  "message": "Air Paradis Sentiment Analysis API",
  "version": "1.0.0",
  "model": "BiLSTM_Word2Vec",
  "endpoints": {...}
}

GET `/health` - Santé de l'API

{
  "status": "healthy",
  "model_loaded": true,
  "timestamp": "2024-01-01T12:00:00",
  "version": "1.0.0"
}

POST `/predict` - Prédiction de sentiment

Request:

{
  "text": "I had an amazing flight with Air Paradis!",
  "user_id": "optional_user_id"
}

Response:

{
  "text": "I had an amazing flight with Air Paradis!",
  "sentiment": "positive",
  "confidence": 0.8542,
  "probability": 0.8542,
  "model": "BiLSTM_Word2Vec",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "request_id": "req_20240101_120000_123456"
}

POST `/feedback` - Feedback utilisateur

Request:

{
  "text": "Great service!",
  "predicted_sentiment": "positive",
  "actual_sentiment": "positive",
  "is_correct": true,
  "user_id": "optional_user_id"
}

Response:

{
  "message": "Feedback enregistré avec succès",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

GET `/metrics` - Métriques de l'API

{
  "total_errors": 0,
  "recent_errors_5min": 0,
  "model_loaded": true,
  "timestamp": "2024-01-01T12:00:00.000Z"
}

🔄 Pipeline CI/CD

Le pipeline GitHub Actions inclut :

Tests automatiques :
- Tests unitaires avec pytest
- Validation du code
- Couverture de tests
Build Docker :
- Construction de l'image Docker
- Push vers Google Artifact Registry
Déploiement :
- Déploiement automatique sur Google Cloud Run
- Test de santé post-déploiement
Notifications :
- Statut de déploiement
- URL de l'API déployée

🚀 Utilisation

Test rapide avec curl

# Prédiction de sentiment
curl -X POST "https://your-api-url/predict" \
  -H "Content-Type: application/json" \
  -d '{"text": "Air Paradis has excellent customer service!"}'

# Feedback
curl -X POST "https://your-api-url/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Great flight!",
    "predicted_sentiment": "positive",
    "actual_sentiment": "positive",
    "is_correct": true
  }'

Interface interactive

Documentation Swagger : https://your-api-url/docs
Interface utilisateur moderne : Voir le dossier frontend/ pour l'interface Next.js

🎨 Interface Utilisateur (Frontend)

Une interface Next.js moderne est disponible dans le dossier frontend/ :

Fonctionnalités de l'UI

Analyse de sentiment en temps réel
Système de feedback avec monitoring Google Cloud
Statistiques en temps réel
Design dark avec animations fluides
Particules animées et effets glassmorphism

Démarrage rapide de l'interface

# Naviguer vers le frontend
cd frontend

# Installer les dépendances
npm install

# Configurer l'environnement
cp .env.example .env.local
# Modifier NEXT_PUBLIC_API_URL dans .env.local

# Démarrer en développement
npm run dev
# Interface accessible sur http://localhost:3000

Déploiement du Frontend

L'interface peut être déployée automatiquement sur Google Cloud Run :

# Commit du frontend
git add frontend/
git commit -m "Add frontend"
git push origin main

# Le pipeline GitHub Actions se déclenche automatiquement
# pour les modifications dans frontend/

Pour plus de détails, consultez frontend/README.md.

📝 Notes importantes

Modèles requis : Assurez-vous que les fichiers de modèles sont présents avant le déploiement
Ressources Google Cloud : L'API utilise Cloud Run avec 2GB RAM et 1 CPU
Limitations : Texte maximum de 500 caractères par prédiction
Sécurité : L'API est publique pour les tests, configurez l'authentification en production
Coûts : Surveillez l'utilisation Google Cloud pour éviter les frais inattendus

🆘 Dépannage

Erreurs courantes

Modèle non trouvé :
- Vérifier que les fichiers sont dans models/
- Vérifier les permissions de lecture
Erreur MLflow :
- Vérifier que MLflow UI est démarré
- Vérifier la variable MLFLOW_TRACKING_URI
Erreur Google Cloud :
- Vérifier les permissions du compte de service
- Vérifier que les APIs sont activées

Logs

# Logs locaux
uvicorn app.main:app --log-level debug

# Logs Google Cloud
gcloud logs read "resource.type=cloud_run_revision" --limit=50

Contribution 👥

Pour contribuer au projet :

Fork le repository
Créer une branche feature
Commiter les changements
Créer une Pull Request

🎯 Projet réalisé dans le cadre du cursus Data Scientist - OpenClassrooms

API d'analyse de sentiment pour Air Paradis - MLOps Pipeline

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github/workflows		.github/workflows
app		app
config		config
frontend		frontend
mlruns/327403163948604556		mlruns/327403163948604556
models		models
monitoring		monitoring
notebooks		notebooks
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.frontend		Dockerfile.frontend
README.md		README.md
article_blog_demarche_mlops.md		article_blog_demarche_mlops.md
requirements-windows.txt		requirements-windows.txt
requirements.txt		requirements.txt
urls.md		urls.md

berch-t/air-paradis-sentiment-api

Folders and files

Latest commit

History

Repository files navigation