Aller au contenu
English

Remise du dépôt

  • Leçon 20
  • 80 min
  • Module 7 : Préparer la présentation du portfolio

Où nous en sommes

Dans le module 6, nous avons livré le produit comme démo reproductible, avec un retour arrière et des limites d'utilisation. Mais le projet dépend encore de vous : personne d'autre ne sait comment l'exécuter ni ce qu'il ne fait pas. Dans cette leçon, nous rendons le dépôt utilisable par une personne inconnue, avec chaque affirmation liée à sa preuve, comme une recette qu'un ami peut vraiment suivre.

Ce que vous saurez faire

Rendez votre dépôt utilisable par une personne qui ne l’a jamais vu. Cette personne doit pouvoir l’exécuter et comprendre son fonctionnement. Elle doit voir d’où viennent les données, sa qualité et ce qu’il ne fait pas. Chaque affirmation renvoie à une preuve.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 80 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre projet à la fin du module 6. Pour le projet intégrateur guidé, utilisez l’instantané end-of-m06, la copie propre utilisée au module 6 : python -m pytest affiche 108 passed (108 tests réussis).
  • Docker en marche, environ 5 Go d’espace disque libre et assez de place pour une deuxième copie du projet.

L’instantané end-of-m06 contient déjà les documents de Sam pour ce module : README.md, docs/portfolio-checklist.md, docs/demo-script.md et docs/reflection.md. Le module 7 n’ajoute aucun code. Vous lisez les versions de Sam et rédigez les vôtres. Les commandes ont été testées sur macOS (Apple silicon); celles pour Windows (PowerShell) sont écrites, mais non testées.

Votre ami a adoré votre soupe et demande la recette. Vous la connaissez par cœur, alors vous écrivez trois lignes : « Oignons, carottes, bouillon. Cuire jusqu’à ce que ce soit prêt. Ajouter du sel. » Votre ami essaie, mais le résultat est mauvais. Quel bouillon? Combien de carottes? Combien de temps veut dire « jusqu’à ce que ce soit prêt »?

Une bonne fiche de recette répond aux questions avant qu’on les pose. Elle indique les ingrédients et les quantités. Elle donne les étapes dans l’ordre et explique pourquoi une étape compte : « faites revenir les oignons d’abord, sinon la soupe aura un goût cru ». Elle indique d’où vient un ingrédient spécial. Elle décrit le goût de la soupe réussie. Et elle précise ce qui ne fonctionne pas : « ne la congelez pas; les pommes de terre ramollissent ».

La personne qui a écrit la recette ne voit pas ces lacunes. Elle connaît les réponses, alors la courte fiche lui semble complète. Seule une personne qui cuisine à partir de la fiche trouve ce qui manque.

Le projet de Sam réussit tous les tests. La démo Compose démarre, le test de bon fonctionnement réussit et le rapport d’évaluation est écrit. Mais beaucoup d’information reste dans la tête de Sam et sur son portable. Omar veut montrer le projet à un gestionnaire qui recrute la semaine prochaine. Amira va d’abord l’exécuter sur son propre ordinateur. Ni l’un ni l’autre n’était là quand Sam a fait chaque choix.

Sam demande à Amira de lire le README avant de lancer quoi que ce soit. Elle trouve vite un vrai problème. Le tableau des paramètres disait ceci :

| `RETRIEVAL_MODE` | `hybrid_rerank` | `dense` (vectors only) or `hybrid_rerank` (vectors + keywords, fused, reread by a cross-encoder) |

L’équipe du cours a trouvé la même lacune en rédigeant cette leçon, avec un seul grep dans le README et le code :

Fenêtre de terminal
grep -n "RETRIEVAL_MODE" README.md .env.example compose.yaml doc_assistant/config.py
README.md:65:| `RETRIEVAL_MODE` | `hybrid_rerank` | `dense` (vectors only) or `hybrid_rerank` (vectors + keywords, fused, reread by a cross-encoder) |
.env.example:22:RETRIEVAL_MODE=hybrid
compose.yaml:64: RETRIEVAL_MODE: ${RETRIEVAL_MODE:-hybrid}
doc_assistant/config.py:92: retrieval_mode=get("RETRIEVAL_MODE", s.retrieval_mode),

La valeur par défaut dans config.py est aussi hybrid. Le README décrivait un ancien plan. Au module 5, Sam a mesuré le modèle de reclassement (reranker) et ne l’a pas gardé. Il était plus lent, sans être meilleur. Personne n’a mis le tableau à jour. Un réviseur qui le lirait croirait qu’un cross-encoder (encodeur croisé) relit chaque recherche. Il s’attendrait à environ 0,4 s de plus par question, puis trouverait des chiffres différents dans le rapport.

Aucun test n’a échoué et aucune erreur n’est apparue. Un document peut être faux alors que le code est juste, et seul un lecteur le découvre. On dit que les documents divergent du code.

L’idée : rédiger la remise pour une personne inconnue

Section intitulée « L’idée : rédiger la remise pour une personne inconnue »

La remise du dépôt est le moment où le dépôt doit fonctionner sans son auteur. Sa partie principale est le README, le premier fichier que chaque lecteur ouvre. Un README de remise répond aux cinq questions de tout nouveau lecteur, dans cet ordre :

  1. Puis-je l’exécuter? Installation : quoi installer, avec les versions; les commandes, dans l’ordre; comment vérifier le fonctionnement; comment réinitialiser.
  2. Comment fonctionne-t-il? Architecture : une image des composants et les paramètres qui changent son comportement.
  3. D’où viennent les données? Provenance des données : qui a créé les documents, sous quelle licence, quels modèles sont utilisés et ce qui a été enregistré.
  4. Quelle est sa qualité? Évaluation : les principaux chiffres et un lien vers le rapport complet.
  5. Que ne fait-il pas? Limites : ce qui n’a pas été testé, les défaillances connues et ce qui est prévu, mais pas réalisé.

Ce sont les cinq types d’information de la fiche de recette. Chaque réponse renvoie à une preuve que le lecteur peut ouvrir ou exécuter.

Cinq questions du lecteur à gauche, chacune avec une flèche vers une section du README, puis vers sa preuve. Puis-je l'exécuter : démarrage rapide, installation, vérifications et réinitialisation; preuves pytest, 108 tests réussis, et scripts.isolation, 0 fuite. Comment fonctionne-t-il : architecture, une image et les paramètres; preuve, le dossier de conception. D'où viennent les données : provenance des données; preuves data/dataset.md, SHA256SUMS et evaluation/heldout.lock. Quelle est sa qualité : évaluation, les chiffres sur les données réservées; preuves docs/evaluation-report.md et scripts.evaluate. Que ne fait-il pas : limites et état; preuve docs/portfolio-checklist.md, travail terminé et prévu.
Un README de remise répond à cinq questions du lecteur. Chaque section se termine par une preuve que le lecteur peut ouvrir ou exécuter (en vert).
Description textuelle du diagramme

Le diagramme a trois colonnes. À gauche se trouvent cinq questions d’un nouveau lecteur. Chaque question a une flèche vers la section du README qui y répond, puis vers la preuve. « Puis-je l’exécuter? » mène au démarrage rapide, puis à deux commandes : pytest, qui affiche 108 tests réussis, et scripts.isolation, qui doit afficher 0 fuite. « Comment fonctionne-t-il? » mène à la section Architecture et au dossier de conception. « D’où viennent les données? » mène à Provenance des données : la fiche de données, les sommes de contrôle et le fichier de verrouillage des questions réservées. « Quelle est sa qualité? » mène à Évaluation et au rapport d’évaluation. « Que ne fait-il pas? » mène à Limites et état, puis à la liste de vérification du portfolio.

Pourquoi est-ce important pour un portfolio? Un gestionnaire qui recrute consacre quelques minutes à votre dépôt. Il n’exécutera pas tous les tests. Il lit le README, lance peut-être une commande et cherche une limite présentée honnêtement. Un README qui répond aux cinq questions, avec des preuves, montre la compétence nécessaire pour le poste.

Les limites et l’évaluation sont les sections les plus difficiles à rédiger, car chaque ligne est une affirmation. Prenez une affirmation sur le projet intégrateur guidé et écrivez-la de trois façons :

Version Texte Ce qu’un réviseur peut en faire
Sans preuve « Assistant multilocataire sécurisé, prêt pour la production. » Rien. Aucun test ne justifie « sécurisé » ou « prêt pour la production ». Le plan de preuves de Sam interdit les deux expressions.
Vague « Les locataires sont isolés. » Demander « comment le savez-vous? ». La réponse n’est pas dans le dépôt.
Avec preuve « Une boutique ne voit jamais les données de l’autre : python -m scripts.isolation vérifie la recherche, l’API et la base de données, et trouve 0 fuite (430 vérifications lors de l’exécution du rapport). » Exécuter la commande et voir 0 leaks (0 fuite) en quelques secondes.

La troisième version est plus longue, mais chaque partie peut être vérifiée. Elle nomme l’affirmation, la commande, le résultat et la taille du test. Elle dit aussi « boutique », plutôt que le mot « locataire » de l’équipe, car le lecteur n’en fait pas partie.

La même règle s’applique à une défaillance. « Certains cas limites pourraient être améliorés » est vague. « Chez Bramble Books, une question sur le crédit de compensation de Larkfield reçoit la limite de Bramble (question réservée B34) » est précis. Le lecteur apprend exactement quoi surveiller.

Le projet intégrateur guidé : le README de Sam, section par section

Section intitulée « Le projet intégrateur guidé : le README de Sam, section par section »

Ouvrez README.md dans votre copie de end-of-m06. Il contient environ 1 300 mots. Lisez-le en gardant les cinq questions en tête.

Ce qu’il fait, puis le démarrage rapide. Le premier paragraphe dit ce que fait le produit et pour qui, en deux phrases. Le deuxième indique son coût d’exécution : rien, car les réponses sont enregistrées et la recherche utilise le processeur. « Ce qu’il fait » présente le parcours utilisateur en quatre lignes. Le démarrage rapide commence par le nécessaire : Python 3.12 ou plus récent, Git, Docker et environ 5 Go d’espace disque. Puis viennent les commandes, chacune avec un court commentaire qui explique son rôle :

README.md (Quick start, part)
cp .env.example .env # then change POSTGRES_PASSWORD (and the two URLs) in .env
python -m idp init # the practice identity provider's keys; writes two secrets to .env
docker compose up -d --wait db # PostgreSQL with pgvector; --wait: until it is ready
python -m scripts.load_pack # the two shops, their people and their 51 documents (downloads the models once)

La section donne aussi les différences pour Windows, les cinq identités de connexion, trois vérifications au terminal et deux façons de réinitialiser. La réinitialisation compte : un réviseur qui abîme les données doit pouvoir recommencer avec une seule commande.

Architecture. Un paragraphe, un schéma textuel et un tableau des paramètres qui changent le comportement. La section ne répète pas le dossier de conception. Elle renvoie à docs/design-pack/architecture.md et à docs/design-pack/threat-and-cost.md pour les détails. La divergence se trouvait dans cette section. La ligne corrigée dit maintenant :

| `RETRIEVAL_MODE` | `hybrid` | `dense` (vectors only), `hybrid` (vectors + keywords, fused), `dense_rerank` or `hybrid_rerank` (then reread by a cross-encoder: measured, not better here, about 0.4 s slower) |

Le schéma textuel a aussi changé : il dit « récupération (vecteurs + mots-clés, fusionnés) », et non « reclassés ».

Provenance des données. Chaque document, boutique et personne est inventé pour le cours, sous licence CC0, et data/dataset.md est la fiche de données. La section nomme les deux modèles locaux et leurs licences, et précise que les réponses dans recordings/ viennent de chat-small. Elle dit que des personnes ont écrit les 103 questions, dont 41 ont été réservées avant tout ajustement. Un réviseur qui demande « le modèle a-t-il écrit son propre test? » trouve la réponse ici.

Évaluation. Un paragraphe avec les principaux chiffres, puis un lien vers le rapport complet. Sam a ajouté ce paragraphe pendant la remise pour présenter la qualité du projet sans ouvrir un deuxième fichier :

README.md (Evaluation, first paragraph)
On the 41 held-out questions (real answers of chat-small, recorded): 36 correct, every citation valid,
5 of the 6 questions that need a "no answer" refused, 0 of 2 hidden instructions followed, about 1.3 s and
US$0.00017 per question. The isolation checks found 0 leaks (430 probes in the report's run). The one
improvement, keyword search next to the vectors, gained on the tuning questions but not on the held-out
ones: it is kept because it is no worse at the same cost, not because it is better.

Regardez la dernière phrase. Elle reprend le résultat honnête de Documenter les compromis, sans l’embellir en parlant d’« amélioration ».

Limites et état. La section présente six limites précises, une par ligne. Les voici : une seule plateforme testée, des documents synthétiques, des réponses enregistrées seulement pour les questions du cours, le fournisseur d’exercice sans mots de passe, les étapes infonuagiques non exécutées et des corrigés stricts. Sam a ajouté une septième ligne avec les défaillances connues, B34 et Q37, identifiées par leurs identifiants de question. Une courte section État sépare ensuite le travail terminé du travail prévu. Elle renvoie à la liste de vérification du portfolio et au scénario de démo.

La divergence revient chaque fois que le code change. Après chaque changement, vérifiez donc de nouveau les paramètres et les commandes. Pour les paramètres, utilisez grep sur le README avec .env.example, compose.yaml et config.py, comme ci-dessus. Après la correction :

Fenêtre de terminal
grep -n "RETRIEVAL_MODE" README.md .env.example compose.yaml
README.md:65:| `RETRIEVAL_MODE` | `hybrid` | `dense` (vectors only), `hybrid` (vectors + keywords, fused), `dense_rerank` or `hybrid_rerank` (then reread by a cross-encoder: measured, not better here, about 0.4 s slower) |
.env.example:22:RETRIEVAL_MODE=hybrid
compose.yaml:64: RETRIEVAL_MODE: ${RETRIEVAL_MODE:-hybrid}

Pour les commandes, il n’y a qu’une vraie vérification : les exécuter, dans l’ordre, dans un environnement propre. C’est l’exercice guidé ci-dessous.

La liste de vérification du portfolio : chaque affirmation et sa preuve

Section intitulée « La liste de vérification du portfolio : chaque affirmation et sa preuve »

Le README fait des affirmations. La démo de la prochaine leçon en fait d’autres, tout comme votre CV. La liste de vérification du portfolio, docs/portfolio-checklist.md, les rassemble toutes dans un tableau. Chaque ligne contient l’affirmation, la preuve et le type de preuve. Sam utilise trois types :

  • En direct : le réviseur l’exécute sur son ordinateur et voit le résultat. Le test de bon fonctionnement, les vérifications d’isolation et les cas de défaillance sont en direct.
  • Enregistrée : une vraie exécution conservée dans le dépôt, que le réviseur peut lire, mais pas répéter exactement. Les réponses de chat-small aux questions réservées sont enregistrées. scripts.evaluate les rejoue, mais aucun modèle ne répond de nouveau.
  • Dans l’historique : un fait que Git prouve. Les données réservées ont été verrouillées dans un commit (enregistrement des modifications) avant qu’une réponse existe.
Sept affirmations à gauche, chacune avec une flèche vers sa preuve dans l'un des trois groupes. En direct, le réviseur exécute, en vert : démarrage rapide et scripts/smoke.py, 7 vérifications sur 7 réussies, pour « un nouvel utilisateur téléverse un document et obtient une réponse avec une citation »; scripts.isolation, 0 fuite, pour « une boutique ne voit jamais les données de l'autre »; scripts.failure_cases, 404, 415, 413, échec, 504, pour « il gère les mauvais fichiers, un modèle lent et la suppression ». Enregistrée, une vraie exécution conservée, en bleu : le rapport d'évaluation, 5 refus sur 6, B34 nommé, pour « il indique qu'il n'a pas de réponse au lieu de deviner »; référence de base et candidat, deux passes chacun, pour « un changement a été testé avec des preuves »; nombres de jetons multipliés par les tarifs, pour « environ 0,00017 $ US par question ». Dans l'historique, en orange : heldout.lock enregistré dans un commit avant toute réponse, pour « les questions réservées ont été mises de côté avant l'ajustement ».
La liste de vérification du portfolio de Sam en image : chaque affirmation renvoie à une preuve en direct (vert), enregistrée (bleu) ou dans l'historique Git (orange).
Description textuelle du diagramme

À gauche se trouvent sept affirmations de Sam. Trois renvoient à des preuves en direct, en vert, que le réviseur exécute : le démarrage rapide avec le test de bon fonctionnement, qui affiche 7 vérifications sur 7 réussies; les vérifications d’isolation, avec 0 fuite; et les cas de défaillance, avec les états 404, 415 et 413, un téléversement échoué et un 504. Trois affirmations renvoient à des preuves enregistrées, en bleu : le rapport d’évaluation avec 5 refus sur 6 et B34 nommé; la référence de base et le candidat, deux passes chacun; et le coût, calculé en multipliant les nombres de jetons par les tarifs. La dernière affirmation dit que les questions réservées ont été mises de côté avant l’ajustement. Elle renvoie à l’historique Git, en orange : le fichier de verrouillage, enregistré dans un commit avant toute réponse.

Le type compte pour le réviseur. Une affirmation vérifiée en direct est la plus solide, car il voit le résultat se produire. Une affirmation enregistrée n’est honnête que si elle est étiquetée ainsi. Supposons que votre démo rejoue des réponses enregistrées et laisse croire au public qu’un modèle vient de répondre. Vous faites alors une affirmation fausse. Le tableau de Sam a une colonne pour le type. Le modèle de document en ajoute une : la date de votre dernière vérification de l’affirmation.

La liste de vérification de Sam se termine par deux listes : terminé et prévu (non réalisé). Un déploiement infonuagique se trouve dans la deuxième liste. Ses étapes sont écrites dans docs/deployment.md, mais personne ne les a exécutées. Il ne peut donc pas passer à la première liste.

La seule façon de trouver une étape manquante est de suivre le README comme une personne qui découvre le projet. Utilisez un nouveau dossier, un nouvel environnement et rien de l’historique de votre interpréteur de commandes. Faites-le d’abord pour le projet intégrateur guidé. Les sorties ci-dessous viennent de l’exécution de l’équipe du cours sur une nouvelle copie de end-of-m06.

  1. Copiez l’instantané dans un nouveau dossier, comme si vous le cloniez pour la première fois :

    Fenêtre de terminal
    cp -R ../nextia-learning-labs/C27/snapshots/end-of-m06 ~/handoff-check
    cd ~/handoff-check
  2. Ouvrez README.md. Suivez son démarrage rapide, une ligne à la fois. N’utilisez aucune commande absente du README.

  3. Notez chaque endroit où vous hésitez. Chacun correspond à une ligne manquante dans le README.

  4. Si un autre PostgreSQL utilise déjà le port 5432, ajoutez DB_PORT=5433 à .env. Utilisez ensuite 5433 dans les deux URL. L’équipe du cours a utilisé un autre port pour cette raison.

  5. Après python -m idp init, lisez la sortie. Elle se termine par ces deux lignes :

    Wrote a new SESSION_SECRET (the API signs its session cookies with it).
    The provider keeps only the client secret's SHA-256. Never commit .env or .idp/.
  6. Après python -m scripts.load_pack, lisez les dernières lignes :

    Indexed 51 documents in 8.4 s (failed 0).
    bramble: 15 documents, 60 passages, 0 failed
    larkfield: 36 documents, 185 passages, 0 failed

    La première exécution sur un nouvel ordinateur télécharge aussi les deux modèles, environ 1 Go, et prend plus de temps.

  7. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest
    ........................................................................ [ 66%]
    .................................... [100%]
    108 passed in 38.29s
  8. Posez la question du README :

    Fenêtre de terminal
    python -m scripts.ask "How long is a gift card valid?" --tenant bramble

    La réponse et sa dernière ligne :

    Answer (answerable): A gift card is valid for 3 years from the date of purchase.
    - A gift card is valid for 3 years from the date of purchase. [Gift cards, How long they last, v1]
    ...
    recorded chat-small | 4117 ms | tokens 768 in, 63 out | US$0.000108 | trace b399659f3e72321038cfa8eaa85e9189

    La première question prend environ 4 s, car elle charge le modèle de plongement (embedding).

  9. Exécutez les vérifications d’isolation :

    Fenêtre de terminal
    python -m scripts.isolation
    Search: 103 questions asked in the other shop -> 0 passages of the first shop
    Access: 11 staff-only questions asked by read-only members -> 0 staff-only passages
    API: 294 requests with the other shop's IDs -> statuses {404: 294}, 0 leaks
    Database: 8 unfiltered queries under row-level security -> 0 rows of the other shop
    Isolation checks: 416 probes, 0 leaks.

    Le nombre de requêtes API augmente avec les réponses stockées dans la base de données. Votre total peut donc différer. Le nombre de fuites doit être 0.

  10. Faites du dossier un dépôt Git, puis demandez à Git quels fichiers il ignore :

    Fenêtre de terminal
    git init -q && git add -A
    git check-ignore -v .env .idp
    .gitignore:2:.env .env
    .gitignore:3:.idp/ .idp

    Si Git n’affiche rien pour .env, arrêtez. Vos secrets iraient dans le prochain commit.

  11. Cherchez des paramètres secrets dans les fichiers que Git enregistrera dans le commit :

    Fenêtre de terminal
    git grep -nE "^(LLM_API_KEY|SESSION_SECRET|OIDC_CLIENT_SECRET|POSTGRES_PASSWORD)="
    .env.example:5:POSTGRES_PASSWORD=change-me-on-your-computer
    .env.example:17:LLM_API_KEY=

    Seul le fichier d’exemple correspond, avec une valeur de remplacement et une clé vide.

  12. Arrêtez la base de données et supprimez ses données avec docker compose down --volumes. Supprimez ensuite le dossier de test.

L’exécution de l’équipe du cours a réussi chaque étape. Dans le parcours avec votre propre idée, les commandes changent, mais le test reste le même.

Rédigez maintenant la remise de votre propre produit. Si vous suivez le parcours avec votre propre idée, les cinq questions restent les mêmes; seules les réponses changent.

  1. Rédigez le README avec les cinq sections : Démarrage rapide (versions, procédure de réinitialisation et trois vérifications), Architecture (une image et les paramètres), Provenance des données, Évaluation (résultats principaux et lien), et Limites avec une section État. Partez du README de Sam et remplacez chaque fait par le vôtre.
  2. Comparez-le au code. Cherchez chaque paramètre avec grep dans le README, .env.example et votre fichier de paramètres. S’ils diffèrent, corrigez le README, ou le code si le README décrit votre intention.
  3. Remplissez la liste de vérification du portfolio. Copiez docs/templates/portfolio-checklist.md vers docs/portfolio-checklist.md. Rédigez une ligne pour chaque affirmation de votre README, de votre démo et de votre CV. Indiquez si chaque preuve est en direct, enregistrée ou dans l’historique, avec la date de votre dernière vérification.
  4. Faites le test avec une personne qui ne connaît pas le projet. Clonez votre dépôt depuis votre hébergeur Git dans un nouveau dossier, puis suivez le README à la lettre. Mieux encore, demandez à un ami de le faire pendant que vous observez sans rien dire.
  5. Conservez les preuves : les notes de cette personne (ses hésitations et vos modifications), la sortie des trois vérifications et le commit (modification enregistrée) qui a corrigé le README.

Liste de vérification

  • Une personne qui ne connaît pas le projet a suivi le démarrage rapide dans un dossier neuf, et chaque vérification a affiché ce qu’indique le README.
  • Le README précise les versions, une procédure de réinitialisation et les systèmes d’exploitation que vous avez testés.
  • Chaque paramètre du README correspond à la valeur par défaut dans le code.
  • La provenance des données précise qui a créé les documents, sous quelle licence, et quels modèles et enregistrements vous utilisez.
  • Chaque affirmation du README a une ligne dans la liste de vérification du portfolio, avec une preuve en direct, enregistrée ou dans l’historique.
  • Les limites précisent au moins une défaillance connue par sa question ou son cas, et séparent le travail terminé du travail prévu.
  • git check-ignore indique .env et tous les autres fichiers contenant un secret, et le dépôt ne contient aucun document privé.

Erreur courante

Le README décrit le projet du mois dernier

Symptôme : un paramètre, une commande ou un nombre du README ne correspond pas à ce que fait le code. Le README de Sam indiquait hybrid_rerank; la valeur par défaut du code était hybrid.

Cause : le README a été rédigé une fois, puis n’a pas été mis à jour après un changement de décision. Les tests vérifient le code, pas le texte.

Solution : après chaque décision, cherchez le paramètre avec grep dans le README, .env.example, compose.yaml et le fichier de paramètres. Citez les nombres du rapport, pas ceux dont vous vous souvenez. Refaites le test avec une personne qui ne connaît pas le projet avant de partager le lien.

Conséquence dans le travail en IA : un réviseur qui trouve une ligne erronée cesse de faire confiance aux autres. Dans une équipe, la personne suivante modifie le mauvais paramètre et mesure le mauvais système.

Erreur courante

Une étape qui existe seulement dans votre terminal

Symptôme : le test avec une personne qui ne connaît pas le projet bloque à une étape qui fonctionne sur votre portable. Par exemple :

error while interpolating services.db.environment.POSTGRES_PASSWORD: required variable POSTGRES_PASSWORD is missing a value: Set POSTGRES_PASSWORD in .env

Cause : vous avez fait une action à la main, il y a plusieurs semaines : créer .env, exporter une variable, télécharger un modèle ou démarrer une base de données. Le README n’en parle jamais, car vous avez oublié cette action. Ici, la personne a sauté cp .env.example .env, et Compose a refusé de démarrer une base de données sans mot de passe.

Solution : ajoutez l’étape manquante au README, là où la personne en a besoin, puis refaites le test dans un nouveau dossier. Recommencez toujours au début, jamais au milieu.

Erreur courante

Des documents privés dans un dépôt public

Symptôme : dans le parcours avec votre propre idée, le dépôt contient de vrais documents de votre employeur ou d’une autre entreprise réelle, ou des enregistrements qui les citent.

Cause : ces documents étaient les données les plus faciles à trouver, et le dépôt est devenu public pour le portfolio.

Solution : retirez-les du dépôt et de son historique. Utilisez des documents synthétiques ou sous licence ouverte, accompagnés d’une fiche de données, comme dans Ensemble de données synthétiques. Les enregistrements contiennent les passages que le modèle a vus; faites donc de nouveaux enregistrements. Demandez l’autorisation du propriétaire avant de publier quoi que ce soit qui ne vous appartient pas.

Vérifiez votre compréhension

Nommez les cinq questions auxquelles répond un README de remise. Pour le projet intégrateur présenté en exemple, donnez une preuve pour chacune.

Afficher la réponse

Puis-je l’exécuter : le démarrage rapide, vérifié par python -m pytest (108 tests réussis) et python -m scripts.isolation (0 fuite). Comment fonctionne-t-il : la section Architecture et le dossier de conception dans docs/design-pack/. D’où viennent les données : data/dataset.md (synthétiques, CC0), SHA256SUMS et evaluation/heldout.lock. Quelle est sa qualité : le rapport d’évaluation et python -m scripts.evaluate --set heldout (36 réponses correctes sur 41, réponses enregistrées). Que ne fait-il pas : les sections Limites et État et docs/portfolio-checklist.md, qui nomment B34 et indiquent que le déploiement dans le nuage est prévu, pas terminé.

Vérifiez votre compréhension

Prédisez : le README de Sam indiquait que le mode de récupération par défaut était hybrid_rerank, et tous les tests réussissaient. Pourquoi aucun test ne l'a-t-il détecté, et que conclurait probablement un réviseur?

Afficher la réponse

Les tests vérifient ce que fait le code, et le code était correct : sa valeur par défaut était hybrid. Rien ne vérifie le texte du README. Un réviseur croirait qu’un cross-encoder (encodeur croisé) relit chaque recherche et s’attendrait à environ 0,4 s de plus par question. Il trouverait ensuite des nombres incompatibles dans le rapport et cesserait de faire confiance au README. Les vérifications consistent à chercher le paramètre avec grep dans le README, .env.example, compose.yaml et config.py, puis à faire le test avec une personne qui ne connaît pas le projet.

Vérifiez votre compréhension

Classez les preuves de ces trois affirmations comme étant en direct, enregistrées ou dans l'historique, et expliquez pourquoi : (a) 36 réponses correctes sur 41 questions réservées; (b) 0 fuite entre les deux boutiques; (c) les données réservées ont été mises de côté avant tout réglage.

Afficher la réponse

(a) Enregistrées : les réponses sont de vraies réponses de chat-small, conservées dans recordings/. scripts.evaluate les rejoue, mais aucun modèle ne répond de nouveau. (b) En direct : le réviseur exécute python -m scripts.isolation sur son ordinateur et voit 0 leaks (0 fuite). (c) Dans l’historique : evaluation/heldout.lock a fait l’objet d’un commit avant toute génération de réponse, et Git montre l’ordre des commits.

Récapitulatif

  • Une remise du dépôt permet au projet de fonctionner sans son auteur. Le README répond à cinq questions, dans l’ordre : puis-je l’exécuter, comment fonctionne-t-il, d’où viennent les données, quelle est sa qualité, et que ne fait-il pas.
  • Les documents s’écartent du code, et aucun test n’échoue. Le README de Sam indiquait hybrid_rerank; le code indiquait hybrid. Vérifiez les paramètres avec grep, et les commandes avec le test dans un dossier neuf, effectué par une personne qui ne connaît pas le projet.
  • Accompagnez chaque affirmation de sa preuve : la commande, le résultat et la taille du test. N’écrivez jamais « sécurisé » ou « prêt pour la production ».
  • La liste de vérification du portfolio présente chaque affirmation et sa preuve, en direct, enregistrée ou dans l’historique. Elle sépare le travail terminé du travail prévu.

Ensuite, vous transformerez ces mêmes preuves en une démo de cinq minutes, avec un cas de défaillance et un compromis.

Leçon suivante : Le récit de la démo