← Accueil
// Documentation

Comment
ça marche

Quizzoss transforme des notes Markdown en quiz interactif piloté par l'IA de Google. Cette page explique le pipeline, le rôle de chaque composant, et pourquoi ça fonctionne mieux qu'un chatbot générique.


// 01 — Le principe fondamental

Le RAG en 30 secondes

RAG signifie Retrieval-Augmented Generation — génération augmentée par récupération. L'idée : plutôt que de demander à l'IA de générer des questions "sur la géopolitique" depuis sa mémoire globale, on lui donne le bon paragraphe, au bon moment.

L'IA ne travaille jamais à l'aveugle. À chaque étape — génération de question, évaluation, tutorat — elle reçoit exactement le contenu de la note concernée. Le résultat : des questions précises, ancrées dans ce qui a réellement été étudié.

Sans RAG
"Parle-moi de X"
Réponse générique
Mémoire globale
Résultat
Questions hors-sujet
Avec RAG (Quizzoss)
Note section §3.2
Contexte injecté
Gemini lit le texte
Résultat
Questions précises

// 02 — Le pipeline complet

Des notes aux questions

Le pipeline se déroule en deux temps : une phase de préparation (hors-ligne, déclenchée manuellement), et une phase de quiz (en direct, côté serveur).

📁
Source
Notes .md
Le coffre-fort de notes
Fichiers Markdown organisés en dossiers. Compatible avec Obsidian — images, liens wiki, block embeds (![[#^id]]) sont supportés.
↓ scanner.py lit chaque fichier
✂️
Étape 1
Découpage
Chunking par titre
Chaque note est découpée en sections selon ses titres (H1, H2, H3…). Chaque section devient un chunk — l'unité atomique du quiz. Résultat stocké dans chunks.json.
↓ prebuild.py envoie chaque chunk à Gemini
Étape 2 — IA
Génération
Gemini génère pour chaque chunk
1 question — précise, testable sur le contenu.
1 réponse attendue — formulation idéale.
3 distracteurs — fausses réponses du même type (dates vs dates, concepts vs concepts) pour le mode QCM.
↓ stocké dans questions.json
🗄️
Cache
Banque de questions
questions.json
Toutes les questions pré-générées. Pas d'appel IA au moment du quiz — la latence est quasi-nulle. Le fichier est mis à jour via le bouton "↻ Mettre à jour les questions".
↓ au démarrage du quiz
🎲
Quiz
Session × 10
10 questions tirées au hasard
Le serveur sélectionne 10 questions aléatoires (filtrées par sujet si sélectionné). Chaque question embarque sa note source pour l'évaluation et le tutorat.

// 03 — Le découpage en sections

Pourquoi découper ?

Une note entière peut faire des dizaines de pages. Injecter tout ça dans le contexte de l'IA à chaque question serait lent, coûteux, et produirait des questions vagues. En découpant par titre, chaque question porte sur un seul concept précis.

chunks.json — exemple
Géopolitique / Énergie mondiale.md
H1 · Introduction chunk #1
H2 · Production d'énergie en France chunk #2 · question générée ✓
H3 · Part du nucléaire chunk #3
H2 · Mix énergétique européen chunk #4
→ chunk #2 → Gemini → "Quel est le principal mode de production d'électricité en France ?" + réponse + 3 distracteurs

// 04 — L'évaluation nuancée

Pas de correspondance exacte

Comparer deux chaînes de texte mot pour mot ne fonctionne pas : "75%" et "soixante-quinze pour cent" sont la même réponse. Gemini relit le contexte complet et juge avec nuance.

Contenu de la note
La France produit ~70% de son électricité via le nucléaire…
+
Question + Réponse attendue
"Quel est le taux de production nucléaire ?" → "environ 70%"
Réponse utilisateur (exemples)
"72%" → ±10% → Réussi "le nucléaire" → incomplet → Incomplet "2024" → hors-sujet → Échoué
Réussi
Réponse correcte, éventuellement formulée différemment ou dans la tolérance ±10% pour les chiffres
Incomplet
Partiellement correct — bonne piste mais un élément clé manque
Échoué
Réponse inexacte ou hors-sujet par rapport à la note
Règle sur les dates
La tolérance ±10% s'applique aux quantités numériques (pas aux dates). "1945" n'est pas équivalent à "1950" — les dates sont évaluées strictement.

// 05 — Le tuteur IA

Le contexte complet, pas juste la question

Le tuteur reçoit beaucoup plus qu'une simple question. À chaque message, Gemini dispose du contexte complet de l'interaction — ce qui lui permet de répondre avec précision et cohérence sur toute la session.

Contenu de la note
Le texte exact de la section source — la "mémoire" du tuteur sur ce sujet.
La question posée
La question générée pour cette note — donne le fil conducteur de l'échange.
La réponse donnée
Ce qui a été répondu — le tuteur peut corriger ou approfondir directement.
L'évaluation
Réussi / Incomplet / Échoué — le tuteur sait déjà où ça coince.
↓ tout ça constitue le prompt système du tuteur ↓
Historique de la conversation
Chaque message s'ajoute à l'historique. Le tuteur garde le fil de toute la discussion — y compris dans le bilan de fin de session, où l'historique de chaque question est préservé.
Au-delà de la note
Si la réponse à une question dépasse ce qui est dans la note, le tuteur peut l'expliquer — il le signale brièvement. L'objectif est de vraiment comprendre, pas de répéter le texte.

// 06 — Le mode QCM

Des distracteurs intelligents

Le mode QCM propose 4 options : la bonne réponse + 3 distracteurs générés par Gemini au moment de la création de la question. La contrainte : les distracteurs doivent être du même type que la bonne réponse.

Si la réponse correcte est une date (1945), les distracteurs sont aussi des dates (1939, 1918, 1973) — pas des concepts ou des noms propres. Ça rend le QCM difficile pour les bonnes raisons.

Bonne réponse
~70%
+
Distracteurs (même type)
45% · 88% · 31%
Options mélangées
4 choix · ordre aléatoire
Évaluation QCM
En mode QCM, l'évaluation est immédiate et locale — pas d'appel API. Le bon choix est connu à l'avance ; l'IA n'intervient qu'ensuite via le tuteur si une question est posée.

// 07 — Les modèles utilisés

Gemini Flash — pourquoi ?

Quizzoss utilise Gemini 2.5 Flash pour toutes les tâches. Flash est rapide et économique — adapté à des appels fréquents (un par chunk lors du prebuild, un par réponse lors de l'évaluation).

Sur les tâches structurées (génération de question, évaluation), le mode "thinking" est désactivé : Gemini répond directement en JSON sans raisonnement intermédiaire. Plus rapide, moins coûteux, aussi précis pour ces tâches courtes. Le thinking reste actif pour le tutorat, où le raisonnement en plusieurs étapes est utile.

Génération de question
Flash · thinking désactivé · 1 appel / chunk · sortie JSON
Évaluation de réponse
Flash · thinking désactivé · 1 appel / réponse · sortie JSON
Tutorat (chat)
Flash · thinking actif · historique complet injecté · réponse libre