Revue de conception d'un service ouvert de questions sur des documents
- Étude de cas 2
- 180 min
- Facultative · 1 étude de cas requise pour le certificat
Où nous en sommes
Cette étude de cas applique tout le dossier de conception à une collection qui n'est pas celle de Larkfield : un service public gratuit qui répond à des questions à partir de vrais documents gouvernementaux sur la sécurité. Vous comptez la collection, dimensionnez et chiffrez la conception, et rédigez une courte revue qu'une personne sans formation en ingénierie peut utiliser.
Étude de cas 2 sur 2 · Conception de systèmes d'IA et maîtrise des coûtsRevue de conception d'un service ouvert de questions sur des documents
1. Commencer par les besoins
2. Concevoir l'architecture de bout en bout
3. Estimer les ressources et le coût
4. Optimiser avec des compromis mesurés
5. Concevoir pour les défaillances et la croissance
6. Présenter la proposition
Ce que vous saurez faire
Examinez la conception d’un service public gratuit qui répond aux questions sur une vraie collection de documents gouvernementaux. Comptez les documents au lieu d’en estimer le nombre. Dimensionnez ensuite le stockage et estimez le temps de chargement. Choisissez le modèle et le cache avec les mesures du cours. Rédigez les décisions et le plan en cas de défaillance. Vous obtiendrez une courte revue qu’une personne sans formation en ingénierie pourra utiliser.
Le projet de départ reprend le dossier de conception du cours et ajoute un dossier, corpus/. Celui-ci télécharge les documents et en mesure la taille. Le projet terminé donne le résultat, pour vous aider si vous bloquez. Le code est sous licence MIT.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
Cette étude de cas applique tout le cours à une collection qui n’appartient pas à Larkfield. Voici les leçons les plus importantes : Préparer le dossier de conception (les trois types de nombres), Calculer la charge de travail, Économie unitaire, Routage entre modèles, Cache et traitement par lots, Objectifs de reprise et Décisions d’architecture. Vous n’avez pas besoin de l’autre étude de cas.
Ce qu’il vous faut sur votre ordinateur
- Python 3.12 ou une version plus récente, et VS Code.
- Environ 70 Mo d’espace disque libre : l’environnement virtuel (environ 56 Mo), les documents (5 Mo) et les données de segmentation.
- Une connexion Internet pour la préparation.
tiktokentélécharge ses données de segmentation une seule fois.
Aucun compte ni paiement nécessaire. L’équipe du cours a effectué les appels aux modèles pour cette étude de cas. Les résultats sont dans les fichiers du projet.
Testé sur macOS (Apple M4, Python 3.12.13). Les commandes Windows et Linux sont fournies, mais n’ont pas été testées.
La situation
Section intitulée « La situation »Fernhollow Safety Line (« Fernhollow » en bref) est un petit service téléphonique de conseil pour les employeurs aux États-Unis. Trois conseillers en sécurité répondent au téléphone. Les appelants posent des questions comme « Mes couvreurs ont-ils besoin d’un plan écrit contre la chaleur? » ou « Qu’est-ce qui a changé dans les étiquettes des produits chimiques? » Les réponses se trouvent dans les règles de l’Occupational Safety and Health Administration (OSHA). Les nouvelles règles, propositions et corrections paraissent dans le Federal Register, le journal quotidien du gouvernement.
Lena Ortiz dirige Fernhollow. Elle dispose d’une subvention de 100 $ US par mois pour une page publique gratuite. Chaque personne peut saisir une question, et la page répond en citant les documents de l’OSHA. Niko Varga, un développeur bénévole, a dessiné une première conception. Aisha Rahman, la conseillère principale, vérifiera les réponses. Les personnes et Fernhollow sont inventées; les documents sont réels.
Trois idées de Niko inquiètent Lena :
- « Il y a des milliers de pages. Il nous faut un service de base de données vectorielle. »
- « Les textes juridiques sont difficiles. Utilisons le modèle puissant pour chaque réponse. »
- « Encore plus simple : mettons tous les documents dans la requête. Le fournisseur met les longues requêtes en cache. »
Lena vous demande une revue de conception. « Que devrions-nous construire? Combien cela coûte-t-il chaque mois? Qu’est-ce qui peut mal fonctionner, et qui le corrige? Utilisez des nombres et dites-moi lesquels sont des estimations. »
L’objectif. Une revue que Lena peut utiliser : la taille de la collection obtenue par comptage, une fourchette de coûts par locataire, deux ou trois décisions justifiées et un tableau des défaillances avec responsables et cibles de reprise. Chaque nombre indique s’il s’agit d’une mesure, d’un prix ou d’une hypothèse.
Ce que vous allez construire
Section intitulée « Ce que vous allez construire »Description textuelle du diagramme
On compte d’abord la collection. Ses nombres vont dans un fichier que lit le calculateur du cours. Le calculateur utilise la demande et la conception pour donner les coûts. Les décisions et le tableau des défaillances utilisent les deux. Tout aboutit à un seul fichier pour Lena.
| Partie | Ce que vous faites | Ce que vous obtenez |
|---|---|---|
| 1 | vérifier les données | les documents sont complets; le texte doit être nettoyé |
| 2 | compter les jetons avec un outil de segmentation | le nombre réel de jetons, et pourquoi une estimation est risquée |
| 3 | dimensionner le stockage et l’ingestion | des mégaoctets, des minutes et des dollars, et corpus.toml |
| 4 | comparer la référence de base et les autres options | une mesure de coût pour chaque conception |
| 5 | rédiger les décisions | trois fiches ADR |
| 6 | rédiger le tableau des défaillances | six défaillances avec responsables, RTO et RPO |
| 7 | coût par locataire et quota | la fourchette pour Lena, et la première limite |
| 8 | nouveaux documents, de bout en bout | le plan vérifié avec les documents de 2026 |
Les données
Section intitulée « Les données »Le Federal Register publie chaque règle, proposition de règle et avis de l’OSHA. Son API ne nécessite aucun compte. Les documents sont des œuvres du gouvernement américain. Ils appartiennent donc au domaine public (17 U.S.C. 105). Certains peuvent citer du contenu protégé par le droit d’auteur, comme l’indique l’avis de GovInfo. Citez donc de courts passages avec leur référence.
L’équipe du cours a pris deux copies figées : les documents de l’OSHA de janvier 2021 à décembre 2025 (628), puis les nouveaux documents de janvier à septembre 2026 (83). Chaque ligne représente un document : son numéro, son type, son titre, sa date, ses pages imprimées et son texte brut. Une copie figée avec une somme de contrôle donne les mêmes octets à chaque personne qui suit le cours. DATASET.md, dans le projet, est la fiche du jeu de données.
Ces documents ne sont pas les règles en vigueur. Une proposition de règle peut ne jamais devenir une règle. Les règles en vigueur se trouvent dans le Code of Federal Regulations. L’étude de cas Répondre à partir de règlements versionnés du cours RAG : créer une IA qui utilise vos données utilise ce code.
Préparer le projet
Section intitulée « Préparer le projet »-
Téléchargez le projet de départ dans l’encadré en haut de cette page. Décompressez-le dans votre dossier de projets. Vous obtenez le dossier
open-docs-review. -
Dans VS Code, choisissez File > Open Folder (fichier, ouvrir un dossier) et ouvrez
open-docs-review. 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 python -m venv .venv.venv\Scripts\Activate.ps1python -m pip install -r requirements.txtFenêtre de terminal python3 -m venv .venvsource .venv/bin/activatepython -m pip install -r requirements.txtL’invite commence par
(.venv). Les paquets sont tiktoken 0.14.0 (un outil de segmentation en jetons), pytest 9.1.1 et ruff 0.17.0. Le calculateur ne nécessite toujours que la bibliothèque standard de Python. -
Téléchargez les documents et vérifiez-les :
Fenêtre de terminal python -m corpus getSortie Downloading https://github.com/Nextia-Intelligence/nextia-learning-labs/raw/main/C26/M07-L02-design-review/data/osha-fr-2021-2025.jsonl.gzChecked osha-fr-2021-2025.jsonl.gz: SHA-256 81b47f96634a... is correctDownloading https://github.com/Nextia-Intelligence/nextia-learning-labs/raw/main/C26/M07-L02-design-review/data/osha-fr-2026-new.jsonl.gzChecked osha-fr-2026-new.jsonl.gz: SHA-256 3ee6af82c139... is correct -
Exécutez les tests :
Fenêtre de terminal python -m pytest -qSortie (fin) FAILED tests/test_corpus.py::test_tokens_are_counted_with_the_tokenizer_not_guessed1 failed, 11 passed in 0.04s
Ce que cela nous apprend. Les deux fichiers sont arrivés sans modification : leurs sommes de contrôle SHA-256 correspondent aux valeurs attendues. Un test échoue volontairement. Le projet de départ estime le nombre de jetons. La partie 2 remplace cette estimation par un compte.
Partie 1 : vérifier les données
Section intitulée « Partie 1 : vérifier les données »Avant de dimensionner quoi que ce soit, vérifiez que les données correspondent à vos attentes :
python -m corpus checkChecked osha-fr-2021-2025.jsonl.gz: SHA-256 81b47f96634a... is correctDocuments: 628; types: Notice 517, Proposed Rule 72, Rule 39Published: 2021-01-11 to 2025-12-31Without text: 0; repeated document numbers: 0; without a page count: 0Raw pages: 20,451,255 characters; text after cleaning: 18,652,871 (8.8% was markup)Shortest: C1-2021-26268 (Rule, 118 words, 1 page)Ce que cela nous apprend.
- Complètes. Chaque document contient du texte et un nombre de pages. Aucun document n’apparaît deux fois.
- Surtout des avis. Parmi les 628 documents, 517 sont des avis, par exemple une demande de commentaires sur un formulaire. Seulement 39 sont des règles.
- Le texte est une page Web. Le « texte brut » de l’API est une petite page HTML. Le texte se trouve dans
<pre>, avec des liens, des marques<bullet>et des indices commeLD<INF>50</INF>. Le balisage représentait 8,8 % des caractères.corpus/load.pyle retire avant tout comptage. Sans cette étape, chaque compte ci-dessous serait trop élevé d’environ un dixième.
Partie 2 : compter les jetons, sans les estimer
Section intitulée « Partie 2 : compter les jetons, sans les estimer »Le problème : la facture compte les jetons
Section intitulée « Le problème : la facture compte les jetons »Un service de livraison facture selon le poids, pas selon le nombre de colis. Dix boîtes de livres coûtent plus cher que dix boîtes d’oreillers.
Un fournisseur de modèles facture selon les jetons, et ses quotas comptent aussi les jetons. Un jeton est un morceau de texte que le modèle lit comme une unité. C’est souvent un mot courant entier. Parfois, c’est une partie de mot, une espace ou un signe de ponctuation. Un outil de segmentation en jetons découpe le texte en jetons. Chaque famille de modèles a le sien. (Les éléments d’une requête présentait les jetons.)
Le cours utilisait 1,48 jeton par mot, une mesure obtenue sur les politiques du magasin du cours RAG. Le projet de départ utilise cette valeur comme estimation. Voici pourquoi une estimation est risquée pour les textes juridiques :
Description textuelle du diagramme
« Guardrails are 42 inches high. » (les garde-corps ont une hauteur de 42 pouces) contient 5 mots et 8 jetons. « 29 CFR 1910.134(c)(2)(ii) » contient 3 mots et 13 jetons : chaque nombre, parenthèse et point constitue un morceau distinct.
Quel outil de segmentation?
Section intitulée « Quel outil de segmentation? »Utilisez l’outil de segmentation qui sert à la facturation. L’équipe du cours l’a vérifié avec de vrais appels. Elle a envoyé 32 lots de segments de cette collection au modèle de plongement, embed-small. Elle a comparé les jetons facturés avec deux comptes locaux. L’outil de segmentation cl100k_base a donné exactement le nombre facturé pour 32 appels sur 32 (167 297 jetons; mesuré). Le modèle de conversation, chat-small, compte avec un autre outil, o200k_base. Celui-ci a donné environ 1,5 % moins de jetons sur le même texte. Cette revue utilise cl100k_base partout. Les estimations des réponses sont donc un peu élevées : c’est le choix prudent.
Comptez-les
Section intitulée « Comptez-les »Exécutez d’abord le calcul de taille avec l’estimation :
python -m corpus sizeCollection: 628 documents, 3,676 printed pages, 2,450,514 words tokens 3,626,755 (1.48 per word, 987 per page; guessed: words x 1.48)Ouvrez maintenant corpus/size.py. Remplacez la ligne TOKENS_HOW = ... et la fonction count_tokens par ceci :
TOKENS_HOW = "cl100k_base" # how the tokens below are found
def count_tokens(text: str) -> int: """Count with the tokenizer: the same count as the provider's bill for embed-small (measured).""" import tiktoken # the embedding model's tokenizer; get_encoding keeps it loaded after the first call
return len(tiktoken.get_encoding("cl100k_base").encode(text, disallowed_special=()))Exécutez de nouveau le calcul de taille et les tests :
python -m corpus sizepython -m pytest -qCollection: 628 documents, 3,676 printed pages, 2,450,514 words tokens 3,710,587 (1.51 per word, 1,009 per page; cl100k_base)...12 passed in 0.07sDescription textuelle du graphique
La plupart des documents ont entre 1,4 et 1,6 jeton par mot, près de l’estimation de 1,48. Le minimum est de 1.288 et le maximum de 2.443 jetons par mot : des tableaux de nombres et de longues références.
Ce que cela nous apprend. Pour toute la collection, l’estimation était trop basse de 2 %, car le texte ordinaire domine. Mais un document contient 65 % plus de jetons que l’estimation. Une revue de conception compte, car les quotas et les défaillances dépendent des documents individuels, pas de la moyenne.
Partie 3 : dimensionner le stockage et l’ingestion
Section intitulée « Partie 3 : dimensionner le stockage et l’ingestion »Le reste de la sortie du calcul de taille :
chunks 14,961 (6.1 per 1,000 words; 263 tokens each with the title) tokens to embed 3,941,704 (the chunks with their titles: +6% on the text) by type Rule 39 documents, 34% of the tokens; Notice 517 documents, 34% of the tokens; Proposed Rule 72 documents, 32% of the tokens the 10 largest 49% of all tokensStorage: vectors with table and index 71.8 MB, chunk text 18.5 MB, document files 18.7 MB in the database 90.4 MB = 0.3% of the smallest size (32 GB)Ingest everything once: 3,941,704 tokens, US$0.08, 695 calls of up to 100 chunks one call at a time 8 min; at the token quota 39 min: about 39 minNew documents per month (60 months): low 0, median 10, mean 10.5, high 37Chaque ligne multiplie un compte par une valeur mesurée ou un prix :
- Segments.
corpus/chunk.pyconserve la règle du cours RAG présentée dans Découper de façon réfléchie : paragraphes entiers, au plus 200 mots, chaque segment commençant par le titre du document. Les titres ajoutent 6 % aux jetons à convertir en plongements. - Stockage. 14 961 segments × 4 800 octets par vecteur avec sa table et son index (mesuré dans le cours sur les bases de données, 384 nombres) = 71,8 Mo. Avec le texte des segments, la base de données contient 90,4 Mo. La plus petite capacité de stockage est de 32 Go (liste de prix). Le stockage n’est donc pas une question de conception ici.
- Ingestion. 3 941 704 jetons × 0,02 $ US par million (liste de prix) = 0,08 $ US. Le temps est la vraie limite. Chaque appel prend environ 0,43 s plus 0,04 s par 1 000 jetons (mesuré). Ainsi, 695 appels exécutés un à la fois prennent environ 8 minutes. Mais le quota du modèle de plongement est de 100 000 jetons par minute (mesuré : en-tête de limitation du fournisseur). La collection entière nécessite au moins 39 minutes. L’échantillon de 167 297 jetons de l’équipe du cours a atteint ce quota quatre fois en environ deux minutes (HTTP 429, mesuré).
Description textuelle du graphique
Le plus grand document, 2024-14824 (Heat Injury and Illness Prevention in Outdoor and Indoor Work Settings, « Heat », chaleur), contient 484,968 jetons. Les deux suivants sont 2021-12428 (Occupational Exposure to COVID-19; Emergency Temporary Standard, « COVID », 315,810 jetons) et 2024-08568 (Hazard Communication Standard, « HazCom », 229,771 jetons). Les sept suivants contiennent ensemble 797,709 jetons, et les 618 autres documents, 1,882,329.
Ce que cela nous apprend. Le document médian compte 2 pages imprimées. Le plus grand compte 376 pages : la proposition de 2024 sur les blessures liées à la chaleur, soit 484 968 jetons. Planifiez le chargement, les délais d’expiration et les nouvelles tentatives pour celui-ci, pas pour la moyenne. Le stockage est minime; le temps et le quota comptent vraiment.
Mettre les comptes dans le dossier
Section intitulée « Mettre les comptes dans le dossier »Deux fichiers renseignent le calculateur sur la collection :
-
Ouvrez
demand.toml. Le projet de départ contient encore les valeurs de la collection Larkfield du cours, marquéesTODO(à faire). Remplacez-les par vos comptes et changez leur preuve pourverified:(vérifié) :demand.toml (part) documents = [628, 628, 628]words_per_document = [3902, 3902, 3902]document_changes_per_month = [10, 10.5, 37]demand.toml (evidence, part) documents = "verified: python -m corpus check counted 628 documents, 2021 to 2025"words_per_document = "verified: python -m corpus size counted 2,450,514 words in 628 documents (mean 3,902)"document_changes_per_month = "verified: new documents per month, 60 months: median 10, mean 10.5, busiest month 37 (python -m corpus size)"Les lignes des visiteurs restent des hypothèses : Fernhollow n’a pas encore de trafic. Lena estime que 250 visiteurs poseront des questions par jour (de 50 à 1 000).
-
Écrivez les valeurs mesurées de cette collection pour le calculateur :
Fenêtre de terminal python -m corpus writeSortie Checked osha-fr-2021-2025.jsonl.gz: SHA-256 81b47f96634a... is correctingest_embed_tokens_per_word 1.61 tokens per wordchunks_per_1000_words 6.11 chunkschunk_text_bytes_per_word 7.57 bytes per worddocument_file_bytes 29,709.91 bytes per document (mean)answer_small_tokens_in 2,002.28 tokens per answer (estimate)answer_strong_tokens_in 2,002.28 tokens per answer (estimate)Wrote corpus.toml: the calculator now uses this collection's values
costmodel/inputs.py lit corpus.toml après measured.toml. Ces six valeurs remplacent donc celles du cours. Les deux dernières méritent une précision. Le cours a mesuré 946,5 jetons d’entrée par réponse, avec cinq passages d’environ 52 jetons chacun. Les segments de cette collection contiennent 263 jetons. La même requête avec cinq de ces segments représente donc environ 946,5 − 5 × 52,31 + 5 × 263,47 = 2 002 jetons. C’est une estimation tirée d’éléments mesurés, et le fichier l’indique.
Partie 4 : la référence de base et les autres options
Section intitulée « Partie 4 : la référence de base et les autres options »La référence de base
Section intitulée « La référence de base »La référence de base reprend la conception du cours pour un locataire, avec les chiffres du cours. C’est ce que Niko obtiendrait en copiant le cours. Chaque conception reçoit une même mesure : le coût mensuel pour la charge de travail de base de Fernhollow. Cela représente 13 050 questions par mois, avec la même liste de prix. Le seuil de qualité est le résultat mesuré dans le cours, qui provient d’un autre ensemble de questions.
| Version | Valeurs de la collection | Coût mensuel de base |
|---|---|---|
| Référence de base : la conception et les chiffres du cours | Les 36 documents courts de Larkfield | 47,04 $ US |
+ les nombres de cette collection dans demand.toml |
628 documents, 3 902 mots chacun | 47,05 $ US |
+ corpus.toml (segments, taille de la requête) |
les valeurs propres à cette collection | 48,31 $ US |
Ce que cela nous apprend. Remplacer 36 documents courts par 628 documents longs a changé la facture d’un cent. Les segments plus longs l’ont augmentée de 3 % : les jetons de réponse sont passés de 2,01 $ US à 3,25 $ US par mois. La réplique de l’API toujours active et le serveur de base de données représentent la majeure partie du coût. La taille de la collection pose donc une question de temps, de quota et de défaillance, pas d’argent.
Les autres options, selon une même mesure
Section intitulée « Les autres options, selon une même mesure »python -m costmodel optionsModel routing: the same 67 questions, the same search results (measured), base workload (cost model) design correct US$/question p50 s p95 s US$/month chat-small only 86.6% 0.000277 1.52 3.79 48.31 chat-strong only 85.8% 0.005309 2.48 6.56 108.59 routed (small first) 86.6% 0.001346 1.76 4.02 61.13Cheapest design with the best measured quality: chat-small onlyLa colonne « correct » reprend le résultat de Routage entre modèles sur les 67 questions du cours RAG concernant les politiques de magasins. Ce n’est pas une mesure sur les documents d’OSHA. Les colonnes de coûts concernent cette collection : la requête plus longue rend chaque réponse plus chère que dans le cours.
La troisième idée de Niko ne demande aucune exécution, seulement du calcul. La collection entière contient 3 710 587 jetons. Le quota de chat-small est de 100 000 jetons par minute. Donc, une question utiliserait 37 minutes de quota. Supposons que le fournisseur facture chaque jeton au prix des entrées en cache (0,01 $ US par million, selon la liste de prix). Une question coûterait alors 0,037 $ US. Pour les 11 745 questions mensuelles qui atteignent le modèle, cela représente 435,81 $ US en jetons seulement. Dans Cache et traitement par lots, le cache du fournisseur économisait de l’argent sur une longue requête, pas du temps.
| Conception | Coût mensuel de base | Données sur la qualité | Respecte les limites? |
|---|---|---|---|
| Collection entière dans chaque requête | environ 481 $ US (435,81 $ US de jetons + le reste) | aucune | non : 37 minutes de quota par question |
| chat-strong pour chaque réponse | 108,59 $ US | 85,8 % (autre ensemble de questions) | oui |
| Routage, chat-small d’abord | 61,13 $ US | 86,6 % (autre ensemble de questions) | oui |
| chat-small seulement, cache de réponses partagé | 48,31 $ US | 86,6 % (autre ensemble de questions) | oui, jusqu’au scénario élevé (partie 7) |
Ce que cela nous apprend. Selon les données disponibles, chat-small offre la conception la moins chère et la meilleure qualité mesurée. Mais ces données sont faibles pour cette collection. La recommandation comprend donc une mesure avant le lancement, pas après.
Le cache : une réponse publique n’a pas de propriétaire
Section intitulée « Le cache : une réponse publique n’a pas de propriétaire »Dans le cours, chaque clé de cache contenait le locataire, car les réponses de Larkfield ne doivent jamais atteindre Bramble Books. Les réponses de Fernhollow sont publiques : chaque visiteur peut voir chaque réponse. Donc, une entrée de cache peut servir à tout le monde, et le taux de succès peut dépasser celui du cours. Cela reste une hypothèse (0 %, 10 % ou 30 %).
Le danger vient du temps, pas des personnes. Environ dix nouveaux documents arrivent chaque mois, dont certaines corrections. Par exemple, « Hazard Communication Standard; Corrections » en janvier 2026. La clé contient donc la version de la collection : le numéro du dernier document chargé. Un nouveau document renouvelle toutes les clés, comme la version des données dans Clés et invalidation. Le reste de la sortie de options chiffre le coût du cache :
Caching answers: the hit share is an ASSUMPTION; the time saved per hit is measured a miss takes 2.18 s (embed + search + answer, medians); a hit takes 0.014 s hit share US$/month saved median wait s 0% 48.68 0.00 2.18 10% 48.31 0.37 2.18 30% 47.58 1.10 2.18 50% 46.84 1.84 2.18 The median wait does not change until more than half of the questions are hits.Ce que cela nous apprend. Le cache économise environ un dollar par mois : 93 % du coût est fixe. Sa valeur concerne le quota : un succès du cache évite tout appel au modèle de conversation. La partie 7 montre pourquoi cela compte.
Partie 5 : les décisions
Section intitulée « Partie 5 : les décisions »Trois décisions changent la conception. Chacune reçoit donc une fiche de décision d’architecture (ADR) tirée de decisions/template-adr.md, comme dans Décisions d’architecture. Copiez le modèle trois fois et remplissez chaque section :
- ADR-0001 : un serveur PostgreSQL contient toute la collection; chargez-la une fois avant le lancement. Les 90,4 Mo représentent 0,3 % du plus petit stockage. Un service de base de données vectorielle ajouterait donc inutilement un service à sécuriser et à sauvegarder. Chargez la collection avant le lancement à 70 % du quota de plongement (environ 56 minutes). Les questions de test pourront ainsi toujours obtenir leurs plongements. Réexaminez à 80 % du stockage, si le p95 de recherche dépasse 100 ms, ou si la collection décuple.
- ADR-0002 : chat-small répond avec cinq passages; aucun routage avant que cette collection ait son propre ensemble de questions. Une partie de la fiche figure ci-dessous.
- ADR-0003 : un cache de réponses partagé, avec une clé contenant la question et la version de la collection. Aucun visiteur dans la clé, car les réponses sont publiques. Réexaminez si le taux de succès mesuré dépasse 30 % (prévoyez-le) ou reste sous 5 % (retirez le cache).
## Decision
Option 1. Before launch, Aisha writes 50 questions with their answers from OSHA's documents, and we run the course's routing comparison on them.
## Revisit when
- the 50-question set shows chat-strong at least 5 points better than chat-small, or- the busiest minute uses 70% of the token quota: first ask the provider for a higher quota; then try three passages (about 1,475 tokens a prompt, an estimate) and check the quality on the question set.Le projet terminé contient les trois fiches complètes, avec leurs options et leurs conséquences.
Erreur courante
Une ADR qui cite un chiffre d'un autre ensemble de questions comme s'il provenait de celui-ci
Une première version d’ADR-0002 disait : « chat-small donne 86,6 % de réponses correctes sur nos documents. » Aisha a demandé : « Quels documents? » Le chiffre est réel, mais il a été mesuré sur des politiques de magasins, pas sur les règles d’OSHA. Un lecteur qui s’y fie saute l’ensemble de questions. La première mesure sur un texte juridique se fait alors en production. Correction : indiquez la source de chaque chiffre mesuré (« sur un autre ensemble de questions »). Faites de la mesure manquante une étape de la décision. Ici, l’ensemble de 50 questions vient avant le lancement.
Partie 6 : le tableau des défaillances
Section intitulée « Partie 6 : le tableau des défaillances »Un service public sans connexion présente des défaillances absentes de la conception du cours. Dessinez-les sur la conception avant de rédiger le tableau :
Description textuelle du diagramme
Les visiteurs accèdent à l’API sans se connecter. L’API utilise le fournisseur de modèles et un serveur PostgreSQL. Un processus charge les nouveaux documents du Federal Register. Chaque défaillance du tableau ci-dessous, de F1 à F6, apparaît sur la partie qu’elle touche.
Le tableau dans decisions/failure-modes.md contient une ligne par défaillance. Il reprend les colonnes de Scénarios de défaillance et ajoute les objectifs de reprise :
| ID | Défaillance | Signal de détection | Responsable | RTO | RPO |
|---|---|---|---|---|---|
| F1 | Panne du fournisseur ou 429 | 5xx et 429 > 5 % sur 5 minutes | Niko | au retour du fournisseur; notre message dans les 15 minutes | aucun |
| F2 | Les robots épuisent le quota et le budget | questions par visiteur par heure; dépenses quotidiennes > budget / 30 | Niko | 60 minutes (bloquer, plafonner) | aucun |
| F3 | Une nouvelle règle ou correction non chargée | chaque jour : nombre d’OSHA dans l’API comparé au nôtre | Aisha | 1 jour | aucun : la source la conserve |
| F4 | La proposition de 376 pages échoue à mi-chemin | une tâche dépasse son bail; segments stockés ≠ attendus | Niko | environ 5 minutes pour ce document | aucun |
| F5 | Perte de la base de données | alerte de disponibilité | Niko | environ 70 minutes (estimation) | 5 minutes du journal des questions (hypothèse); documents : aucun |
| F6 | Une réponse interprétée comme un conseil juridique | bouton « this answer is wrong » (cette réponse est erronée); 20 réponses révisées par semaine | Lena | entrée de cache supprimée dans un délai d’un jour ouvrable | aucun |
Le fichier du projet contient aussi chaque mesure d’atténuation. Deux lignes demandent des chiffres :
- F4. Le plus grand document contient 1 543 segments : 16 appels de 100, et 484 968 jetons. À 100 000 jetons par minute, il exige à lui seul environ 5 minutes de quota. Une transaction par document signifie qu’une défaillance laisse l’ancien état, jamais un demi-document.
- F5. Lena vise un RTO de 8 heures et un RPO d’un jour pour le journal des questions. C’est une hypothèse : un service gratuit, sans contrat. Exécutez la commande de reprise du cours :
python -m costmodel recoveryRecovery (base): targets RTO 480 min, RPO 1440 min; database 184 MB restores in about 4.6 s (measured rate, a laptop) plan RPO min RTO min meets both? nightly dump to file storage 1,440 70 yes managed point-in-time restore 5 70 yesMost of the recovery time is people and a new server, not copying data. Test the restore to know.Ce que cela nous apprend. Les deux plans respectent les objectifs de Lena. Cette collection offre aussi une voie de reprise que celle de Larkfield n’a pas : les documents sont publics. Si toutes les sauvegardes échouaient, corpus get et un nouveau chargement reconstruiraient la collection en environ une heure. Seul le journal des questions serait perdu.
Partie 7 : le coût par locataire et la première limite
Section intitulée « Partie 7 : le coût par locataire et la première limite »Fernhollow est le seul locataire. Le coût par locataire est donc le coût total :
python -m costmodel scenariosScenarios (US$ per month) low base high month 0 39.09 48.31 74.04 (1 tenants) per tenant 39.09 48.31 74.04 month 12 39.09 49.72 115.32 (1 tenants) per tenant 39.09 49.72 115.32python -m costmodel units ajoute le coût unitaire : 0,0037 $ US par question dans le scénario de base, tous coûts compris, dont 93 % fixes. Dans le scénario élevé, il tombe à 0,00078 $ US. Davantage de questions partagent les coûts fixes, comme dans Économie unitaire. Si Fernhollow rejoignait une plateforme partagée avec d’autres locataires, ils partageraient aussi la partie fixe.
Passons aux limites :
python -m costmodel growth --scenario high- Jetons
- Appels (pointillés)
- Le quota
Description textuelle du graphique
Dans le scénario élevé, la minute la plus chargée utilise 127% du quota de jetons au mois 0 et 399% au mois 12. Les appels commencent à 59% et dépassent le quota au mois 6. Le coût dépasse le budget de 100 $ US de Lena au mois 9 (100,26 $ US).
Ce que cela nous apprend. La première limite est le quota de jetons du fournisseur, dès le mois 0 du scénario élevé : 127 %. La conception de Larkfield dans le cours atteignait 114 % avec deux magasins. Ici, un seul locataire l’atteint, car chaque requête est deux fois plus longue. Trois leviers, dans l’ordre. D’abord, demandez au fournisseur un quota plus élevé avant toute publicité. Ensuite, laissez le cache répondre aux questions répétées. Enfin, essayez trois passages plutôt que cinq (environ 1 475 jetons, une estimation), après avoir mesuré la qualité.
Partie 8 : les nouveaux documents, de bout en bout
Section intitulée « Partie 8 : les nouveaux documents, de bout en bout »Le plan prévoit environ 10,5 nouveaux documents par mois, de la taille moyenne de la collection. Les données de 2026 sont de nouvelles entrées que le plan n’a jamais vues :
python -m corpus newChecked osha-fr-2026-new.jsonl.gz: SHA-256 3ee6af82c139... is correctNew documents: 83 from 2026-01 to 2026-09 (9.2 a month) 239 pages, 132,766 words, 850 chunks, 216,557 tokens to embed embedding US$0.0043; database +5.1 MB largest: 2026-10735 (Notice, 11 pages, 14,958 tokens)Ce que cela nous apprend. Neuf mois de nouveaux documents coûtent moins d’un demi-cent en plongements et ajoutent 5 Mo. Le rythme, 9,2 par mois, est proche des 10,5 du plan. Les documents étaient plus petits que la moyenne prévue (1 600 mots, pas 3 902). La moyenne comprend en effet les règles géantes de 2021 à 2024. Le plan était donc prudent. Un document de janvier corrigeait la règle d’étiquetage de 2024. La version de la collection dans la clé du cache (ADR-0003) et la vérification quotidienne (F3) existent précisément pour ce cas.
Vérifier la revue
Section intitulée « Vérifier la revue »Remplissez review.md à partir du modèle : le service et ses objectifs, le dimensionnement, la recommandation, le coût par locataire, les hypothèses et les risques. Nommez l’hypothèse qui changerait la recommandation. Exécutez ensuite la vérification de la revue :
python -m costmodel check PASS demand: every value has evidence (verified or assumed) PASS prices: every price has its source PASS measured: every value names its run PASS corpus: the calculator uses this collection's own numbers PASS decisions: 2 or more ADRs with status, context, options, decision, consequences, revisit PASS failures: at least 5, each with owner, mitigation, signal, RTO and RPO PASS review: recommendation, cost per tenant, assumptions, risks and an unresolved assumptionDesign review check: 7 of 7 passedLa vérification reprend celle du dossier du cours, avec les règles de cette revue. Elle examine la forme de la revue, pas sa véracité : Lena la lit toujours. Le projet terminé ajoute un test qui exécute cette vérification. Sa commande python -m pytest -q affiche donc 13 passed (13 tests réussis).
Constats et limites
Section intitulée « Constats et limites »- Comptez avant de concevoir. « Des milliers de pages » semblait annoncer un problème de stockage. Après comptage, c’était 90 Mo : 0,3 % de la plus petite base de données.
- La moyenne cache le risque. Le document médian compte 2 pages; le plus grand en compte 376. Le temps de chargement, les nouvelles tentatives et une ligne de défaillance concernent ce seul document.
- La collection change les requêtes, et les requêtes changent le quota. Les segments plus longs ont doublé la taille de chaque requête de réponse par rapport au cours. Le coût a changé de 3 %; le quota de jetons est devenu la première limite.
- Limites de cette revue. La demande est supposée. La requête de réponse est une estimation à partir de parties mesurées, comptées avec le segmenteur en jetons du modèle de plongement. Celui de chat-small en compte environ 1,5 % de moins. Le temps d’accès au cache vient du cours de mise à l’échelle. Tous les temps ont été mesurés sur un seul ordinateur, un seul après-midi. Le calculateur facture toujours un résumé pour chaque nouveau document, même si le Federal Register en fournit un (moins d’un cent par mois). Windows et Linux ne sont pas testés.
Utilisation responsable
Section intitulée « Utilisation responsable »- Pas de conseils juridiques. Le Federal Register consigne les règles lors de leur création, de leur proposition et de leur correction. Les règles en vigueur se trouvent dans le Code of Federal Regulations. Chaque réponse montre ses documents, leurs dates et leurs types, et précise qu’une règle proposée n’est pas en vigueur.
- Refuser plutôt que deviner. Lorsqu’aucun passage n’appuie une réponse, le service le dit et donne le numéro de téléphone de Fernhollow.
- Des personnes dans les documents publics. Les documents nomment des responsables et donnent leurs numéros de téléphone. N’extrayez pas les coordonnées, ne les republiez pas et excluez-les des réponses.
- Une page publique est une porte ouverte. Limitez les questions par visiteur et plafonnez les dépenses quotidiennes avant d’annoncer la page.
- Respectez la source. Vérifiez l’API du Federal Register une fois par jour, une requête à la fois. Ne rechargez pas les 628 documents à chaque test : utilisez la copie fixe.
En faire un projet de portfolio
Section intitulée « En faire un projet de portfolio »Ce projet montre ce que les employeurs recherchent chez un architecte de solutions. Une conception dimensionnée par comptage, des coûts avec leurs hypothèses et des décisions qui précisent quand les réexaminer.
Quoi mettre dans le dépôt :
open-docs-review/ README.md what it is, the commands, the three kinds of numbers review.md the one-page review: recommendation, cost per tenant, risks DATASET.md the source, the licence, the checksums, the limits decisions/ ADR-0001 to 0003, failure-modes.md demand.toml demand with its evidence corpus.toml this collection's measured values (written by corpus write) corpus/ download, cleaning, chunks, token counts, storage, ingestion costmodel/ the course's calculator, reading corpus.toml tests/ 13 tests, one of them the review's check- Créez un dépôt Git à partir de votre dossier et poussez-le vers GitHub.
.gitignoreexclut les données et l’environnement virtuel. - Placez le tableau de dimensionnement et la fourchette de coûts de
review.mden haut du README. - Décrivez-le en deux phrases : « J’ai révisé un service public de questions portant sur 628 documents gouvernementaux. Le comptage des jetons a montré que le stockage était minime et que le quota de jetons était la première limite. J’ai recommandé le petit modèle, un cache partagé et un test de qualité avant le lancement. »
Aller plus loin. Dimensionnez les documents d’un autre organisme avec les mêmes scripts et comparez leurs profils. Rédigez les 50 questions d’Aisha et exécutez la comparaison de routage du cours sur ces questions. Ajoutez un deuxième locataire et observez la baisse du coût par locataire.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
La collection est passée de 36 documents courts à 628 documents longs. Pourtant, le coût mensuel n'a augmenté que d'un cent. Ensuite, corpus.toml l'a augmenté d'environ 3 %. Pourquoi le deuxième changement a-t-il eu plus d'effet que le premier?
Afficher la réponse
Les documents influencent le coût seulement par l’ingestion et le stockage. Charger de nouveaux documents coûte des fractions de cent par mois. La base de données reste bien en dessous de sa taille minimale de 32 Go. corpus.toml a changé le coût de chaque réponse. Les segments de cette collection sont environ cinq fois plus longs. Une requête avec cinq passages contient donc environ 2 002 jetons, et non 946. Le service produit des milliers de réponses par mois. La majeure partie du coût reste fixe, donc le total n’a augmenté que de 3 %. Mais la requête plus longue a fait du quota de jetons la première limite.
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
Niko dit : « Le cours a mesuré un résultat de 86,6 % pour chat-small. Donc, on sait qu'il fonctionne pour les règles d'OSHA. » Que répondez-vous, et que consignez-vous dans le registre des décisions?
Afficher la réponse
Le résultat de 86,6 % est réel. Mais il a été mesuré sur les politiques de magasins du cours RAG : créer une IA qui utilise vos données. Il s’agissait d’un autre ensemble de questions. Des textes juridiques avec de longs passages et des renvois peuvent donner un résultat différent. La décision peut quand même être de choisir chat-small. C’est la conception la moins chère qui offre la meilleure qualité mesurée. Mais le registre doit indiquer d’où vient le chiffre. Il doit aussi prévoir une étape pour obtenir la mesure manquante : tester les 50 questions d’Aisha sur les documents d’OSHA avant le lancement. Le déclencheur de révision : un résultat de chat-strong supérieur d’au moins 5 points.
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
Dans le cours, la clé du cache de réponses contenait le locataire. Dans cette revue, elle contient plutôt la version de la collection. Pourquoi ces deux choix, et quel problème survient si la version manque?
Afficher la réponse
Dans le cours, les réponses appartiennent à un locataire. Sans le locataire dans la clé, un magasin pourrait voir une réponse privée d’un autre magasin. Les réponses de Fernhollow sont publiques, donc tous les visiteurs peuvent partager une entrée. Mais les documents changent : une nouvelle règle ou une correction peut rendre une ancienne réponse incorrecte. Avec la version de la collection dans la clé, la première question après un chargement ne trouve aucune entrée. Le service construit alors la réponse à partir des nouveaux documents. Sans cette version, le cache pourrait continuer à citer un texte remplacé par une correction, jusqu’à l’expiration de l’entrée.
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 vérifié les données et retiré leur balisage de page Web (8,8 % des caractères) avant le comptage.
- Vous avez compté les jetons avec le même outil de segmentation en jetons que celui utilisé pour la facturation : 3 710 587 pour 628 documents. L’estimation était trop basse de 2 % au total. Un document contenait 65 % plus de jetons que prévu.
- Le stockage occupait 90 Mo, soit 0,3 % de la plus petite base de données. Le chargement complet coûte 0,08 $ US et prend au moins 39 minutes, à cause du quota de plongements.
- chat-small et un cache partagé coûtent 48,31 $ US par mois dans le scénario de base (de 39,09 $ US à 74,04 $ US). La part fixe représente 93 % du coût. Inclure toute la collection dans chaque requête demanderait 37 minutes de quota par question.
- Vous avez rédigé trois ADR et décrit six défaillances avec leurs responsables, RTO et RPO. La première limite est le quota de jetons de chat-small. La principale hypothèse non vérifiée est la qualité des réponses sur les documents d’OSHA.
Ensuite, le travail final : rédigez votre propre proposition d’architecture et de coûts pour un petit assistant documentaire multilocataire.
Leçon suivante : Travail final