Clemylia/Mini-Groutouille

📄 Documentation du Modèle : Mini-Groutouille 🥖

Détail	Valeur
🧑‍💻 Auteur	Clemylia
🏗️ Architecture	Aricate V4 (GRU + Attention Additive)
🎯 Type	Micro-Modèle de Langage (SLM)
🗣️ Langue	Français
🗂️ Tâche	Modélisation Causal (Continuation de phrase) / Expérimentation Q/R

---

🌟 Présentation

Mini-Groutouille est un Micro-Modèle de Langage (SLM) développé par Clemylia dans le cadre d'une expérimentation sur des architectures légères. Il est basé sur l'architecture propriétaire Aricate V4, conçue spécifiquement pour être entraînée et utilisée efficacement sur CPU.

Contrairement aux modèles basés sur l'architecture Transformer (comme GPT), Mini-Groutouille utilise une combinaison de Réseaux Neuronaux Récurrents (GRU) et d'un mécanisme d'Attention Additive (Bahdanau) pour la prédiction du mot suivant.

🥐 Corpus d'Entraînement

Le modèle a été entraîné sur un corpus extrêmement réduit (environ 6 phrases) centré sur le thème d'un boulanger et de ses villageois, d'où son nom amusant !

L'objectif de cet entraînement était de valider le pipeline d'entraînement et de publication de l'architecture Aricate V4.

---

🛠️ Détails Techniques de l'Architecture Aricate V4

L'architecture Aricate V4 se distingue par son approche Séquence-à-Séquence (Seq2Seq) simplifiée, qui lui confère une performance surprenante sur les tâches ciblées comme les Questions/Réponses.

• 1. Couche Récurrente (GRU) : Un GRU (Gated Recurrent Unit) est utilisé pour lire la séquence d'entrée (l'historique de la phrase) et en conserver une mémoire (hn). Cela permet au modèle de bien suivre l'ordre des mots.
• 2. Couche d'Attention Additive : Une couche d'attention de type Bahdanau est appliquée sur les sorties du GRU. Cette couche permet au modèle de peser l'importance de chaque mot de l'historique pour la prédiction du mot suivant, produisant un vecteur de contexte ciblé.
• 3. Prédiction : La prédiction finale est effectuée en combinant le Vecteur de Contexte et l'État Caché Final du GRU avant de projeter sur le vocabulaire.

Paramètre	Valeur (Approximative)	Rôle dans Aricate V4
Embedding Dim	32	Taille du vecteur qui représente chaque mot.
Hidden Dim	64	Taille de la mémoire de l'unité GRU.
Num Layers	1	Nombre de couches récurrentes (Minimal pour le micro-modèle).

---

⚙️ Utilisation (Inférence)

Puisque Mini-Groutouille utilise une architecture customisée, vous ne pouvez pas utiliser directement le pipeline de transformers.

Vous devez importer et utiliser les classes définies (AricateModel et WordTokenizer) ainsi que la fonction d'inférence (comme generate_sequence_greedy) pour charger et tester le modèle.

📥 Fichiers à Charger

Fichier	Rôle
model.safetensors	Les poids entraînés du modèle Aricate V4.
config.json	La configuration du modèle (dimensions, couches, etc.).
aricate_tokenizer.json	Le vocabulaire customisé basé sur les mots, essentiel pour l'encodage et le décodage.

💻 Exemple de Chargement (Inférence CPU)

Vous devez utiliser huggingface_hub.from_pretrained_fast pour charger les poids dans la classe AricateModel.

# Exemple de chargement (nécessite la définition des classes Aricate)
from huggingface_hub import from_pretrained_fast
# ... (définition des classes AricateModel, WordTokenizer et fonction de génération)

REPO_ID = "Clemylia/Mini-Groutouille"
model = from_pretrained_fast(REPO_ID, filename="pytorch_model.bin", custom_model_class=AricateModel)

# Ensuite, chargez et initialisez le WordTokenizer avec aricate_tokenizer.json
# ...

---

🚀 Performances Notables

• Efficacité CPU : Conçu pour être entraîné et s'exécuter rapidement sur des ressources CPU limitées.
• Génération Ciblée : L'architecture Seq2Seq simplifiée permet des réponses ciblées dans les tâches de Questions/Réponses, montrant moins de tendance à générer du "charabia" ou des phrases non pertinentes que certains modèles Transformer sous-entraînés--

Exemple dinference :

# ==============================================================================
# 🚀 Inférence Aricate V4 - Chargement depuis Hugging Face
# Ce code charge le modèle et le tokenizer customisés pour la génération de texte.
# ==============================================================================

import torch
import torch.nn as nn
import torch.nn.functional as F
import collections
from huggingface_hub import hf_hub_download, PyTorchModelHubMixin
import os
import json

# --- 1. Définitions des Classes (Réplique de l'architecture d'entraînement) ---

# --- A. WordTokenizer (Customisé pour le chargement) ---
class WordTokenizer:
    """Tokenizer simple pour l'architecture Aricate, chargé depuis le vocabulaire publié."""
    def __init__(self, vocab_data):
        self.word_to_id = vocab_data["word_to_id"]
        # Récupérer max_len_input pour le padding lors de l'inférence
        self.max_len_input = vocab_data["max_len_input"]
        self.id_to_word = {id: word for word, id in self.word_to_id.items()}
        self.vocab_size = len(self.word_to_id)

        # Définition des tokens spéciaux
        self.special_tokens = {
            '<pad>': self.word_to_id.get('<pad>', 0),
            '<unk>': self.word_to_id.get('<unk>', 1),
            '<eos>': self.word_to_id.get('<eos>', 2),
        }

        print(f"Tokenizer chargé. Taille du vocabulaire : {self.vocab_size}")
        print(f"Longueur maximale d'entrée pour le padding : {self.max_len_input}")

    def encode(self, text, add_eos=False):
        words = text.lower().split()
        if add_eos:
            words.append('<eos>')
        ids = [self.word_to_id.get(word, self.special_tokens['<unk>']) for word in words]
        return ids

    def decode(self, ids):
        words = [self.id_to_word.get(id, '<unk>') for id in ids]
        return " ".join(word for word in words if word not in ['<pad>', '<unk>', '<eos>'])

# --- B. AricateAttentionLayer (Inchangé) ---
class AricateAttentionLayer(nn.Module):
    """Couche d'Attention Additive (Bahdanau)."""
    def __init__(self, hidden_dim):
        super(AricateAttentionLayer, self).__init__()
        self.W = nn.Linear(hidden_dim, hidden_dim)
        self.U = nn.Linear(hidden_dim, hidden_dim)
        self.V = nn.Linear(hidden_dim, 1, bias=False)
    def forward(self, rnn_outputs, last_hidden):
        last_hidden_expanded = last_hidden.unsqueeze(1)
        energy = torch.tanh(self.W(rnn_outputs) + self.U(last_hidden_expanded))
        attention_weights_raw = self.V(energy).squeeze(2)
        attention_weights = F.softmax(attention_weights_raw, dim=1)
        context_vector = torch.sum(rnn_outputs * attention_weights.unsqueeze(2), dim=1)
        return context_vector

# --- C. AricateModel V4 (Doit hériter de PyTorchModelHubMixin) ---
class AricateModel(nn.Module, PyTorchModelHubMixin):
    """Architecture Aricate V4 pour Modélisation de Langage."""
    def __init__(self, vocab_size: int, embedding_dim: int, hidden_dim: int, num_layers: int = 1, config: dict = None, **kwargs):
        super(AricateModel, self).__init__()

        # Chargement de la configuration si disponible (utilisé par from_pretrained_fast)
        if config is not None:
             vocab_size = config.get("vocab_size", vocab_size)
             embedding_dim = config.get("embedding_dim", embedding_dim)
             hidden_dim = config.get("hidden_dim", hidden_dim)
             num_layers = config.get("num_layers", num_layers)

        self.vocab_size = vocab_size
        self.embedding_dim = embedding_dim
        self.hidden_dim = hidden_dim
        self.num_layers = num_layers

        self.word_embeddings = nn.Embedding(num_embeddings=vocab_size, embedding_dim=embedding_dim, padding_idx=0)
        self.rnn = nn.GRU(input_size=embedding_dim, hidden_size=hidden_dim, num_layers=num_layers, batch_first=True)
        self.attention = AricateAttentionLayer(hidden_dim)
        self.hidden_to_vocab = nn.Linear(hidden_dim * 2, vocab_size)

    def forward(self, input_words):
        embeds = self.word_embeddings(input_words)
        rnn_out, hn = self.rnn(embeds)
        last_hidden = hn[-1]
        context_vector = self.attention(rnn_out, last_hidden)
        combined_features = torch.cat((context_vector, last_hidden), dim=1)
        logits = self.hidden_to_vocab(combined_features)
        return logits

# --- D. Fonction de Génération (Adaptée) ---
def generate_sequence(model, tokenizer, prompt, max_length, temperature=1.0, do_sample=False):
    """Génère la continuation en utilisant le décodage glouton ou l'échantillonnage avec température."""
    model.eval()

    # Récupérer la longueur maximale d'entrée pour le padding
    max_len_input = tokenizer.max_len_input
    eos_id = tokenizer.special_tokens['<eos>']

    current_ids = tokenizer.encode(prompt, add_eos=False)

    print(f"\n--- Génération ({'Échantillonnée' if do_sample else 'Gloutonne'}) ---")
    print(f"Amorce: '{prompt}'")
    if do_sample:
        print(f"Température: {temperature}")

    with torch.no_grad():
        for _ in range(max_length):
            # 1. Préparer l'entrée (Longueur fixe, padding à gauche)
            input_ids_to_pad = current_ids[-max_len_input:] if len(current_ids) > max_len_input else current_ids
            padding_needed = max_len_input - len(input_ids_to_pad)
            input_ids_padded = [tokenizer.special_tokens['<pad>']] * padding_needed + input_ids_to_pad

            input_tensor = torch.tensor(input_ids_padded).unsqueeze(0)

            # Assurez-vous que le modèle est sur le bon appareil (CPU)
            device = next(model.parameters()).device
            input_tensor = input_tensor.to(device)

            # 2. Forward Pass et Prédiction
            logits = model(input_tensor)

            if do_sample:
                # Appliquer la température et échantillonner
                probabilities = F.softmax(logits / temperature, dim=-1)
                predicted_id = torch.multinomial(probabilities, num_samples=1).item()
            else:
                # Décoding glouton (choix du mot le plus probable)
                predicted_id = torch.argmax(logits, dim=-1).item()

            # 3. Arrêt
            if predicted_id == eos_id:
                break

            # 4. Ajouter le nouveau mot
            current_ids.append(predicted_id)

    # Décodage de la partie générée seulement
    prompt_length = len(tokenizer.encode(prompt))
    generated_ids = current_ids[prompt_length:]
    final_response = tokenizer.decode(generated_ids)

    print(f"Continuation générée: '{final_response}'")
    print("-" * 40)

    return final_response


# --- 2. Code de Chargement et de Test ---
def load_and_test_aricate_model(repo_id: str):
    """Charge le modèle Aricate V4 et son tokenizer depuis Hugging Face et lance l'inférence."""

    # Fichiers à télécharger
    MODEL_FILE = "model.safetensors"
    TOKENIZER_FILE = "aricate_tokenizer.json"

    # Force l'utilisation du CPU
    device = torch.device("cpu")
    print(f"Appareil d'inférence sélectionné: {device}")

    try:
        print(f"\n↻ 1. Chargement du modèle {repo_id}...")

        # ⚠️ Utilisez model_file_name pour spécifier le fichier de poids du modèle
        model = AricateModel.from_pretrained(repo_id, model_file_name=MODEL_FILE)
        model.to(device)
        model.eval()

        print("✅ Modèle Aricate V4 chargé avec succès.")

        print(f"\n↻ 2. Chargement du tokenizer custom...")
        # Téléchargement du fichier de vocabulaire
        tokenizer_path = hf_hub_download(repo_id=repo_id, filename=TOKENIZER_FILE)

        # Chargement des données du tokenizer
        with open(tokenizer_path, 'r', encoding='utf-8') as f:
            tokenizer_data = json.load(f)

        tokenizer = WordTokenizer(tokenizer_data)
        print("✅ Tokenizer custom chargé.")


        # 3. Test d'Inférence
        print("\n--- 3. TEST D'INFÉRENCE ---")

        # Longueur maximale de la continuation
        MAX_GENERATION_LENGTH = 10

        # --- Test en mode Glouton (Greedy) ---
        print("\n--- Test en mode Glouton (Greedy) ---")
        prompts_to_test_greedy = [
            "le boulanger donnait",
            "Marie allait chercher du",
            "il aimait cuisiner"
        ]
        for prompt in prompts_to_test_greedy:
            generate_sequence(model, tokenizer, prompt, MAX_GENERATION_LENGTH, do_sample=False)

        # --- Test en mode Échantillonnage (Sampling) ---
        print(f"\n--- Test en mode Échantillonnage (Sampling, Température=0.7) ---")
        prompts_to_test_sampled = [
            "le boulanger cuisinait des gâteaux qui",
            "Marie et sa mère allaient voir",
            "un met extrêmement délicieux pour"
        ]
        TEMPERATURE_VALUE = 0.7 # Une valeur courante pour l'échantillonnage
        for prompt in prompts_to_test_sampled:
            generate_sequence(model, tokenizer, prompt, MAX_GENERATION_LENGTH, temperature=TEMPERATURE_VALUE, do_sample=True)

    except Exception as e:
        print(f"\n❌ ÉCHEC DU CHARGEMENT OU DE L'INFÉRENCE :")
        print("Ceci peut se produire si le modèle custom n'est pas correctement publié ou si les classes ne sont pas définies.")
        print(f"Détail de l'erreur: {e}")


# --- Lancement de la fonction principale ---
if __name__ == '__main__':
    # Le REPO_ID que vous avez fourni
    ARICATE_REPO_ID = "Clemylia/Mini-Groutouille"
    load_and_test_aricate_model(ARICATE_REPO_ID)