Mode opératoire

Principe

predict prévoit les valeurs futures d'une série temporelle avec Timestral (Mistral AI), un modèle de fondation zero-shot : il n'y a aucun entraînement à lancer. Le modèle lit l'historique fourni (le « contexte ») et en déduit la suite, sous forme probabiliste. La qualité se vérifie par backtest et s'améliore en donnant plus d'historique et des covariables pertinentes.

Parcours

flowchart TD
    A["Étape 1 : Créer une série
nom, unité, pas de temps"] --> B["Étape 2 : Importer l'historique
CSV date,valeur"]
    B --> C{"Des facteurs externes
influencent la série ?"}
    C -- oui --> D["Étape 3 : Ajouter des covariables
passées ou connues dans le futur"]
    C -- non --> E
    D --> E["Étape 4 : Backtest
mesurer la qualité"]
    E --> F{"MAE et couverture
satisfaisantes ?"}
    F -- non --> G["Plus d'historique, autres covariables,
modèle plus grand"]
    G --> E
    F -- oui --> H["Étape 5 : Prévision réelle
médiane et intervalles 80 % / 90 %"]
    H --> I["Étape 6 : Mettre à jour les données
et relancer"]
    I --> H

1. Créer une série

• Nom unique et unité (facultative, pour mémoire).
• Pas de temps : 15 minutes, 1 heure, 1 jour ou 1 semaine. Toutes les dates sont ramenées sur cette grille régulière ; un pas sans valeur est traité comme une valeur manquante, ce que le modèle sait gérer.

2. Importer l'historique

• Coller un CSV ou envoyer un fichier, une ligne par pas : date,valeur. Une ligne d'en-tête est ignorée, les lignes commençant par # aussi.
• Séparateur , ; ou tabulation. Avec ; ou tabulation, la virgule décimale est acceptée (12,5).
• Dates : 2026-01-31, 2026-01-31 14:00, RFC 3339 ou 31/01/2026. Sans fuseau, l'heure est lue en UTC.
• Mise à jour : réimporter une date déjà présente remplace sa valeur. Pour ajouter les derniers jours, il suffit d'importer les nouvelles lignes.
• Minimum 16 pas d'historique pour prévoir ; au-delà de 32 768 pas, seuls les plus récents sont utilisés.

date,valeur
2026-01-01,120
2026-01-02,134.5
2026-01-03,128

3. Covariables exogènes (facultatif)

Facteurs externes qui aident à expliquer la série (météo, fréquentation, calendrier, promotions). Même format CSV, sur la même grille de dates.

Une covariable sans aucune valeur sur la période du contexte est ignorée.

4. Lancer une prévision

• Modèle : Timestral-209M par défaut, le plus précis, chargé au démarrage (environ 0,2 s pour une semaine horaire sur le serveur). 5M, 28M et 123M restent disponibles pour comparer ; ils sont chargés au premier usage.
• Horizon : nombre de pas à prévoir, de 1 à 4 096.
• Backtest : masque les horizon derniers points, les prévoit comme s'ils étaient inconnus, puis compare aux valeurs réelles.

5. Lire le résultat

• Médiane : la valeur centrale prévue (une chance sur deux d'être au-dessus).
• Intervalle 80 % (quantiles 0,1 à 0,9) et 90 % (0,05 à 0,95) : la plage où la valeur réelle devrait tomber dans 80 % / 90 % des cas. Plus la bande est large, plus le modèle est incertain.
• MAE (backtest) : écart moyen absolu entre la médiane et le réel, dans l'unité de la série. Plus bas = mieux.
• Référence saisonnière (backtest) : MAE obtenue en prévoyant chaque pas par la valeur observée un cycle plus tôt (une semaine pour les pas horaires ou plus fins, un an pour les pas journaliers et hebdomadaires). En vert si Timestral fait mieux : c'est le seuil à battre pour que le modèle apporte quelque chose.
• Couverture 80 % (backtest) : part des valeurs réelles tombées dans l'intervalle 80 %. Proche de 80 % = incertitude bien calibrée ; bien en dessous = modèle trop confiant.
• La dernière prévision est enregistrée et réaffichée à l'ouverture de la série.

Ce qui se passe lors d'une prévision

sequenceDiagram
    actor U as Utilisateur
    participant W as predict (Go)
    participant DB as PostgreSQL
    participant F as forecaster (Python)
    participant M as Timestral
    U->>W: Lancer (modèle, horizon, backtest)
    W->>DB: historique + covariables
    DB-->>W: points datés
    Note over W: alignement sur la grille du pas
trous = valeurs manquantes
backtest : retire les H derniers points
    W->>F: POST /forecast (contexte, covariables)
    F->>M: forecast (zero-shot, CPU)
    M-->>F: 21 quantiles par pas
    F-->>W: quantiles
    Note over W: backtest : MAE de la médiane
et couverture de l'intervalle 80 %
    W->>DB: enregistre la prévision
    W-->>U: graphique historique + prévision

Améliorer la qualité

• Au moins un cycle saisonnier complet d'historique : une semaine pour une série horaire, un an pour une série journalière ou hebdomadaire. Mesuré sur des ventes hebdomadaires réelles (voir Test ventes) : avec 25 semaines, Timestral ne voit pas la baisse estivale et ne fait pas mieux qu'une moyenne des 4 dernières semaines ; avec 18 mois, l'erreur sur le CA passe de 23,5 % à 13,6 %. Un avertissement s'affiche sur la série quand l'historique est trop court.
• Toujours comparer à la référence saisonnière (même période un cycle plus tôt), et pas seulement à la MAE : sur des totaux très réguliers d'une année sur l'autre, elle peut battre le modèle.
• Juger sur plusieurs backtests : un seul backtest ne mesure qu'une période ; refaire l'essai en retirant des points récents pour vérifier que le résultat tient.
• Ajouter les covariables qui pilotent réellement la série, en « connue dans le futur » quand leurs valeurs à venir sont disponibles. Une covariable redondante avec l'historique dégrade la prévision : sur ces mêmes ventes, l'évolution N-1 du prix ou du panier moyen a fait passer l'erreur de 13,6 % à 15,5 %, et la série N-1 n'apporte presque rien quand l'historique couvre déjà l'année précédente.
• Comparer les modèles par backtest sur le même horizon et garder celui qui a la plus faible MAE avec une couverture correcte.
• Le fine-tuning de Timestral n'est pas disponible publiquement : on améliore les données, pas le modèle.