Skip to content

Pingouins API

Architecture

API FastAPI pour aider des scientifiques à identifier des espèces de manchots à partir de données optionnelles (tabulaire et/ou image). L’API renvoie une liste d’espèces probables avec une probabilité.

Objectif

Construire une API de classification multimodale (Tabular + Image) avec journalisation des requêtes, interfaces web de test et notebooks d’entraînement.

Fonctionnalités principales

  • POST /predict : classification (espèce + probabilité)
  • Tous les champs d’entrée sont optionnels
  • Fusion multimodale (tabulaire + image)
  • Journalisation des requêtes/réponses (SQLite)
  • UI web pour consulter les logs (/logs)
  • UI web simple pour tester (/ui/predict)
  • Notebooks pour exploration et entraînement (notebooks/)
  • Collection Postman/Insomnia (tests/)

Modalités d’entrée

Tabulaire (optionnel)

  • bill_length_mm
  • bill_depth_mm
  • flipper_length_mm
  • body_mass_g
  • island
  • sex

Image (optionnel)

  • image_base64 (data URL ou base64 brut)

Paramètres de contrôle

  • model : rf | knn | lr | all
  • top_k : nombre de résultats (défaut 3)
  • w_image : poids de l’image (défaut 0.6)

Réponse API

  • results : top-k espèces avec probabilités
  • all_results : seulement si model="all"
  • meta :
  • used_modalities (tabular/image)
  • fused (true si fusion)
  • w_image utilisé

Lancer l’API (local)

Installation

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install fastapi uvicorn pandas scikit-learn joblib

Démarrage

python run.py

Swagger : http://127.0.0.1:8000/docs
Logs UI : http://127.0.0.1:8000/logs
Predict UI : http://127.0.0.1:8000/ui/predict

Exemple d’appel

curl -X POST "http://127.0.0.1:8000/predict"   -H "Content-Type: application/json"   -d '{"bill_length_mm": 45.1, "bill_depth_mm": 14.5, "model":"rf"}'

Entraînement des modèles

Tabulaire (recommandé)

python train/train_tabular_cv.py

Sorties : - artifacts/penguins_model.joblib - artifacts/model_card.json

Ne pas pousser data/ ni artifacts/*.joblib (ignorés par .gitignore)

Vision (optionnel)

python train/train_vision_hf.py

Sortie : - artifacts/vision_model/

L’API charge automatiquement le modèle vision s’il existe.

Structure du projet

  • api/ : application FastAPI + logs UI
  • models.py : chargement + prédiction (rf/knn/lr)
  • notebooks/ : exploration + training
  • docs/ : documentation
  • tests/ : collection Postman
  • static/ : images d’espèces

Ce que j’ai appris

  • Conception d’API ML avec FastAPI
  • Fusion multimodale (tabulaire + image)
  • Gestion des modèles (joblib)
  • Journalisation SQLite
  • Interfaces de test backend
  • Pipeline d’entraînement et déploiement

Améliorations possibles

  • Authentification API
  • Monitoring modèle
  • Dockerisation
  • Déploiement cloud
  • Ajout d’autres espèces

Liens

Auteur

Ahmad Abo-Alola — Student Project (AI Developer Training)