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.
Étude de cas 1 sur 2 · Projet intégrateur : créer, évaluer et livrer un produit d'IAProjet intégrateur sur une collection publique de documents
1. Choisir et délimiter le projet
2. Préparer les données et l'architecture
3. Créer un parcours utilisateur complet
4. Ajouter la fiabilité et le contrôle d'accès
5. Évaluer et améliorer
6. Déployer et exploiter
7. Préparer la présentation du 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.
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 main
Ce que vous devez savoir
Cette étude de cas reprend tout le cours avec de nouveaux documents. Elle utilise surtout ces leçons :
- Problème et public, Critères d’acceptation et Planifier les preuves
- Ensemble de données synthétiques
- Exécuter les tests sur des données réservées, Examiner les catégories d’erreurs et Documenter les compromis
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.
La situation
Section intitulée « La situation »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.
Ce que vous allez créer
Section intitulée « Ce que vous allez créer »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 |
Préparer le projet
Section intitulée « Préparer le projet »Les étapes utilisent VS Code et son terminal. Toutes les commandes s’exécutent dans le dossier du projet.
-
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 dossierpublic-collection-capstone. -
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). -
Créez et activez un environnement virtuel, puis installez les paquets :
Fenêtre de terminal python3 -m venv .venvsource .venv/bin/activatepython -m pip install -r requirements.txtFenêtre de terminal py -3.12 -m venv .venv.venv\Scripts\Activate.ps1python -m pip install -r requirements.txtSur Linux sans processeur graphique, installez d’abord la version pour processeur central de PyTorch, comme l’indique le début de
requirements.txt. -
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 .envFenêtre de terminal Copy-Item .env.example .env -
Créez les clés du fournisseur d’identité d’exercice, puis démarrez PostgreSQL :
Fenêtre de terminal python -m idp initdocker compose up -d --wait dbidp initvient en premier : cette commande écrit deux secrets dans.env, sans lesquels Compose refuse de démarrer. -
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.
Partie 1 : définir la portée
Section intitulée « Partie 1 : définir la portée »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.
Partie 2 : la collection
Section intitulée « Partie 2 : la collection »La licence d’abord
Section intitulée « La licence d’abord »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 ».
Un instantané d’une source qui évolue
Section intitulée « Un instantané d’une source qui évolue »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.
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.
Convertir et vérifier
Section intitulée « Convertir et vérifier »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 :
python -m scripts.collection preparepython -m scripts.datapackSnapshot: 22 of 22 files match data/snapshot/SHA256SUMSWrote 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 SHA256SUMSwestbrook: 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: noneEvery 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 :
## 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 :
python -m scripts.collection check20 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. »
Partie 3 : réserver les questions de test
Section intitulée « Partie 3 : réserver les questions de test »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 :
python -m scripts.holdout reserveHeld 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 :
git initgit 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.
Partie 4 : la référence de base
Section intitulée « Partie 4 : la référence de base »Chargez la collection dans PostgreSQL, comme documents d’une seule équipe :
python -m scripts.load_packIdentity: 1 tenants, 2 people, 2 membershipswestbrook: 20 documents uploaded, 0 already thereIndexing with intfloat/multilingual-e5-small@614241f ...Indexed 20 documents in 9.7 s (failed 0). westbrook: 20 documents, 225 passages, 0 failedLa 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 :
python -m scripts.evaluate --set dev --show-failureshybrid, 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.
Partie 5 : trois options, une mesure
Section intitulée « Partie 5 : trois options, une mesure »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?
python -m scripts.evaluate --set dev --retrieval-only --show-failures --config RETRIEVAL_MODE=denseExé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 mshybrid, 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 mshybrid_rerank, guide_v1, recorded: retrieval hit 1.000 (30 of 30 questions with relevant passages), median search time 362.0 msEnsuite, mesurez ce qu’utilise la règle : les réponses correctes. Exécutez l’évaluation complète avec chaque option, par exemple :
python -m scripts.evaluate --set dev --show-failures --config RETRIEVAL_MODE=dense- Référence de base (hybride)
- Options
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 »python -m scripts.evaluate --set heldout --show-failures --out reports/heldout-baseline.jsonhybrid, 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.jsonComparez 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|upcomingne 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 :
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 v2Answer (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 041008fb094ca06d9a6ab4115f9e7b78Description 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.
Partie 7 : nouvelle entrée, de bout en bout
Section intitulée « Partie 7 : nouvelle entrée, de bout en bout »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 :
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 v2Answer (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 206a36fb03f9af69d265c9fb19e1b0dcL’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.
-
Convertissez le guide :
Fenêtre de terminal python -m scripts.collection convert data/snapshot/new-input/how-service-assessments-work.jsonWrote data/new-input/how-service-assessments-work.md: What happens at a service assessment (last updated 2026-09-07). -
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. -
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"Fenêtre de terminal $TOKEN = python -m idp token usr-ruthcurl.exe -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. -
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 v8Answer (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.
La recommandation
Section intitulée « La recommandation »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 :
- Ouvrez la section citée. La réponse est courte; le guide fait autorité. La page montre le passage en un clic.
- « 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.
Constats et limites
Section intitulée « Constats et limites »- 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.
Utilisation responsable
Section intitulée « Utilisation responsable »- 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 checkavant 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.
Faites-en un projet de portfolio
Section intitulée « Faites-en un projet de portfolio »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- Envoyez le dépôt sur GitHub. Vérifiez que
.envet.idp/n’y sont pas :.gitignoreles exclut. - 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.
- Ajoutez un lien vers
docs/evaluation-report.md. Nommez les trois échecs dans le README, pas seulement dans le rapport. - À 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érification des connaissances
Section intitulée « Vérification des connaissances »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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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