Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Olist — Segmentation comportementale des clients

Projet MLOps · École Polytechnique de Thiès · Promotion DIC3

Segmentation non supervisée des clients de la marketplace brésilienne Olist basée sur le comportement d'achat (RFM étendu). Pipeline reproductible avec DVC, suivi MLflow, API REST FastAPI, tests automatisés, Docker et CI/CD GitHub Actions.


Contexte métier

Olist est une marketplace B2B brésilienne. L'équipe marketing souhaite personnaliser ses campagnes en s'appuyant sur des profils clients homogènes construits à partir de leurs comportements d'achat.

Mission : fournir une segmentation actionnable et un contrat de maintenance basé sur la stabilité temporelle des segments.

Source de données : Kaggle — Brazilian E-Commerce (9 tables, ~100k commandes, ~93k clients).

Approche retenue : segmentation comportementale sur 9 features RFM étendues (volumétrie, dépense, satisfaction, logistique, paiement, géographie).

Architecture du projet

olist_segmentation/
├── data/
│   ├── raw/                        ← 9 CSV bruts (gitignored)
│   └── preprocessed/               ← dataset client
│
├── notebooks/
│   ├── 01_eda_feature_engineering.ipynb  ← EDA + construction dataset client
│   ├── 02_modeling.ipynb                  ← Clustering + MLflow (14+ runs)
│   └── 03_temporal_stability.ipynb        ← Stabilité + contrat de maintenance
│
├── src/
│   ├── config.py                   ← chemins + chargement params.yaml
│   ├── data.py                     ← chargement + filtre delivered
│   ├── features.py                 ← NB1 refactoré en fonctions pures
│   ├── preprocessing.py            ← MinMaxScaler
│   ├── train.py                    ← entraînement final + log MLflow
│   ├── predict.py                  ← inférence (utilisé par l'API)
│   ├── evaluate.py                 ← silhouette, DB, CH, ARI
│   └── utils.py                    ← haversine, mapping catégories L1
│
├── api/
│   ├── main.py                     ← FastAPI + Swagger auto
│   └── schemas.py                  ← validation Pydantic (9 features)
│
├── tests/                          ← tests unitaires pytest
├── .github/workflows/ci.yml        ← lint + tests + docker-build
│
├── params.yaml                     ← paramètres centralisés
├── dvc.yaml                        ← pipeline reproductible
├── Dockerfile                      ← image API
├── docker-compose.yml              ← stack dev (API + MLflow)
└── requirements.txt                ← dépendances pinnées

Démarrage rapide

# Cloner
git clone https://github.com/killer-pro/segmentation_client_olist.git
cd segmentation_client_olist

# Environnement virtuel
python -m venv .venv
source .venv/bin/activate       # Linux/Mac
# .venv\Scripts\activate        # Windows

# Dépendances
pip install -r requirements.txt

# Données (placer les 9 CSV dans data/raw/)
kaggle datasets download -d olistbr/brazilian-ecommerce -p data/raw/ --unzip

# Pipeline complet
dvc repro

# API
uvicorn api.main:app --reload   # http://localhost:8000/docs

# MLflow UI
mlflow ui --backend-store-uri file:./mlruns  # http://localhost:5000

Notebooks

Notebook Rôle Sortie
01_eda_feature_engineering.ipynb EDA des 9 tables, feature engineering, construction du dataset client customer_features.csv
02_modeling.ipynb MinMaxScaler, comparaison KMeans/GMM/DBSCAN/Agglo (14+ runs MLflow), K=5 retenu, interprétation des 5 segments segmentation_pipeline.joblib
03_temporal_stability.ipynb Simulation temporelle avec recalcul des features par période (scaler fixe), contrat de maintenance semestriel stability_results.json

Décisions techniques

Décision Choix Justification
Features 9 comportementales (RFM étendu) Les catégories produit dominaient le clustering
Scaler MinMaxScaler Adapté aux features bornées et ratios
PCA Non ARI 0.955 avec/sans PCA, mêmes segments
Algorithme KMeans Domine sur silhouette et DB sur la base complète
K 5 Coude de l'inertie, silhouette 0.29, DB 1.15
Stabilité Semestrielle ARI > 0.85 pendant 6 mois, décrochage à 8 mois

Les 5 segments

Segment Nom Taille Trait dominant
0 Client régulier mitigé 19.0% Revient mais note 3.64/5
1 Acheteur dormant satisfait 24.3% Note 4.73 mais revient après 14 mois
2 Gros acheteur mécontent 12.6% Dépense 192 BRL mais note 1.24/5
3 Client distant premium 9.4% 1375 miles du hub, dépense 202 BRL
4 Client idéal 34.8% Note 5.0, revient en 4 mois

Pipeline DVC

    ┌─────────────────┐
    │ build_features  │ ← data/raw/ → customer_features.csv
    └────────┬────────┘
             ▼
    ┌─────────────────┐
    │   preprocess    │ ← MinMaxScaler → X_scaled.npy
    └────────┬────────┘
             ▼
    ┌─────────────────┐
    │      train      │ ← KMeans K=5 → segmentation_pipeline.joblib
    └─────────────────┘

API REST

Méthode Chemin Description
GET / Métadonnées
GET /health État du modèle
POST /predict Segment d'un client
POST /predict/batch Segmentation en lot
GET /segments Descriptions des 5 segments

Exemple :

curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "nb_orders": 2,
    "total_spend": 250.0,
    "mean_nb_items": 1.5,
    "order_mean_delay": 90.0,
    "mean_review_score": 4.5,
    "mean_delivery_days": 12.0,
    "freight_ratio": 0.15,
    "mean_payment_installments": 3.0,
    "haversine_distance": 500.0
  }'

Tests

pytest tests/ -v --cov=src --cov=api

Docker

# API seule
docker build -t olist-api .
docker run -p 8000:8000 olist-api

# Stack complète (API + MLflow)
docker compose up

Organisation de l'équipe

Phase Responsable Livrable
NB1 — EDA + Features Phase commune 01_eda_feature_engineering.ipynb
NB2 — Modélisation Phase commune 02_modeling.ipynb
NB3 — Stabilité Phase commune 03_temporal_stability.ipynb
DVC + params.yaml Membre 1 dvc.yaml, src/
MLflow + tests Membre 2 tests/, logging
API + Docker + CI Membre 3 api/, Dockerfile, .github/workflows/

Licence

Projet académique — usage pédagogique uniquement.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages