Spaces:
Sleeping
Sleeping
| # Workflow — finalisation du module IA YELY | |
| Organisation recommandée pour arriver à un livrable démontrable : tests de | |
| type production, suivi des performances, apprentissage continu, | |
| documentation complète, interface web de démo, déploiement. | |
| ## 1. Arborescence cible du dépôt | |
| ``` | |
| yely_ai_module/ | |
| ├── app/ # code de production (déjà en place) | |
| ├── models/ # modèle(s) sérialisé(s) — voir §3 versioning | |
| ├── train/ # scripts d'entraînement (référence) | |
| ├── tests/ | |
| │ ├── test_postprocess.py # ✅ fait | |
| │ ├── test_rules.py # ✅ fait | |
| │ ├── test_api.py # ✅ fait (mocké) | |
| │ ├── test_monitoring.py # ✅ fait (feedback + métriques + endpoints) | |
| │ └── test_integration.py # à lancer : vrai modèle, vraies images | |
| ├── tools/ | |
| │ └── check_seen_image.py # ✅ fait | |
| ├── monitoring/ # ✅ fait — §2 | |
| │ ├── metrics.py # ✅ agrégation logs/api.log (succès, confiance, blocages) | |
| │ └── feedback.py # ✅ collecte + conversion des corrections pompiste | |
| ├── docs/ # ✅ fait — §4 | |
| │ ├── WORKFLOW.md # ce fichier | |
| │ ├── LIMITATIONS.md # ✅ fait | |
| │ ├── ARCHITECTURE.md # ✅ fait | |
| │ ├── PREPROCESSING.md # ✅ fait | |
| │ ├── RECOGNIZER.md # ✅ fait | |
| │ ├── POSTPROCESS_RULES.md # ✅ fait | |
| │ ├── API.md # ✅ fait | |
| │ └── MONITORING.md # ✅ fait | |
| ├── web/ # ✅ fait — §5, interface de démo | |
| │ ├── index.html # démo /analyze | |
| │ ├── stats.html # tableau de bord /metrics + /failures (soutenance) | |
| │ ├── feedback.html # correction d'une lecture (préremplie depuis stats.html) | |
| │ └── config.js | |
| └── requirements.txt | |
| ``` | |
| ## 2. Tests "comme en production" | |
| Objectif : valider le comportement réel, pas seulement la logique unitaire. | |
| 1. **Test d'intégration avec le vrai modèle** (`tests/test_integration.py`) : | |
| envoyer une vraie photo à `recognize_screen` (pas de mock), vérifier que | |
| la réponse a la bonne forme et un temps de réponse mesuré. | |
| 2. **Test API bout-en-bout** : lancer `uvicorn`, envoyer une requête HTTP | |
| réelle via `httpx`/`curl`, sur 3-5 photos couvrant les scénarios du | |
| cahier des charges (§14) : nette/cohérente, floue, incohérente, | |
| montant seul, litres seuls. | |
| 3. **Test de charge léger** : mesurer le temps de réponse sur 10 requêtes | |
| séquentielles (le modèle doit rester chargé en mémoire entre les | |
| requêtes — vérifier qu'il n'y a pas de rechargement). | |
| 4. **Rapport de test** (§15 du cahier des charges) : générer un tableau | |
| photo → attendu → obtenu → écart, à partir des images du dossier | |
| `Images datasetdiversifié/` (celles non utilisées à l'entraînement). | |
| ## 3. Suivi des performances + apprentissage continu | |
| ### Suivi (`monitoring/`) | |
| - Chaque appel à `/analyze` log déjà la requête/réponse dans `logs/api.log`. | |
| À ajouter : un identifiant de version du modèle (`model_version`) dans | |
| chaque entrée, pour pouvoir comparer les performances entre versions. | |
| - `monitoring/metrics.py` : script qui parcourt `logs/api.log` et calcule | |
| périodiquement : taux de succès, distribution des `confidence_score`, | |
| taux de blocage par cause (floue/incohérence/confiance). | |
| ### Apprentissage continu (boucle de feedback) | |
| Le principe : chaque photo traitée par l'API est déjà sauvegardée | |
| (`photos/<uuid>.jpg`). Il manque la boucle qui transforme ces photos en | |
| nouvelles données d'entraînement : | |
| 1. **Endpoint de correction** (`POST /feedback`) : le pompiste (ou un | |
| contrôle a posteriori côté YELY) envoie `transaction_id` + les valeurs | |
| réellement correctes. Stocké dans `monitoring/feedback.jsonl`. | |
| 2. **Script de conversion** (`monitoring/feedback.py`) : transforme les | |
| entrées corrigées en nouvelles entrées `annotations.json` (même format | |
| que l'annotation manuelle), en réutilisant `photos/<uuid>.jpg` comme | |
| image source. | |
| 3. **Ré-entraînement périodique** : relancer `split_lines.py` → | |
| `prepare_doctr_dataset.py` → `finetune_doctr.py` quand un nombre | |
| suffisant de nouvelles corrections est accumulé (ex. tous les 50). | |
| **Important** (retenu de cette session) : ne jamais modifier le dataset | |
| pendant qu'un entraînement tourne (lecture disque à la volée) ; toujours | |
| nettoyer `dataset_lines/`/`dataset_doctr/` avant de régénérer (déjà | |
| corrigé). | |
| 4. **Versioning des modèles** : chaque nouveau modèle entraîné va dans | |
| `models/v<N>/`, avec son propre `history.json`. Le modèle "actif" utilisé | |
| par l'API est un lien/chemin configurable (`CRNN_MODEL_PATH` en variable | |
| d'environnement), pas une réécriture du fichier précédent — pour pouvoir | |
| revenir en arrière si une nouvelle version est pire. | |
| ## 4. Documentation (`docs/`) | |
| Un fichier par aspect, cible = qu'un lecteur qui n'a pas suivi le | |
| développement comprenne le rôle et les choix de chaque module : | |
| - `ARCHITECTURE.md` : schéma du pipeline complet (image → écran → lignes → | |
| CRNN → postprocess → rules → réponse), et pourquoi ce découpage. | |
| - `PREPROCESSING.md` : détection d'écran, découpage en lignes, limites | |
| connues (cas où la détection choisit la mauvaise zone — voir l'incident | |
| du bandeau de marque confondu avec l'écran). | |
| - `RECOGNIZER.md` : choix du CRNN, format d'entrée/sortie, le bug | |
| resize corrigé et pourquoi c'était important. | |
| - `POSTPROCESS_RULES.md` : normalisation numérique, règle de priorité | |
| `fuel_price` configuré > lu à l'écran, moteur de règles de blocage. | |
| - `API.md` : contrat de l'endpoint, exemples de requêtes/réponses. | |
| - `MONITORING.md` : comment lire les logs, comment fonctionne la boucle de | |
| feedback. | |
| - `LIMITATIONS.md` : déjà fait — diversité du dataset, précision actuelle. | |
| ## 5. Interface web de démo | |
| Objectif : une page simple, présentable en soutenance, qui appelle l'API et | |
| affiche le résultat de façon lisible pour un non-développeur (le formulaire | |
| technique `test_api_form.html` existant sert de base, mais mérite une | |
| version "présentation" séparée : moins de champs bruts, plus visuelle). | |
| Contenu minimal : | |
| - Upload/prise de photo (accepte l'appareil photo sur mobile via | |
| `capture="environment"`). | |
| - Choix du prix du litre (pré-rempli, modifiable). | |
| - Affichage : bannière succès/bloqué, valeurs détectées, calculées, statut | |
| de cohérence — pas le JSON brut par défaut (accessible en option). | |
| - Appel vers l'URL de l'API configurée (variable d'environnement au build). | |
| ## 6. Déploiement | |
| **Frontend (`web/`) → Netlify** : parfaitement adapté (fichiers statiques, | |
| pas de build nécessaire), pas de souci particulier. | |
| **API IA → PAS d'hébergement serverless classique (Vercel, Netlify | |
| Functions...).** Point d'attention important avant d'aller plus loin : ce | |
| type d'hébergement limite la taille du build (souvent ~250 Mo décompressés) | |
| et le temps d'exécution par requête. Cette API embarque PyTorch + doctr + | |
| OpenCV, qui dépassent déjà largement cette taille à eux seuls, et | |
| l'inférence CRNN prend actuellement 60-100+ secondes par image (bien | |
| au-delà des temps d'exécution autorisés, même sur les plans payants). | |
| Déployer tel quel sur ce type de plateforme échouera au build ou au | |
| timeout, pas juste "sera lent". | |
| **Décision retenue : Hugging Face Spaces (Docker SDK)** pour l'API. | |
| Gratuit, pensé pour les démos ML, pas de limite stricte de temps | |
| d'exécution comme un hébergement serverless, `Dockerfile` déjà préparé | |
| (`yely_ai_module/Dockerfile`). | |
| Étapes de déploiement (à faire manuellement, action externe) : | |
| 1. Créer un Space sur huggingface.co → SDK "Docker" → visibilité au choix. | |
| 2. Ajouter en tête de `yely_ai_module/README.md` le bloc de configuration | |
| attendu par HF Spaces : | |
| ```yaml | |
| --- | |
| title: YELY AI Module | |
| emoji: ⛽ | |
| colorFrom: blue | |
| colorTo: green | |
| sdk: docker | |
| app_port: 7860 | |
| --- | |
| ``` | |
| 3. Pousser le contenu de `yely_ai_module/` (avec `models/crnn_fuel_pump_best.pt` | |
| inclus) vers le dépôt git du Space. | |
| 4. Noter l'URL publique du Space (`https://<user>-<space>.hf.space`) — c'est | |
| l'URL que le frontend Netlify appellera pour `/analyze`. | |
| 5. Ajouter `CORSMiddleware` dans `app/main.py` pour autoriser le domaine | |
| Netlify du frontend (sinon le navigateur bloquera les réponses). | |
| 6. (Optionnel, payant) Activer le **stockage persistant** du Space et | |
| définir la variable d'environnement `YELY_DATA_DIR` sur son point de | |
| montage — sans quoi `photos/`, `logs/` et `monitoring/feedback.jsonl` | |
| sont perdus à chaque redémarrage/veille du Space. Voir | |
| `docs/MONITORING.md` §3 pour la marche à suivre complète et l'impact si | |
| on s'en passe pour la démo. | |
| ## 7. Ordre d'exécution recommandé (vu le délai serré) | |
| 1. Terminer l'entraînement en cours, figer le modèle livré. | |
| 2. Tests d'intégration réels (§2.1-2.2) — valide que tout fonctionne | |
| vraiment avant de documenter/déployer. | |
| 3. Interface web de démo (§5) branchée sur l'API en local — utilisable pour | |
| répéter la démo même sans déploiement cloud. | |
| 4. Documentation (§4) — peut se faire en parallèle du reste. | |
| 5. Déploiement (§6) — une fois l'hébergement de l'API décidé. | |
| 6. Monitoring/apprentissage continu (§3) — le plus gros morceau, à | |
| présenter comme "conçu et partiellement implémenté" si le temps manque | |
| (c'est un livrable attendu — §8.6/§15 — mais l'essentiel du temps | |
| restant doit sécuriser une démo qui fonctionne). | |