Aller au contenu
English

Projet intégrateur sur une collection publique de documents

  • Étude de cas 1
  • 240 min
  • Facultative · 1 étude de cas requise pour le certificat

Où nous en sommes

Cette étude de cas applique toute la méthode du cours à une vraie collection publique : les guides du GOV.UK Service Manual sur la livraison agile. Vous délimitez le produit, mettez de côté les questions réservées avant toute réponse, comparez une référence de base de façon équitable et rédigez le README d'une pièce de portfolio.

Ce que vous saurez faire

Appliquez la méthode du projet intégrateur à une vraie collection : les 20 guides sur la livraison agile du GOV.UK Service Manual. Ils sont sous licence ouverte. Limitez la portée à un utilisateur et une décision, et réservez les questions avant toute réponse. Comparez équitablement une référence de base à trois variantes, et exécutez les tests sur les données réservées une seule fois. Ensuite, montrez honnêtement un échec et rédigez le README qui fera du projet une pièce de votre portfolio.

Étude de casPièce de portfolio

Durée
Environ 4 h
S’exécute dans
VS Code, Python 3.12+, Docker
Compétences utilisées
  • Portée limitée à un utilisateur
  • Licence et fiche de données
  • Un instantané avec des sommes de contrôle
  • Les questions réservées d'abord
  • Une règle écrite avant de mesurer
  • Comparaison équitable
  • Analyse honnête des échecs
  • README pour le portfolio

Décompressez le projet de départ, ouvrez le dossier dans VS Code et suivez les étapes ci-dessous. Elles commencent par un nouvel environnement virtuel.

Le projet de départ est le doc-assistant terminé du cours, adapté à une collection publique. Il contient les fichiers de la collection, 60 questions et les réponses d’un vrai modèle, enregistrées par l’équipe du cours. Vous n’avez besoin ni de clé ni d’argent. Le projet terminé présente le résultat, pour les moments où vous êtes bloqué. Le code est sous licence MIT. Les guides sont protégés par le droit d’auteur de la Couronne, sous l’Open Government Licence.

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

Ce que vous devez savoir

Cette étude de cas reprend tout le cours avec de nouveaux documents. Elle utilise surtout ces leçons :

La recherche hybride et le modèle de reclassement (reranker) viennent de Recherche lexicale, dense et hybride et Reclassement et reformulation des requêtes dans RAG : créer une IA qui utilise vos données.

Ce qu’il vous faut sur votre ordinateur

  • Python 3.12 ou une version plus récente, Git, VS Code, curl et Docker Desktop.
  • Environ 5 Go d’espace disque libre : les paquets (environ 1 Go, avec PyTorch), le modèle de plongement et PostgreSQL.
  • Une connexion Internet pour l’installation et une vérification facultative auprès de GOV.UK.

Testé sur macOS (Apple M4, 16 Go, Docker Desktop, PostgreSQL 18.6, Python 3.12.13). Les commandes Windows sont fournies, mais n’ont pas été testées. Tous les temps de cette étude de cas proviennent de l’ordinateur de l’auteur, qui exécutait aussi d’autres tâches. Vos temps seront différents.

Ruth est responsable de la livraison dans une petite équipe numérique d’un organisme public. Chaque mois, de nouvelles personnes arrivent : spécialistes de la recherche utilisateur, développeurs, gestionnaire de produit. La plupart découvrent le travail au gouvernement. Elles posent toutes les mêmes questions : « Combien de temps devrait durer une phase de découverte? », « Quand faut-il réserver l’évaluation? », « Qu’est-ce qu’une séance de présentation? »

Les réponses se trouvent dans le GOV.UK Service Manual. Son sujet Agile delivery compte 20 guides, de Core principles of agile à Retiring your service. Aujourd’hui, Ruth donne une liste de lecture aux nouvelles recrues. Elles ne lisent pas tout et confondent les guides. Le mois dernier, une recrue a dit à l’équipe qu’une phase alpha dure « 4 à 8 semaines ». C’est la durée du guide sur la découverte; le guide sur la phase alpha indique 6 à 8 semaines.

L’équipe et ses membres sont inventés pour cette étude de cas. Les guides sont réels.

L’objectif. Ruth doit prendre une seule décision : les nouvelles recrues devraient-elles commencer par un assistant plutôt que par la liste de lecture? Elle dit oui seulement avec des preuves. L’assistant répond à partir des 20 guides et cite un guide et une section pour chaque affirmation. Quand les guides ne répondent pas, il le dit. Ses résultats sur les questions réservées doivent respecter les seuils que vous écrivez avant toute réponse.

Un flux. La GOV.UK Content API, en pointillés parce qu'elle peut changer à tout moment, mène à data/snapshot/ : 22 fichiers JSON et SHA256SUMS, représentés comme verrouillés. collection prepare les transforme en 20 guides Markdown avec 197 sections. Ils entrent dans doc-assistant : une équipe, westbrook, la recherche hybride et la requête guide_v1. Séparément, questions.jsonl et ses 60 questions passent à holdout reserve avec la graine 27. Cette commande écrit heldout.jsonl, avec 25 questions verrouillées et enregistrées dans un commit avant toute réponse, et dev.jsonl, avec 35 questions de réglage. Les questions de réglage et l'assistant se rejoignent dans la comparaison de la référence de base et de 3 variantes. Une seule mesure les départage : les réponses correctes. La version choisie et les questions réservées verrouillées se rejoignent dans une seule exécution des tests, avec deux passages. Cela mène au rapport, au README et à la décision de Ruth.
L'étude de cas en une image. Les deux boîtes verrouillées sont fixées avant toute réponse : les documents et les questions réservées.
Description textuelle du diagramme

Lisez de gauche à droite. Les guides proviennent de GOV.UK, récupérés une seule fois sous forme d’instantané. Les 60 questions se répartissent en 25 questions réservées verrouillées et 35 questions de réglage. Vous comparez les versions uniquement sur les questions de réglage. La version choisie est testée une seule fois sur les questions réservées.

Partie Ce que vous faites Preuves à conserver
1 Portée : un utilisateur, une décision, les exclusions; les seuils et la règle pour un changement docs/project-brief.md, docs/acceptance-criteria.md
2 La collection : licence, instantané, conversion, fiche de données data/dataset.md, la sortie de datapack
3 Réserver les questions de test evaluation/heldout.lock, un commit (enregistrement des changements)
4 La référence de base sur les questions de réglage les échecs, lus un par un
5 Trois variantes, une mesure, une règle un tableau comparatif
6 Les tests sur les questions réservées, une seule fois reports/heldout-baseline.json, docs/evaluation-report.md
7 Une nouvelle entrée, de bout en bout un nouveau guide, téléversé, indexé et cité
8 Le README la pièce du portfolio

Les étapes utilisent VS Code et son terminal. Toutes les commandes s’exécutent dans le dossier du projet.

  1. Téléchargez le projet de départ depuis l’encadré en haut de cette page. Décompressez-le dans votre dossier de projets, par exemple ~/projects. Vous obtenez le dossier public-collection-capstone.

  2. Dans VS Code, choisissez File > Open Folder (fichier, ouvrir un dossier), puis ouvrez public-collection-capstone. Ouvrez ensuite un terminal : Terminal > New Terminal (terminal, nouveau terminal).

  3. Créez et activez un environnement virtuel, puis installez les paquets :

    Fenêtre de terminal
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install -r requirements.txt

    Sur Linux sans processeur graphique, installez d’abord la version pour processeur central de PyTorch, comme l’indique le début de requirements.txt.

  4. Copiez le fichier de paramètres. Changez ensuite son mot de passe : POSTGRES_PASSWORD, et le même mot de passe dans les deux URL.

    Fenêtre de terminal
    cp .env.example .env
  5. Créez les clés du fournisseur d’identité d’exercice, puis démarrez PostgreSQL :

    Fenêtre de terminal
    python -m idp init
    docker compose up -d --wait db

    idp init vient en premier : cette commande écrit deux secrets dans .env, sans lesquels Compose refuse de démarrer.

  6. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest
    .................................................................ssss... [ 64%]
    ....................................... [100%]
    107 passed, 4 skipped in 38.71s

Ce que cela nous indique. Les tests du cours réussissent aussi sur ce projet. Ils utilisent l’ensemble synthétique de deux boutiques du cours, qui se trouve maintenant dans tests/fixtures/pack/. Pourquoi le garder? Tester le code d’accès et d’isolation nécessite deux locataires et des documents réservés au personnel. Une collection publique n’a ni l’un ni l’autre. Les quatre tests ignorés vérifient les données réservées, que vous préparez à la partie 3.

Commencez par les cinq lignes de Problème et public, rédigées avec Ruth. Le projet terminé les contient dans docs/project-brief.md :

  • Utilisateur : Ruth et les nouvelles recrues de son équipe.
  • Décision : la trousse d’accueil dirige-t-elle d’abord les nouvelles recrues vers l’assistant, plutôt que vers la liste de lecture?
  • Documents : les 20 guides du sujet Agile delivery, dans une seule copie fixe.
  • Réussite : une réponse courte en quelques secondes, avec un guide et une section pour chaque affirmation, ou « les guides ne le disent pas ».
  • Exclusions : aucun autre sujet du manuel, aucun conseil, aucune copie en direct de GOV.UK, et un seul locataire.

Pourquoi un seul locataire suffit-il? Le projet intégrateur guidé a deux boutiques, car les documents de chacune sont privés. Une fuite entre elles serait le pire échec. Ici, tous les documents sont publics et une seule équipe les utilise. Un deuxième locataire ne protégerait rien. Le code d’isolation reste dans le produit, et ses tests utilisent toujours l’ensemble synthétique. Dans le README, vous ne revendiquez pas l’isolation pour cette collection : vous dites qu’elle ne s’applique pas.

Ensuite viennent les critères d’acceptation, avant toute réponse. Ce sont les seuils du projet intégrateur guidé, pour permettre de comparer les deux projets :

ID Mesure sur les questions réservées Seuil
Q1 réponses correctes aux questions auxquelles les guides répondent au moins 75 %
Q2 s’abstient quand les guides ne répondent pas 100 %
Q3 validité des citations 100 %
Q4 suit une instruction cachée non mesuré : les guides n’en contiennent aucune
Q5 temps médian, de la question à la réponse moins de 5 s
C1 coût du modèle par question moins de 0,001 $ US

Une autre ligne a sa place ici, et elle est nouvelle : la règle pour choisir un changement. Vous allez essayer des variantes sur les questions de réglage. Écrivez maintenant ce que « meilleur » signifie, pour qu’une exécution chanceuse ne décide pas à votre place :

Sur les 35 questions de réglage, au premier passage en direct, une variante devient candidate seulement avec au moins 2 réponses correctes de plus que la référence de base. Elle ne doit pas échouer sur une question sans réponse que la référence de base avait traitée correctement. Elle ne doit pas non plus ajouter plus de 0,5 s au temps médian.

Pourquoi 2 et non 1? Dans Exécuter les tests sur des données réservées, deux exécutions identiques en direct différaient d’une question. Une règle qui accepte une question accepte du bruit.

Avant de lire un seul guide, vérifiez que vous pouvez le copier et publier votre copie. L’auteur a comparé deux collections :

GOV.UK Service Manual, Agile delivery Open Source Guides (GitHub)
Licence Open Government Licence v3.0 CC BY 4.0
Taille 20 guides, environ 19 100 mots 14 articles, environ 40 000 mots
Faits vérifiables nombreux : réunions quotidiennes de 15 minutes, phases alpha de 6 à 8 semaines, adresses courriel peu : surtout des conseils
Une vraie difficulté quatre guides de phase avec les mêmes titres; une contradiction articles qui se recoupent

Les deux licences permettent une copie avec attribution. Les guides GOV.UK ont été retenus, car une réponse à leur sujet peut être notée correcte ou incorrecte. Un corrigé comme \b15\b|fifteen peut vérifier « Combien de temps devrait durer notre réunion quotidienne? ». Aucun corrigé ne peut vérifier « Soyez aimable avec les nouveaux contributeurs ».

Imaginez un tableau d’affichage dans un bureau. N’importe qui peut le modifier à tout moment. Pour le citer dans un rapport, vous le photocopiez et inscrivez la date sur la copie. Votre rapport porte alors sur la copie, et tout le monde peut le vérifier.

GOV.UK est ce tableau d’affichage : six des 20 guides ont été mis à jour rien qu’en 2026. Imaginez maintenant que vous téléchargez les guides un mois après l’auteur. Un guide a un nouveau paragraphe, donc ses passages se déplacent. Leurs identifiants changent, les réponses enregistrées ne correspondent plus, et un corrigé réservé peut ne plus être vrai. Vous et l’auteur avez mesuré deux collections différentes sans le savoir.

La solution est un instantané : les fichiers exacts, récupérés une fois, conservés avec une somme de contrôle (SHA-256) pour chacun. Tout ce qui suit dépend de cet instantané : les documents, les passages, les enregistrements et le verrou des données réservées. Un deuxième script compare l’instantané au GOV.UK d’aujourd’hui, pour que vous sachiez quand il a vieilli. Vous pouvez conserver une copie seulement si la licence le permet, et l’Open Government Licence le permet.

GOV.UK aujourd'hui, en pointillés parce qu'un guide peut changer n'importe quel jour, mène à l'instantané par une flèche portant l'étiquette « récupérer, une fois ». L'instantané contient les fichiers exacts et le SHA-256 de chacun, représentés comme verrouillés. Il donne le même texte sur chaque ordinateur, puis les mêmes passages et identifiants de passage, puis deux résultats : les réponses enregistrées correspondent toujours et les corrigés réservés restent vrais. Une flèche pointillée de GOV.UK vers l'instantané porte l'étiquette « collection check : qu'est-ce qui a changé depuis? ».
Un instantané fixe tout ce qui dépend du texte. La vérification vous indique quand la source a évolué.
Description textuelle du diagramme

À gauche se trouve GOV.UK, qui peut changer n’importe quel jour. Une seule récupération crée l’instantané : les fichiers exacts avec un SHA-256 pour chacun. À partir de l’instantané, chaque ordinateur obtient le même texte, donc les mêmes passages et identifiants de passage. Cela garde deux choses vraies : les réponses enregistrées correspondent, et les corrigés réservés décrivent toujours le texte. Une flèche pointillée vers GOV.UK représente la vérification, qui énumère les changements depuis la récupération.

Quand avez-vous besoin d’un instantané? Quand la source change sans numéro de version, et que votre évaluation ou vos enregistrements dépendent des mots exacts. Il prend de l’espace disque, et la copie vieillit. Indiquez son âge dans la fiche de données. Actualisez-le volontairement, avec de nouveaux enregistrements et une nouvelle exécution des tests sur les données réservées.

Le projet de départ contient l’instantané dans data/snapshot/. Il contient la page du sujet et ses 20 guides, tels que la GOV.UK Content API les a renvoyés. Il contient aussi un guide supplémentaire pour la partie 7. scripts/collection.py transforme chaque guide en document Markdown avec les métadonnées que l’assistant lit :

Fenêtre de terminal
python -m scripts.collection prepare
python -m scripts.datapack
Snapshot: 22 of 22 files match data/snapshot/SHA256SUMS
Wrote 20 documents to data/westbrook/documents/ (19,135 words), last updated 2016-05-23 to 2026-05-22.
Wrote data/westbrook/inventory.csv and data/SHA256SUMS (24 files, SHA-256 of the list 1a5f6f7cd1a5...).
Checksums: 24 of 24 files match SHA256SUMS
westbrook: 20 documents, 197 sections, formats {'md': 20}, languages {'en': 20}
staff-only 0; with more than one version: none; with an end date 0; supplier documents: none
Every document parses.

Ce que cela nous indique. Les 22 fichiers de l’instantané correspondent à leurs sommes de contrôle. Les 20 documents sont analysés correctement, avec 197 sections. Le SHA-256 de la liste des documents commence par 1a5f6f7cd1a5, comme celui de l’auteur. Votre collection est donc identique, octet par octet. Il n’y a aucun document réservé au personnel ni aucune deuxième version : une collection publique n’a ni l’un ni l’autre.

La conversion a révélé une surprise. Les guides utilisent trois niveaux de titres, et le lecteur du cours en reconnaît deux. Agile methods : an introduction contient deux sections « Scrum », sous deux sections parentes différentes. Deux citations auraient la même apparence. Le script nomme donc une section de troisième niveau en utilisant le nom de sa section parente :

data/westbrook/documents/agile-methodologies.md (part)
## Popular agile methods explained: Scrum
Scrum is the most commonly used agile method.

Vérifiez maintenant l’âge de l’instantané. Cette commande nécessite Internet :

Fenêtre de terminal
python -m scripts.collection check
20 of 20 guides are the same as the snapshot; 0 changed.

Écrivez le résultat dans la fiche de données. Celle du projet terminé, data/dataset.md, suit le modèle du cours. Elle indique la source, la licence, la phrase d’attribution, le contenu, les vraies difficultés, les questions et les limites. Sa phrase clé : « Rien n’a été ajouté artificiellement : ce sont les difficultés de la vraie collection. »

Une seule personne a rédigé les 60 questions de evaluation/questions.jsonl en lisant les guides. Aucun modèle ne les a écrites, n’y a répondu ni ne les a étiquetées. Chaque question nomme les sections qui y répondent. Il y a six types :

Type Nombre Exemple
avec réponse 24 « Combien de temps devrait durer notre réunion quotidienne? »
phase 12 « Combien de temps dure habituellement une phase alpha? » (les quatre guides de phase sont en concurrence)
reformulation 7 « Presque plus personne n’utilise notre ancien service en ligne. Devrait-on le maintenir en fonctionnement? »
définition 6 « Qu’est-ce qu’un obstacle bloquant? »
conflit 2 « Faut-il une approbation du contrôle des dépenses avant de commencer une phase de découverte? »
sans réponse 9 « Combien de points contient le Service Standard? » (un autre sujet du manuel)

Les questions de conflit sont réelles. How the discovery phase works dit encore « vérifiez si vous avez besoin d’une approbation du contrôle des dépenses ». Getting approval to spend money on a service, mis à jour en avril 2026, indique que ces contrôles ont été remplacés le 1er avril 2026. Le guide le plus récent s’applique.

Réservez maintenant les données de test, avant de voir une seule réponse. C’est l’étape de Planifier les preuves :

Fenêtre de terminal
python -m scripts.holdout reserve
Held out: 25 questions (westbrook 25). Kinds: answerable 10, conflict 1, definition 2, paraphrase 3, phase 5, unanswerable 4.
Tuning set: 35 questions (westbrook 35).
Wrote evaluation/heldout.jsonl, dev.jsonl and heldout.lock. Commit them now, before any tuning.

Enregistrez les trois fichiers dans un même commit, avec le reste du projet :

Fenêtre de terminal
git init
git add .
git commit -m "The collection, the questions and the held-out set, before any answer"

Ce que cela nous indique. La répartition est stratifiée : les données réservées contiennent donc chaque type de question. L’empreinte du verrou commence par 75f6adf284e4, comme celle de l’auteur : la répartition est reproductible. Les quatre tests ignorés s’exécutent maintenant et réussissent. À partir d’ici, les 25 questions réservées restent fermées jusqu’à la partie 6.

Chargez la collection dans PostgreSQL, comme documents d’une seule équipe :

Fenêtre de terminal
python -m scripts.load_pack
Identity: 1 tenants, 2 people, 2 memberships
westbrook: 20 documents uploaded, 0 already there
Indexing with intfloat/multilingual-e5-small@614241f ...
Indexed 20 documents in 9.7 s (failed 0).
westbrook: 20 documents, 225 passages, 0 failed

La référence de base utilise les paramètres finaux du cours : recherche hybride, les 5 premiers passages et la requête (prompt) guide_v1. Cette requête reprend answer_v2 du cours, en remplaçant les mots sur les boutiques par des mots sur les guides. Les règles n’ont pas changé. Vous l’avez écrite avant toute réponse. Elle fait donc partie de la configuration, pas du réglage.

Exécutez les 35 questions de réglage. Consultez ces réponses aussi souvent que vous le voulez :

Fenêtre de terminal
python -m scripts.evaluate --set dev --show-failures
hybrid, guide_v1, recorded: 35 questions | correct 0.971 | retrieval hit 0.967 | citations valid 1.000 | abstained when it should 1.0 | injection obeyed 0 of 0 | median 11 ms | US$0.000202 per question
answerable 14 correct 1.0 hit 1.0
conflict 1 correct 1.0 hit 1.0
definition 4 correct 1.0 hit 1.0
paraphrase 4 correct 0.75 hit 0.75
phase 7 correct 1.0 hit 1.0
unanswerable 5 correct 1.0 hit None
WRONG G49 (westbrook, paraphrase, hit False): The guides do not say whether you should keep running the service because hardly anyone uses it.

Ce que cela nous apprend. 34 réponses sur 35 sont correctes, chaque citation est valide et chaque question sans réponse est refusée. Le seul échec est G49, une reformulation : « Presque personne n’utilise encore notre ancien service en ligne. Devrait-on continuer à l’exploiter? » La réponse dit que les guides ne le précisent pas. Ils le précisent pourtant : How the live phase works indique de retirer un service devenu non rentable parce que trop peu d’utilisateurs en ont besoin. hit False indique que la recherche n’a pas trouvé cette section. Le modèle pouvait donc seulement refuser.

Le temps dans cette sortie ne représente pas la vitesse de l’assistant : les réponses sont enregistrées. Dans l’exécution en direct de l’auteur, une question prenait environ 1.6 s en médiane. L’appel au modèle prenait presque tout ce temps.

L’échec pointe vers la recherche. Les options sont donc des modes de recherche. Les trois existent dans le code du cours : dense (vecteurs seulement), dense_rerank et hybrid_rerank (un encodeur croisé relit 20 candidats). D’abord, la mesure gratuite : la recherche a-t-elle trouvé une section pertinente?

Fenêtre de terminal
python -m scripts.evaluate --set dev --retrieval-only --show-failures --config RETRIEVAL_MODE=dense

Exécutez-la quatre fois, avec dense, hybrid, dense_rerank et hybrid_rerank :

dense, guide_v1, recorded: retrieval hit 1.000 (30 of 30 questions with relevant passages), median search time 8.1 ms
hybrid, guide_v1, recorded: retrieval hit 0.967 (29 of 30 questions with relevant passages), median search time 9.3 ms
missed G49 (westbrook, paraphrase)
dense_rerank, guide_v1, recorded: retrieval hit 1.000 (30 of 30 questions with relevant passages), median search time 363.5 ms
hybrid_rerank, guide_v1, recorded: retrieval hit 1.000 (30 of 30 questions with relevant passages), median search time 362.0 ms

Ensuite, mesurez ce qu’utilise la règle : les réponses correctes. Exécutez l’évaluation complète avec chaque option, par exemple :

Fenêtre de terminal
python -m scripts.evaluate --set dev --show-failures --config RETRIEVAL_MODE=dense
  • Référence de base (hybride)
  • Options
Première passe de l'exécution en direct de l'auteur. Chaque option a corrigé la même question; la règle en exige deux.
Description textuelle du graphique

La référence de base, hybride, a obtenu 34 réponses correctes sur 35 à la première passe et 34 à la deuxième. La recherche dense, dense avec modèle de reclassement (reranker) et hybride avec modèle de reclassement ont chacune obtenu 35 sur 35. « p2 » désigne la deuxième passe et « +R » signifie avec le modèle de reclassement. L’axe commence à 30 pour rendre visible l’écart d’une question.

Version (données de réglage, passe 1 en direct) Réponses correctes Recherche ayant trouvé une section pertinente Temps de recherche médian
hybride (référence de base) 34 sur 35 29 sur 30 environ 9 ms
dense 35 sur 35 30 sur 30 environ 7 ms
dense_rerank 35 sur 35 30 sur 30 environ 340 ms
hybrid_rerank 35 sur 35 30 sur 30 environ 350 ms

Ce que cela nous apprend. Chaque option a trouvé la section de G49 et répondu à la question. Rien d’autre n’a changé. La recherche dense était même un peu plus rapide. Est-elle donc meilleure? Appliquez la règle écrite dans la partie 1. Elle exige 2 réponses correctes de plus, et chaque option en a 1. Aucun candidat : la référence de base reste.

Cela peut sembler incorrect : G49 a échoué aux deux passes de la référence de base. Ce n’est donc pas du bruit. Mais il s’agit d’une seule question. À 34 sur 35, les données de réglage ne permettent pas de démontrer un écart d’une réponse. Le compte rendu honnête : « La recherche dense a corrigé G49, une reformulation. Pas assez de preuves pour changer. Surveiller les reformulations. » Sans candidat, on exécute les données réservées une seule fois, pour la référence de base.

Partie 6 : une seule exécution sur les données réservées

Section intitulée « Partie 6 : une seule exécution sur les données réservées »
Fenêtre de terminal
python -m scripts.evaluate --set heldout --show-failures --out reports/heldout-baseline.json
hybrid, guide_v1, recorded: 25 questions | correct 0.880 | retrieval hit 0.905 | citations valid 1.000 | abstained when it should 1.0 | injection obeyed 0 of 0 | median 12 ms | US$0.000201 per question
answerable 10 correct 0.8 hit 0.9
conflict 1 correct 1.0 hit 1.0
definition 2 correct 1.0 hit 1.0
paraphrase 3 correct 1.0 hit 1.0
phase 5 correct 0.8 hit 0.8
unanswerable 4 correct 1.0 hit None
WRONG G01 (westbrook, answerable, hit False): The guides do not say how long a daily standup should last.
WRONG G13 (westbrook, answerable, hit True): Show work that’s in progress, not yet started and done. Also track progress against goals and KPIs, risks and issues, blockers, deadlines and dependen
WRONG G30 (westbrook, phase, hit False): The guides do not say whether members of the public can use your service during alpha.
Wrote reports/heldout-baseline.json

Comparez les résultats aux critères d’acceptation. Les deux passes en direct de l’auteur ont donné le même résultat. Le voici avec le temps et le coût en direct :

Mesure Seuil Passe 1 Passe 2 Respecté?
Réponses correctes aux questions ayant une réponse (Q1) au moins 75 % 18 sur 21 18 sur 21 oui
S’abstient quand les guides ne répondent pas (Q2) 100 % 4 sur 4 4 sur 4 oui
Validité des citations (Q3) 100 % 100 % 100 % oui
Temps médian, de la question à la réponse (Q5) moins de 5 s environ 1.3 s environ 1.7 s oui
Coût du modèle par question (C1) moins de 0,001 $ US 0,000201 $ US 0,000201 $ US oui

Chaque critère est respecté : 85,7 % des questions ayant une réponse sont correctes, contre un seuil de 75 %. Mais ne vous arrêtez pas au tableau des résultats. Lisez les trois réponses incorrectes, comme l’enseigne Examiner les catégories d’erreurs :

  • G13, le mur de l’équipe : le corrigé était trop strict. La réponse est correcte : « Montrez le travail en cours, pas encore commencé et terminé. » Mais le corrigé not started|upcoming ne reconnaît pas « not yet started » (pas encore commencé). Vous ne modifiez pas un corrigé réservé après une exécution. Le score reste à 22. Le rapport indique qu’une personne juge correctes 23 réponses sur 25.
  • G30, le public en alpha : la recherche a raté la section. Le début du guide sur l’alpha dit : « Les services alpha ne devraient pas être accessibles au public. » La recherche n’a pas fourni ce passage, et l’assistant a répondu : « Les guides ne le précisent pas. »
  • G01, la réunion debout : la recherche a raté la section. La prochaine section examine cet échec de près.

Un échec, en toute honnêteté : la réunion debout de 15 minutes

Section intitulée « Un échec, en toute honnêteté : la réunion debout de 15 minutes »

G01 est la question la plus facile de la banque : « Combien de temps devrait durer notre réunion debout quotidienne? » La réponse a sa propre section dans Agile tools and techniques. Elle dit : « limitez-la à 15 minutes ou moins ». Pourtant, l’assistant a répondu que les guides ne le précisent pas. Posez vous-même la question et examinez les passages :

Fenêtre de terminal
python -m scripts.ask "How long should our daily standup last?"
Ruth (owner) at Westbrook digital team asks: How long should our daily standup last?
Passages found: ca47f49114ab how-the-beta-phase-works v4, 9a823f56a408 how-the-discovery-phase-works v4, 01df8cd661a8 core-principles-agile v1, 2bbb0c5e9905 how-the-live-phase-works v4, 5b1eb08f23b8 retiring-your-service v2
Answer (not answerable): The guides do not say how long a daily standup should last.
recorded chat-small | 3300 ms | tokens 1265 in, 80 out | US$0.000167 | trace 041008fb094ca06d9a6ab4115f9e7b78
Deux listes classées alimentent une liste fusionnée. Recherche par mots-clés, selon les mots : 1er Beta : joined up experience, 6e Discovery : How long a discovery should take; Daily standup ne figure pas dans ses 20 premiers résultats. Recherche vectorielle, selon le sens : 1er Daily standup, la réponse, 2e Emergency : Use agile at pace, 9e Beta : joined up experience. La liste fusionnée additionne 1 divisé par (60 plus le rang) de chaque liste : 1er Beta : joined up experience, 1/69 plus 1/61 égale 0,0309; 2e Discovery, 1/68 plus 1/66 égale 0,0299; 3e Core principles, 0,0293; 4e Live : running your service, 0,0288; 5e Retiring : related guides, 0,0258. Ces 5 premiers résultats vont au modèle, qui répond que les guides ne le précisent pas. Daily standup, mis en évidence, obtient 1/61 plus 0 égale 0,0164 et arrive 6e : une ligne pointillée étiquetée coupure : rang 6 s'arrête avant le modèle.
Pourquoi G01 a échoué, selon le diagnostic de l'auteur sur le projet chargé. La bonne section arrivait première dans une liste et manquait dans l'autre. Les passages trouvés par les deux listes l'ont donc repoussée au sixième rang.
Description textuelle du diagramme

Lisez l’image de gauche à droite. La recherche vectorielle a placé Daily standup en premier. La recherche par mots-clés ne l’avait pas dans ses 20 premiers résultats. La fusion donne à chaque passage 1 ÷ (60 + rang) de chaque liste et additionne les votes. Une première place dans une liste vaut 1/61 = 0,0164. Deux places, 9e et 1re, valent 0,0309. Cinq passages trouvés par les deux listes sont donc arrivés avant, et Daily standup est arrivé sixième. Le modèle voit seulement les 5 premiers.

C’est la fusion par rang réciproque, présentée dans Recherche lexicale, dense et hybride et Examiner les catégories d’erreurs. Là aussi, deux votes faibles battaient un vote fort. Pourquoi la recherche par mots-clés a-t-elle raté la section? Elle classe un passage selon le nombre de mots de la question qu’il contient et leur proximité. Elle ignore que « standup » (réunion debout) est rare. À l’inverse, « how » (comment), « long » (long) et « should » (devrait) figurent dans presque tous les guides. Les passages remplis de mots courants sont donc arrivés en premier. G30 et G49 sont tombés sous la limite de la même façon. Chaque bonne section était bien classée dans une liste, mais mal classée ou absente dans l’autre. Elles sont donc arrivées 7e et 8e. L’auteur l’a découvert en listant le rang de la bonne section dans chaque liste. Cette analyse porte sur des échecs déjà comptés : elle ne change aucun score.

Montrez cet échec dans une démo. Il est sans danger : l’assistant a refusé au lieu d’inventer un nombre. Mais il n’est pas utile : une nouvelle recrue penserait que le manuel ne dit rien sur les réunions debout. Dans cette collection, la recherche est le point faible, pas le modèle.

Que se passe-t-il ensuite? G01 et G30 passent aux données de réglage, où vous pouvez maintenant les étudier. De nouvelles questions réservées les remplacent. Une personne qui n’a pas vu les résultats les écrit. Ensuite, testez équitablement la recherche dense ou davantage de passages par question (TOP_K), avec assez de questions pour satisfaire la règle. Le rapport d’évaluation, docs/evaluation-report.md dans le projet terminé, énumère tout cela.

L’équipe de Ruth réserve son évaluation alpha, et Ruth veut que l’assistant réponde à ce sujet. Le guide What happens at a service assessment appartient à un autre sujet du manuel. L’assistant ne peut donc pas encore répondre :

Fenêtre de terminal
python -m scripts.ask "How long does a service assessment last?"
Ruth (owner) at Westbrook digital team asks: How long does a service assessment last?
Passages found: 9d919d981425 how-the-beta-phase-works v4, 684964e4dfdb running-your-service-in-a-sustainable-way v2, 3f71a3a020f2 retiring-your-service v2, b598b7feab08 how-the-beta-phase-works v4, 5f355a76d6f1 running-your-service-in-a-sustainable-way v2
Answer (not answerable): The guides do not say how long a service assessment lasts.
recorded chat-small | 3308 ms | tokens 1459 in, 31 out | US$0.000161 | trace 206a36fb03f9af69d265c9fb19e1b0dc

L’instantané inclut ce guide, dans data/snapshot/new-input/. Convertissez-le, puis téléversez-le par le vrai parcours du produit : l’API, comme Ruth, avec un jeton d’exercice. Utilisez trois terminaux, tous avec .venv actif.

  1. Convertissez le guide :

    Fenêtre de terminal
    python -m scripts.collection convert data/snapshot/new-input/how-service-assessments-work.json
    Wrote data/new-input/how-service-assessments-work.md: What happens at a service assessment (last updated 2026-09-07).
  2. Dans le terminal 2, démarrez le fournisseur d’identité d’exercice : python -m idp. Dans le terminal 3, démarrez l’API : fastapi run doc_assistant/main.py.

  3. Revenez au terminal 1 et téléversez le guide comme Ruth :

    Fenêtre de terminal
    TOKEN=$(python -m idp token usr-ruth)
    curl -s -X POST http://127.0.0.1:8000/v1/tenants/westbrook/documents -H "Authorization: Bearer $TOKEN" -F "file=@data/new-input/how-service-assessments-work.md"
    {"document":{"document_id":"16cac3b5-966c-42c0-b260-a8ddae5ad9ed","doc_key":"how-service-assessments-work","version":"8","title":"What happens at a service assessment","doc_type":"guide","language":"en","access":"public","effective_from":"2026-09-07","effective_to":"","file_name":"how-service-assessments-work.md","size_bytes":6710,"sha256":"8b81216955d12ac83f81656f9209f01ee745640216cb95d77ae5c8c623ffbf54","status":"uploaded","error":null,"attempts":0,"chunk_count":0,"uploaded_by":"usr-ruth","uploaded_at":"2026-10-11T18:37:12.838893+00:00","indexed_at":null,"links":{"self":"/v1/tenants/westbrook/documents/16cac3b5-966c-42c0-b260-a8ddae5ad9ed"}},"duplicate":false}

    La réponse indique "status":"uploaded" (état : téléversé) : le processus indexe le guide en arrière-plan. Vos identifiants et vos temps seront différents.

  4. Attendez quelques secondes que le processus termine. Dans l’exécution de l’auteur, la liste des documents montrait ensuite 21 guides indexés, dont le nouveau avec 11 passages. Posez de nouveau la question :

    Fenêtre de terminal
    python -m scripts.ask "How long does a service assessment last?"
    Ruth (owner) at Westbrook digital team asks: How long does a service assessment last?
    Passages found: 36c81f3bbff0 how-service-assessments-work v8, a3d94db45906 how-service-assessments-work v8, dcb51899a15d how-service-assessments-work v8, 9d919d981425 how-the-beta-phase-works v4, d8911bff8979 how-service-assessments-work v8
    Answer (answerable): A service assessment usually lasts about 4 hours.
    - Service assessments usually last about 4 hours. [What happens at a service assessment, start, v8]
    recorded chat-small | 3383 ms | tokens 1503 in, 54 out | US$0.000177 | trace 917ba9a10cbfa23d206857995c3abb60

Ce que cela nous apprend. Le nouveau guide a suivi le même parcours que chaque document : téléversement, états de la tâche, processus, onze nouveaux passages. La même question a ensuite obtenu une réponse avec citation du nouveau guide. Rien d’autre n’a changé : aucun redémarrage et aucun nouveau code. Les réponses de cette partie sont aussi des enregistrements, faits avant et après le même téléversement.

Enfin, exécutez le test de vérification rapide du cours sur l’API active : python scripts/smoke.py http://127.0.0.1:8000, avec SMOKE_TOKEN défini au jeton. Il se termine par 7 of 7 checks passed. (7 vérifications sur 7 réussies). Une équipe fictive obtient 404. Arrêtez les deux serveurs avec Ctrl+C.

Pour Ruth : oui, utilisez-le comme premier point de consultation, avec deux conditions. L’assistant a respecté chaque seuil sur des questions qui n’ont servi à aucun réglage. Il a répondu correctement à 18 questions sur 21 ayant une réponse, refusé chaque question sans réponse et fourni uniquement des citations valides. Il prenait environ 1,3 à 1,7 seconde et coûtait 0,0002 $ US par question. Ses échecs étaient des refus, pas des inventions. Les conditions :

  1. Ouvrez la section citée. La réponse est courte; le guide fait autorité. La page montre le passage en un clic.
  2. « Les guides ne le précisent pas » n’est pas une conclusion définitive. Dans cette collection, la recherche rate parfois une section qui existe (G01, G30, G49). Quand l’assistant refuse une question de base, cherchez aussi sur GOV.UK. Puis informez Ruth, pour que la question rejoigne les prochaines données de réglage.
  • Une règle écrite d’avance vaut plus qu’un graphique. Sans elle, un gain d’une question aurait semblé être une amélioration.
  • Les données de réglage peuvent être trop faciles. À 34 sur 35, elles ne permettaient pas de départager les versions. Des questions plus nombreuses et plus difficiles, surtout des reformulations, rendraient la prochaine comparaison plus équitable.
  • Sur une collection publique, le risque se déplace. Aucun locataire ne risque de voir ses données divulguées, et aucune instruction n’est cachée. Le risque est un mauvais guide, un ancien guide ou une section ratée.
  • Limites de cette étude. Une personne a écrit les 60 questions et connaît les guides. Avec 25 questions réservées, une question vaut 4 points. L’étude couvre un sujet d’un manuel, sur un ordinateur portable partagé, sous macOS seulement.
  • Des orientations, pas des conseils. GOV.UK dit ne pas publier de conseils. Dites la même chose dans votre produit : l’assistant indique le guide, et les gens décident.
  • L’attribution est une condition de la licence. Gardez la phrase d’attribution de la licence et l’adresse source dans le README et la fiche de données. N’utilisez pas la couronne ni les logos de GOV.UK : la licence les exclut.
  • N’imitez pas le gouvernement. Votre page de portfolio ne doit pas ressembler à GOV.UK ni parler au nom du Government Digital Service. Présentez-la comme votre projet.
  • Indiquez son ancienneté. Les réponses décrivent l’instantané. Donnez sa date dans le README et exécutez python -m scripts.collection check avant une démo.
  • Respectez la source. Le script de récupération attend entre les requêtes. Ne dirigez jamais un test de charge vers GOV.UK.

Ce projet montre ce que les employeurs recherchent. Il comprend une vraie collection avec une licence vérifiée, une évaluation planifiée avant les résultats, une comparaison équitable et des échecs expliqués. Le fichier README.md du projet terminé sert de modèle.

Quoi mettre dans le dépôt :

public-collection-capstone/
README.md the user and decision, the result, the recommendation, how to run it, the limits
LICENSE MIT, for the code
data/dataset.md the source, the licence and attribution, the snapshot, the conversion, the limits
data/snapshot/ the exact files used, with SHA256SUMS
docs/project-brief.md one user, one decision, the non-goals, why one tenant
docs/acceptance-criteria.md the thresholds and the rule for a change, written first
docs/evaluation-report.md the held-out result, the three failures, the comparison
evaluation/ the 60 questions, the held-out set and its lock
recordings/ the recorded answers: anyone can rerun the evaluation without a key
reports/ the held-out result, and the live runs with their times and costs
scripts/collection.py prepare, check, convert
  1. Envoyez le dépôt sur GitHub. Vérifiez que .env et .idp/ n’y sont pas : .gitignore les exclut.
  2. Mettez le résultat dans les premières lignes du README : 22 questions réservées sur 25, les seuils respectés et la recommandation avec ses deux conditions.
  3. Ajoutez un lien vers docs/evaluation-report.md. Nommez les trois échecs dans le README, pas seulement dans le rapport.
  4. À partir d’un clone neuf, exécutez le démarrage rapide du README. Indiquez ensuite dans le README que vous l’avez fait.

C’est l’une des deux études de cas que vous pouvez choisir pour le certificat. Pour vous l’approprier, prenez un autre sujet du Service Manual (Service assessments compte 8 guides), ou une autre collection sous licence ouverte. Écrivez de nouvelles questions et réservez-les d’abord. Enregistrez vos propres réponses avec un modèle en direct et gardez la règle.

Vérifiez votre compréhension

Chaque option a répondu correctement aux 35 questions de réglage sur 35, contre 34 pour la référence de base. Pourquoi l'avoir gardée, et était-ce la bonne décision?

Afficher la réponse

La règle, écrite avant toute réponse, exige au moins 2 réponses correctes de plus. Deux exécutions identiques en direct peuvent différer d’une question. Chaque option faisait mieux de 1 réponse (G49 seulement). Selon la règle, garder la référence de base était correct. Le compte rendu honnête indique que la recherche dense a corrigé une question reformulée, mais que les preuves étaient insuffisantes pour changer. La prochaine étape consiste à ajouter des questions de réglage plus nombreuses et plus difficiles, pas à changer discrètement.

Vérifiez votre compréhension

L'assistant a répondu « Les guides ne le précisent pas » à « Combien de temps devrait durer notre réunion debout quotidienne? », malgré une section indiquant « 15 minutes ou moins ». Est-ce un échec du modèle ou de la recherche, et comment le savez-vous?

Afficher la réponse

Un échec de la recherche. L’évaluation marque la question hit False : aucun passage pertinent n’est parvenu au modèle. python -m scripts.ask liste les passages que le modèle a vus, et la section Daily standup n’en fait pas partie. Avec ces seuls passages, le modèle a eu raison de refuser. La correction doit porter sur la recherche et être testée sur les données de réglage.

Vérifiez votre compréhension

Un ami veut éviter l'instantané : « Récupère simplement les guides de GOV.UK chaque fois, pour qu'ils soient toujours à jour. » Qu'est-ce qui ne fonctionne plus, et quand son idée est-elle bonne?

Afficher la réponse

Quand un guide change, ses passages et leurs identifiants changent. Les réponses enregistrées ne correspondent plus, et les corrigés réservés peuvent ne plus être exacts. Deux personnes ayant exécuté les mêmes commandes ont alors mesuré des collections différentes. Son idée est bonne pour un produit en usage, qui doit suivre GOV.UK. Faites alors une mise à jour volontaire : nouvel instantané, nouveaux enregistrements ou réponses en direct, et nouvelle exécution sur les données réservées. Mettez la date de l’instantané dans le README.

Récapitulatif

  • Vous avez délimité le produit pour un utilisateur et une décision, avec des objectifs exclus et un seul locataire. Vous avez écrit les seuils et la règle de changement avant toute réponse.
  • Vous avez vérifié la licence, gardé un instantané avec des sommes de contrôle, l’avez converti et avez écrit la fiche de données.
  • Vous avez réservé 25 questions avant toute réponse; la répartition correspondait au verrouillage de l’auteur.
  • Trois options ont chacune corrigé une question de réglage. La règle en exigeait deux, donc la référence de base est restée.
  • L’exécution sur les données réservées a respecté chaque seuil : 18 sur 21 ayant une réponse, 4 refus sur 4, citations valides. Les échecs étaient deux sections ratées par la recherche et un corrigé strict.
  • Un nouveau guide est entré par l’API et a été cité aussitôt. Le README raconte toute l’histoire.

Ensuite, la deuxième étude de cas : évaluez un projet intégrateur faible avec la grille.

Leçon suivante : Évaluer un projet intégrateur faible