database/README.md

Base de données de monitoring — Agritech Answers

Objectif

Cette base PostgreSQL permet de suivre le comportement de l’API en production dans une logique MLOps.

Elle centralise :

• les appels API
• les étapes internes du pipeline ML
• les prédictions produites
• le détail des recommandations
• les référentiels métier utilisés par l’API
• les distributions de référence utilisées pour le monitoring du drift

---

Structure de la base

Table api_requests

Table principale du monitoring.

1 ligne = 1 appel API

Cette table contient :

• l’endpoint appelé (predict ou recommend)
• le statut de la requête
• la latence de traitement
• le modèle utilisé
• les données d’entrée
• la réponse retournée par l’API
• les erreurs éventuelles

---

Table inference_steps

Suivi technique détaillé du pipeline ML.

Cette table permet de tracer :

• la validation métier
• le feature engineering
• la prédiction
• le post-processing
• les erreurs techniques
• la durée de chaque étape

---

Table api_predictions

Résumé métier des prédictions produites.

Cette table contient :

• le pays concerné
• la culture prédite ou recommandée
• le rendement estimé
• le type de prédiction (predict ou recommend)
• le nombre de candidats évalués

---

Table api_recommendation_details

Détail complet du classement des recommandations.

1 ligne = 1 culture candidate du Top K

Cette table permet de conserver :

• le rang de la culture
• la culture recommandée
• le rendement estimé

---

Table country_crop_mapping

Référentiel métier des associations pays / cultures.

Cette table est générée automatiquement depuis le jeu d’entraînement afin de garantir :

• la cohérence des recommandations
• l’absence de fuite de données
• l’utilisation exclusive des cultures réellement observées

Elle est utilisée par l’API pour :

• valider les entrées utilisateur
• limiter les recommandations aux cultures plausibles

---

Table reference_distributions

Référentiel de distributions utilisé pour le monitoring du drift.

Cette table stocke les valeurs de référence issues du jeu d’entraînement pour :

Variables numériques

• temp
• rainfall_mm
• pesticides
• trend

Variables catégorielles

• area
• item

Elle permet :

• le calcul du PSI (Population Stability Index)
• le suivi des distributions en production
• la détection de dérive des données
• le monitoring ML avancé

---

Relations entre les tables

erDiagram

    api_requests ||--o{ inference_steps : "décompose"

    api_requests ||--o{ api_predictions : "produit"

    api_requests ||--o{ api_recommendation_details : "détaille"

---

Schéma de la base

erDiagram

    api_requests ||--o{ inference_steps : "trace"

    api_requests ||--o{ api_predictions : "produit"

    api_requests ||--o{ api_recommendation_details : "detaille"


    api_requests {

        int id PK

        datetime timestamp

        string endpoint

        int status_code

        boolean success

        string error_message

        float latency_ms

        string model_name

        string model_version

        string input_json

        string output_json

    }


    inference_steps {

        int id PK

        int request_id FK

        string step_name

        boolean success

        string error_message

        float duration_ms

        string details_json

    }


    api_predictions {

        int id PK

        int request_id FK

        string area

        string item

        string recommended_crop

        float predicted_yield

        int n_candidates

        string prediction_type

    }


    api_recommendation_details {

        int id PK

        int request_id FK

        int rank

        string item

        float predicted_yield

    }


    country_crop_mapping {

        int id PK

        string area

        string item

        string source

        datetime created_at

    }


    reference_distributions {

        int id PK

        string feature_name

        string feature_value

        string source

        datetime created_at

    }

---

Initialisation

1. Créer la base PostgreSQL

CREATE DATABASE agritech_monitoring;

---

2. Exécuter le schéma SQL

\i database/schema.sql

---

Génération des référentiels métier

Mapping pays / cultures

Le mapping country_crop_mapping est généré automatiquement depuis le notebook de recommandation.

Cette étape permet de :

• construire les associations pays / cultures
• exporter le référentiel en JSON
• enregistrer les données en base PostgreSQL

Le référentiel est construit uniquement à partir du jeu d’entraînement afin d’éviter toute fuite de données.

---

Distributions de référence

Les distributions de référence sont chargées via :

python -m scripts.load_reference_distributions

Ce script :

• lit le jeu d’entraînement
• extrait les variables suivies
• charge les distributions en base PostgreSQL
• prépare les données nécessaires au calcul du drift et du PSI

---

Monitoring ML

Le système de monitoring permet de suivre :

Monitoring système

• nombre de requêtes
• latence moyenne
• latence par endpoint
• latence par étape d’inférence
• erreurs récentes
• volume d’appels API

Monitoring métier

• cultures les plus recommandées
• utilisation des endpoints
• suivi des prédictions

Monitoring ML

• distributions des variables d’entrée
• dérive des données
• PSI (Population Stability Index)
• comparaison train vs production

---

Utilisation dans l’API

La base est utilisée par l’API pour :

• tracer les appels utilisateurs
• suivre les performances du modèle
• analyser les erreurs
• monitorer les temps d’inférence
• conserver l’historique des recommandations
• valider les cultures disponibles selon les pays
• suivre la dérive des données en production

---

Architecture MLOps

Cette base s’intègre dans une architecture MLOps comprenant :

• FastAPI
• PostgreSQL / Neon
• Docker
• Hugging Face Hub
• GitHub Actions
• Streamlit
• Streamlit Monitoring

---

Objectif du monitoring

Le système de monitoring a pour objectif de :

• superviser les performances techniques
• suivre le comportement du modèle en production
• détecter les anomalies
• analyser les usages métier
• préparer une industrialisation MLOps complète