Lab 007: Embeddings et recherche de similarité locale¶
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¶
- Représenter le sens par des vecteurs sans modèle hébergé
- Calculer la similarité cosinus et examiner les voisins
- Distinguer chevauchement lexical et similarité sémantique
- Évaluer la récupération avec des documents pertinents étiquetés
Prérequis¶
- Python 3.10+ pour l'exercice local
- Un éditeur de texte et un terminal
- Lab 022
Résultat et preuves¶
Le lab n'est terminé que lorsque l'apprenant montre des preuves, pas seulement le concept.
| Capacité | Preuve requise |
|---|---|
| Représenter le sens par des vecteurs sans modèle hébergé | evidence/step-1.txt plus un contrôle local réussi |
| Calculer la similarité cosinus et examiner les voisins | evidence/step-2.txt plus un contrôle local réussi |
| Distinguer chevauchement lexical et similarité sémantique | evidence/step-3.txt plus un contrôle local réussi |
| Évaluer la récupération avec des documents pertinents étiquetés | 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] --> E[Local vectorizer]
Q[Query] --> E
E --> V[Vectors]
V --> C[Cosine similarity]
C --> R[Ranked results]
R --> M[Recall@k]
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 embedding_explorer.py avec le corpus OutdoorGear.
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: Comparez les vecteurs de hachage par mots et n-grammes.
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: Modifiez une requête et expliquez le changement de classement.
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: Calculez recall@3 avec les étiquettes fournies.
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 compare la similarité cosinus ?
Réponse
La direction des vecteurs, indépendamment de leur magnitude globale.
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.