🧪 Regrelio

Un outil puissant et automatisé pour l'évaluation textuelle et la comparaison de Modèles de Langage (LLMs). Destiné aux chercheurs et ingénieurs ML, Regrelio permet d'identifier les régressions de performance (catastrophic forgetting) lors du fine-tuning, d'évaluer l'impact des techniques de quantification (quantization) et de monitorer l'évolution de vos modèles via un dashboard interactif.

🎯 Pourquoi cet outil ?

Lors de l'entraînement (Fine-Tuning, DPO, RLHF) d'un LLM pour spécialiser ses compétences, il est fréquent qu'il "oublie" ses capacités générales (raisonnement, code, logique mathématique). Ce projet permet de :

1. Comparer un modèle de base et un modèle fine-tuné sur un ensemble configurable de benchmarks (JSON).
2. Scanner la dégradation liée à la quantification (fp16 vs 8bit vs 4bit).
3. Bloquer une pipeline CI/CD (via des seuils configurables et un golden benchmark) en cas de régression critique.
4. Visualiser les résultats grâce à une interface Streamlit intuitive.

✨ Fonctionnalités clés

• ⚖️ Comparaison A/B Automatique : Évaluez Base vs Fine-tuned avec génération locale (compare.py main).
• 🧮 Scan Quantization : Mesurez le compromis entre perte de performance et gain de vitesse (TPS) sur différentes quantifications fp16, 8bit, et 4bit.
• 👨‍⚖️ LLM-as-a-Judge & Exact Match : Supporte l'évaluation par règles strictes (regex, rapidfuzz), exécution de code isolée via subprocess + timeout (non sandboxée), et LLM externe agissant comme juge (via OpenAI ou Ollama).
• 🚀 Intégration CI/CD : Détection de régression avec marge d'erreur, et "Golden Gate" limitant le déploiement.
• 📈 Dashboard Streamlit Local : Affichez et analysez graphiquement les différences de metrics et temps de réponse.
• ⚡ Optimisation : Générations en batch batching, hashing SHA-256 pour caching local et gestion de timeouts.

📁 Structure du Projet

regrelio/
├── benchmarks/         # Outils d'évaluation sous forme JSON (golden, reasoning, code...)
├── dashboard/          # Application front-end interactive (Streamlit)
│   └── app.py
├── metrics/            # Algorithmes de matching exact, fuzzy, et exécution
│   ├── judge.py        # LLM-as-a-Judge (OpenAI / Ollama Local)
│   └── scorer.py       # Metrics classiques et execution de code
├── models/             
│   └── loader.py       # Pipeline HuggingFace (BitsAndBytes, Accelerate, Torch)
├── results/            # Fichiers de dump (JSON, MD et données de cache)
└── compare.py          # Point d'Entrée CLI Typer 

🛠️ Installation

Option rapide (PyPI)

# Installe tout (LLM + quantization + dashboard)
pip install regrelio[all]

Autres variantes utiles :

# Juste le coeur (sans LLM)
pip install regrelio

# LLM (torch + transformers)
pip install regrelio[llm]

# LLM + quantization
pip install regrelio[llm,quant]

# Dashboard uniquement
pip install regrelio[dashboard]

Option dev (depuis le repo)

# 1. Cloner le repository
git clone https://github.com/Drescargot/regrelio.git
cd regrelio

# 2. Créer un environnement virtuel
python -m venv .venv
source .venv/bin/activate  # Sous Windows: .venv\Scripts\activate

# 3. Installer les dépendances
pip install --upgrade pip
pip install -e .[llm,quant,dashboard,dev]

Note : Un GPU NVIDIA avec support CUDA est fortement recommandé.

🚀 Utilisation

L'outil repose sur la CLI multi-commandes compare.py. Voici un tableau récapitulatif des commandes en fonction de ce que vous souhaitez accomplir :

🎯 Que souhaitez-vous faire ? (Guide Rapide)

Objectif / Cas d'usage	Commande Complète	Description
Comparer 2 modèles (A/B Test)	regrelio main --base-model "X" --ft-model "Y"	Détecte les régressions entre un modèle de base et son fine-tune via Exact Match.
Évaluation Sémantique (LLM Judge)	regrelio main --judge --judge-backend ollama	Utilise un LLM (Ollama ou OpenAI) pour noter des réponses abstraites (résumé, traduction).
Sécuriser une CI/CD (Golden Gate)	regrelio main --strict-golden	Échoue le pipeline (Exit Code 1) si un benchmark critique (golden) régresse ou est raté.
Analyser l'impact Quantization	regrelio scan-quantization --model "X" --modes "fp16,8bit,4bit"	Mesure le compromis entre perte de score et gain de vitesse (TPS) de la quantification.
Explorer les données (Dashboard)	regrelio serve	Interface graphique Streamlit interactive pour visualiser les deltas et performances.

---

1. Détail : Comparaison Base vs Fine-Tuned (A/B Test)

Générez un rapport détaillé comparant un modèle base et un tune. En cas de régression forte (par défaut configurable) ou si le --strict-golden est activé, un Exit Code 1 est envoyé (pratique pour vos CI/CD).

regrelio main \
  --base-model "TinyLlama/TinyLlama-1.1B-Chat-v1.0" \
  --ft-model "MonSuperModele-FineTune-1.1B" \
  --benchmarks "reasoning,code,golden"

💡 Note pour les modèles privés : Vous pouvez tout à fait utiliser des modèles propriétaires téléchargés ou entraînés localement sans accès à internet. Il suffit de donner le chemin vers le dossier contenant le modèle (ex: --base-model "./mes_poids/model_v1" --ft-model "/mnt/data/model_v2_finetuned").

Options notables:

• --batch-size N : Parallélisez la génération localement.
• --cache : Active le cache des résultats inférés pour itérer vite.
• --judge : Active l'évaluation sémantique complexe par appel externe (OpenAI/Ollama).

2. LLM-as-a-Judge (Évaluation sémantique)

Pour exploiter LLM as a Judge au lieu d'Exact Matchs traditionnels sur des tâches abstraites :

regrelio main --judge \
  --judge-backend openai \
  --judge-model gpt-4o-mini \
  --judge-types summary,translation,tone

(Identique avec un backend Local via ollama)

3. Scan Dégradation de Quantization

Visualisez ce que coûte réellement la quantification (Loss vs Vitesse TPS) :

regrelio scan-quantization \
  --model Qwen/Qwen2-1.5B \
  --modes "fp16,8bit,4bit" \
  --benchmarks "reasoning,code"

4. Lancer le Dashboard interactif Streamlit

Ouvrez une interface visuelle pour explorer en détail les révisions générées.

regrelio serve --results-dir results --port 8501

📝 Créer ses propres benchmarks

Insérez simplement un JSON dans /benchmarks. Exemple (benchmarks/math.json) :

[
  {
    "id": "m01",
    "type": "math",
    "prompt": "Combien font 7 + 5 ? Réponds uniquement le nombre.",
    "expected_answer": "12"
  }
]

🤝 Contribution & Support

Les Pull Requests (nouveaux scoreurs, optimisations vLLM) sont les bienvenues. N'hésitez pas à ouvrir un Ticket !

📜 Licence

Apache 2.0