README.md

---
license: agpl-3.0
language:
- fr
base_model:
- unsloth/Llama-3.2-3B-Instruct
datasets:
- eltorio/appreciation
library_name: peft
---
# Une intelligence artificielle pour écrire des appréciations

## Objectifs

Cette IA s'adresse aux enseignants de l'enseignement secondaire français pour les aider à rédiger automatiquement des appréciations pour leurs élèves.  

## Interface utilisateur

L'interface réalisée avec Gradio propose en entrée:

### Informations générales

- matière enseignée:
  - Histoire-Géographie
  - Histoire-Géographie-Géopolitique-Science-Politique (HGGSP)
  - (des matières seront ajoutées ultérieurement)
- niveau de l'élève (2nde, 1ère, Terminale)
- trimestre (1er, 2ème, 3ème)

### Évaluation

- note de l'élève sur 20
- évolution par rapport au trimestre précédent (notes des 3 trimetres ou N/A si innaproprié)

### Attitude et travail

- travail personnel fourni: slider de 0 à 10
- participation en classe: slider de 0 à 10
- comportement: slider de 0 à 10

L'interface génère une appréciation de 1 à 20 mots adaptée au profil de l'élève. Cette évaluation reste bienveillante et permet à l'élève et à ses parents de comprendre les atouts et les difficultés, tout en proposant des pistes de progression.

## Stratégie de développement

### Phase 1 : MVP (Minimum Viable Product)

- Utilisation d'un modèle LLM de taille moyenne (3B paramètres)
- Création d'un dataset initial de ≈250 appréciations représentatives
- Inclusion d'exemples réels anonymisés d'appréciations d'enseignants
- Interface basique mais fonctionnelle
- Système de feedback utilisateur

En phase 1 le modèle a été entrainé avec [ce code](https://www.kaggle.com/code/eltorio/autoeval-training)

### Phase 2 : Amélioration et validation

- Extension du dataset à 1000+ exemples
- Fine-tuning d'un modèle plus large
- Validation par un panel d'enseignants
- Métriques qualitatives (cohérence, personnalisation)
- Amélioration continue basée sur les retours

### Pipeline technique

1. Prétraitement et normalisation des entrées
2. Construction du contexte spécifique
3. Génération de l'appréciation
4. Post-traitement (vérification longueur/ton/grammaire)

## Notebook de test d'inférence 

Vous pouvez tester ce modèle avec ce notepook Jupyter.  
Pour pouvoir l'essayer dans de bonnes conditions vous devez changer le type d'exécution de Colab pour que l'environnement utilise des GPU T4.  

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/#fileId=https://huggingface.co/eltorio/Llama-3.2-3B-appreciation/blob/main/InferenceTest.ipynb)

## Exemple de code d'inference avec Gradio

Attention ce code est extrêmement lent sans GPU Cuda  

```python
# -*- coding: utf-8 -*-
"""
app.py

This script creates a graphical interface to test an automatic evaluation generation model.
The model is available on Hugging Face and is based on the Llama 3.2 3B-instruct model.
model_id: "eltorio/Llama-3.2-3B-appreciation"

Author: Ronan Le Meillat
License: AGPL-3.0
"""
import gradio as gr
from transformers import AutoProcessor, AutoTokenizer, AutoModelForCausalLM
from peft import AutoPeftModelForCausalLM
import torch
import os

if os.environ.get('HF_TOKEN') is None:
    raise ValueError("You must set the HF_TOKEN environment variable to use this script, you also need to have access to the Llama 3.2 model family")

# sets the main paremeters
hugging_face_model_id = "eltorio/Llama-3.2-3B-appreciation"
base_model_path = "meta-llama/Llama-3.2-3B-Instruct"
device = torch.device('cuda') if torch.cuda.is_available() else torch.device('cpu')

# Define the title, description, and device description for the Gradio interface
device_desc = f"Cette I.A. fonctionne sur {device} 🚀." if device == torch.device('cuda') else f"🐢 Cette I.A. est très très lente sur {device} 🐢."
title = f"Une intelligence artificielle pour écrire des appréciations qui tourne sur {device}"
desc = "Ce modèle vous propose une évaluation automatique."

# Define the long description for the Gradio interface
long_desc = f"Cette démonstration est basée sur le modèle <a href='https://huggingface.co/eltorio/Llama-3.2-3B-appreciation'>Llama-3.2-3B-appreciation</a>, c'est un LLM développé à l'aide de Llama 3.2 3B-instruct!<br><b>{device_desc}</b><br> 2024 - Ronan Le Meillat"

# Load the model
processor = AutoProcessor.from_pretrained(
    base_model_path,
    do_image_splitting=False
)

model = AutoModelForCausalLM.from_pretrained(
    base_model_path,
    torch_dtype=torch.float16,
    low_cpu_mem_usage=True,
).to(device)
model.load_adapter(hugging_face_model_id)
tokenizer = AutoTokenizer.from_pretrained(hugging_face_model_id)

# Define a function to create the conversation from the incoming parameters
def get_conversation(trimestre: str, moyenne_1: float,moyenne_2: float,moyenne_3: float, comportement: float, participation: float, travail: float):

    if trimestre == "1":
        trimestre_full = "premier trimestre"
        user_question = f"Veuillez rédiger une appréciation en moins de 40 mots pour le {trimestre_full} pour cet élève qui a eu {moyenne_1} de moyenne, j'ai évalué son comportement à {comportement}/10, sa participation à {participation}/10 et son travail à {travail}/10. Les notes ne doivent pas apparaître dans l'appréciation."
    elif trimestre == "2":
        trimestre_full = "deuxième trimestre"
        user_question = f"Veuillez rédiger une appréciation en moins de 40 mots pour le {trimestre_full} pour cet élève qui a eu {moyenne_2} de moyenne ce trimestre et {moyenne_1} au premier trimestre, j'ai évalué son comportement à {comportement}/10, sa participation à {participation}/10 et son travail à {travail}/10. Les notes ne doivent pas apparaître dans l'appréciation."
    elif trimestre == "3":
        trimestre_full = "troisième trimestre"
        user_question= f"Veuillez rédiger une appréciation en moins de 40 mots pour le {trimestre_full} pour cet élève qui a eu {moyenne_3} de moyenne ce trimestre, {moyenne_2} au deuxième trimestre et {moyenne_1} au premier trimestre, j'ai évalué son comportement à {comportement}/10, sa participation à {participation}/10 et son travail à {travail}/10. Les notes ne doivent pas apparaître dans l'appréciation."
    messages = [
        {
            "role": "system",
            "content": "Vous êtes une IA assistant les enseignants d'histoire-géographie en rédigeant à leur place une appréciation personnalisée pour leur élève en fonction de ses performances. Votre appreciation doit être en français, et doit aider l'élève à comprendre ses points forts et les axes d'amélioration. Votre appréciation doit comporter de 1 à 40 mots. Votre appréciation ne doit jamais comporter la valeur de la note. Votre appréciation doit utiliser le style impersonnel.Attention l'élément le plus important de votre analyse doit rester la moyenne du trimestre"},
        {
            "role": "user",
            "content": user_question},
    ]
    return messages

# Define a function to infer a evaluation from the incoming parameters
def infere(trimestre: str, moyenne_1: float,moyenne_2: float,moyenne_3: float, comportement: float, participation: float, travail: float) -> str:
    if not torch.cuda.is_available():
        gr.Warning("""No GPU available.<br>
                    The answer will appear in around 10 minutes!<br>
                    But it takes only a few seconds on a decent GPU.<br>
                    Open a message in the <a href='https://huggingface.co/spaces/eltorio/Llama-3.2-3B-appreciation/discussions'>Community Discussion</a>.<br>
                    """,
                  duration=500)
    messages = get_conversation(trimestre, moyenne_1, moyenne_2, moyenne_3, comportement, participation, travail)
    # Tokenize the input
    inputs = tokenizer.apply_chat_template(
        messages,
        tokenize = True,
        add_generation_prompt = True,
        return_tensors = "pt",).to(device)
    # Generate the output
    outputs = model.generate(input_ids = inputs, 
                                        max_new_tokens = 90, 
                                        use_cache = True,
                                        temperature = 1.5,
                                        min_p = 0.1,
                                        pad_token_id=tokenizer.eos_token_id,)
    # Decodes the returned tokens
    decoded_sequences = tokenizer.batch_decode(outputs[:, inputs.shape[1]:],skip_special_tokens=True)[0]
    return decoded_sequences

# Create a Gradio interface with the infere function and specified title and descriptions
autoeval = gr.Interface(fn=infere, inputs=[
        gr.Radio(
            ["1", "2", "3"], value="1", label="Trimestre en cours", info="Sélectionnez le trimestre en cours à l'aide des boutons radio"
        ),
        gr.Slider(0, 20,label="Moyenne au premier trimestre", value=10, info="Moyenne sur 20 obtenue au premier trimestre"),
        gr.Slider(0, 20,label="Moyenne au second trimestre", value=10, info="Moyenne sur 20 obtenue au second trimestre"),
        gr.Slider(0, 20,label="Moyenne au troisième trimestre", value=10, info="Moyenne sur 20 obtenue au troisième trimestre"),
        gr.Slider(0, 10, value=5, label="Comportement", info="Comportement (1 à 10)"),
        gr.Slider(0, 10, value=5, label="Participation", info="Participation (1 à 10)"),
        gr.Slider(0, 10, value=5, label="Travail", info="Travail (1 à 10)"),
        
    ], outputs="text", title=title, 
                description=desc, article=long_desc)

# Launch the Gradio interface and share it
autoeval.launch(server_name="0.0.0.0", share=True, ssr_mode=False)
    

```
## Sécurité et éthique

- Il est hors de question de mettre des appréciations automatiques, elles devront être validée et eventuellement corrigée par l'enseignant.

## Référencer ce modèle

- Utiliser la citation *bibtex* suivante:
```bibtex
@misc {ronan_l.m._2024,
	author       = { {Ronan L.M.} },
	title        = { Llama-3.2-3B-appreciation (Revision 4441ca8) },
	year         = 2024,
	url          = { https://huggingface.co/eltorio/Llama-3.2-3B-appreciation },
	doi          = { 10.57967/hf/3667 },
	publisher    = { Hugging Face }
}
```