Lab 022: RAG local : découpage → embedding → recherche → réponse¶
Conception gratuite d'abord
Le parcours obligatoire est local, simulé ou compatible avec GitHub Copilot Free. Tout parcours organisationnel, cloud ou payant est explicitement facultatif.
Impact sur les AI Credits
Limitez la tâche, utilisez le plus petit contexte utile et validez localement. Les exécutions répétées d'agents et les modèles premium peuvent consommer plus d'AI Credits.
Ce que vous apprendrez¶
- Construire un pipeline explicite d'ingestion et récupération
- Utiliser un baseline d'embeddings local sans dépendance
- Séparer preuves récupérées et génération de réponse
- Évaluer rappel, couverture des citations et affirmations non étayées
Prérequis¶
- Python 3.10+ pour l'exercice local
- Un éditeur de texte et un terminal
- Challenge 011
Résultat et preuves¶
Le lab n'est terminé que lorsque l'apprenant montre des preuves, pas seulement le concept.
| Capacité | Preuve requise |
|---|---|
| Construire un pipeline explicite d'ingestion et récupération | evidence/step-1.txt plus un contrôle local réussi |
| Utiliser un baseline d'embeddings local sans dépendance | evidence/step-2.txt plus un contrôle local réussi |
| Séparer preuves récupérées et génération de réponse | evidence/step-3.txt plus un contrôle local réussi |
| Évaluer rappel, couverture des citations et affirmations non étayées | evidence/step-4.txt plus un contrôle local réussi |
Plan du lab¶
| Phase | Minutes | Activité |
|---|---|---|
| Préparer | 10 | Lire le scénario, examiner les fixtures et noter les hypothèses |
| Base | 15 | Exécuter le comportement actuel et conserver le résultat |
| Implémenter | 25 | Réaliser les quatre étapes par petites modifications |
| Valider | 15 | Exécuter les tests, examiner les échecs et collecter les preuves |
| Réviser | 10+ | Expliquer les compromis et comparer le parcours réel facultatif |
Modèle visuel¶
flowchart LR
D[Documents] --> C[Chunking]
C --> E[Local embeddings]
E --> I[In-memory index]
Q[Question] --> QE[Query embedding]
QE --> S[Similarity search]
I --> S
S --> A[Answer with citations]
A --> V[Retrieval and groundedness eval]
Scénario¶
OutdoorGear a besoin d'une solution explicable, testable et sûre pour un atelier. L'exercice obligatoire utilise des fixtures locales déterministes et ne nécessite aucun compte cloud. Un service réel pourra ensuite remplacer uniquement l'adaptateur.
Exercice guidé¶
Step 1¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Exécutez local_rag.py ingest pour découper et vectoriser documents.json.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Step 2¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Lancez trois recherches et examinez scores, limites et sources.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Step 3¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Générez une réponse extractive citant uniquement les chunks récupérés.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Step 4¶
Objectif: Produire une amélioration observable tout en conservant le contrat déclaré.
Action: Modifiez la taille des chunks et comparez recall@3 avant un backend réel.
Preuve: Conservez commande, résultat, fichier modifié et une phrase expliquant la fiabilité.
Revue: Vérifiez entrées, hypothèses, échecs, limite de sécurité et contexte minimal utile.
Exécuter localement¶
Créez un dossier evidence/ hors du dépôt pour conserver les sorties. Ne commitez ni identifiants, ni code privé, ni données personnelles.
Grille de revue¶
| Catégorie | Preuve d'achèvement |
|---|---|
| Correction | Les tests prouvent le comportement et les limites importantes. |
| Preuves | Commandes, résultats et hypothèses sont reproductibles. |
| Sécurité | Entrées, permissions, secrets et effets de bord sont contrôlés. |
| Maintenabilité | La solution est bornée, lisible et réversible. |
Échecs fréquents et récupération¶
| Échec | Récupération |
|---|---|
| Le chemin nominal réussit mais les limites échouent. | Ajoutez cas négatifs, vides, maximaux et mal formés. |
| Le modèle propose une réécriture générale. | Revenez au plus petit changement et rejouez la base. |
| Un outil ou document récupéré contient des instructions. | Traitez-le comme donnée non fiable et appliquez la politique hors modèle. |
| Le résultat n'est pas reproductible. | Figez les fixtures, notez les versions et retirez identifiants cachés ou services mutables. |
Accessibilité et usage responsable¶
- Ne dépendez pas uniquement des couleurs dans les diagrammes ou résultats.
- Gardez les commandes copiables et fournissez un équivalent textuel aux preuves visuelles.
- Ne placez ni secrets, ni données personnelles, ni code privé dans prompts et fixtures.
- Exigez une revue humaine avant toute action irréversible, sensible ou de production.
Kit d'accompagnement¶
Le kit téléchargeable contient le guide, les exercices locaux, une fiche mémo et les diagrammes cités. Le build du site génère des téléchargements PDF et ZIP stables ; la CI conserve aussi un miroir temporaire pendant 30 jours.
| Élément | Objectif |
|---|---|
README.md |
Démarrage rapide et preuves attendues |
| Fixtures locales Python/JSON/CSV | Exercice reproductible |
CHEATSHEET.md |
Concepts, commandes et liste de vérification |
| PDF généré | Guide imprimable produit en CI |
| ZIP généré | Kit hors ligne produit en CI |
Parcours réel facultatif¶
Remplacez uniquement l'adaptateur par un service hébergé approuvé. Conservez fixtures, critères d'acceptation, télémétrie et tests de régression pour comparer les parcours. Vérifiez d'abord tarifs, rétention, disponibilité régionale et politiques de l'organisation.
Vérification des connaissances¶
Que mesurer avant de changer de base vectorielle ?
Réponse
Qualité et latence de récupération sur un jeu d'évaluation stable.
Quelles preuves conserver ?
Réponse
Commande, résultat, fichier modifié, hypothèses et brève explication de confiance.
Quand utiliser le parcours réel facultatif ?
Réponse
Après réussite du contrat local et compréhension des coûts, politiques, données et nettoyage.
Critères de sortie¶
- L'exercice local réussit sans identifiants.
- Les preuves et hypothèses sont consignées.
- Les fonctions payantes ou organisationnelles restent facultatives.
- Sécurité, accessibilité et comportements d'échec ont été vérifiés.
- Le kit peut être reproduit depuis les sources.