Aller au contenu
English

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.

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.

Étude de casPièce de portfolio

Durée
Environ 3 heures
S’exécute dans
VS Code, Python 3.12+
Compétences utilisées
  • Compter les jetons avec un outil de segmentation en jetons
  • Dimensionner le stockage et l'ingestion
  • Coût par locataire avec le calculateur
  • Routage et cache à partir de faits mesurés
  • Fiches de décision d'architecture
  • Tableau des défaillances avec RTO et RPO

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 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 mainEnviron 180 minutes

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. tiktoken té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.

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 :

  1. « Il y a des milliers de pages. Il nous faut un service de base de données vectorielle. »
  2. « Les textes juridiques sont difficiles. Utilisons le modèle puissant pour chaque réponse. »
  3. « 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.

Un flux de gauche à droite. La collection, les documents de l'OSHA dans le Federal Register de 2021 à 2025, passe à l'étape 1, Mesurer la taille : documents, pages, mots, jetons comptés avec un outil de segmentation et segments. L'étape 1 alimente l'étape 2, stockage et ingestion, ainsi que le fichier corpus.toml contenant les nombres de cette collection. corpus.toml passe à l'étape 3, le calculateur, avec demand.toml et design.toml, qui donne le coût, les scénarios et les options. Les faits mesurés du cours, tirés d'un autre ensemble de questions, alimentent aussi l'étape 3. Les étapes 2 et 3 alimentent l'étape 4, les décisions ADR-0001 à 0003. L'étape 4 mène à l'étape 5, le tableau des défaillances avec responsables, RTO et RPO, puis à review.md pour Lena.
Le parcours de la revue. Vos propres comptes remplacent les nombres du cours quand la collection les modifie. Les faits mesurés du cours fournissent le reste.
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

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.

  1. 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.

  2. 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).

  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

    L’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.

  4. Téléchargez les documents et vérifiez-les :

    Fenêtre de terminal
    python -m corpus get
    Sortie
    Downloading https://github.com/Nextia-Intelligence/nextia-learning-labs/raw/main/C26/M07-L02-design-review/data/osha-fr-2021-2025.jsonl.gz
    Checked osha-fr-2021-2025.jsonl.gz: SHA-256 81b47f96634a... is correct
    Downloading https://github.com/Nextia-Intelligence/nextia-learning-labs/raw/main/C26/M07-L02-design-review/data/osha-fr-2026-new.jsonl.gz
    Checked osha-fr-2026-new.jsonl.gz: SHA-256 3ee6af82c139... is correct
  5. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q
    Sortie (fin)
    FAILED tests/test_corpus.py::test_tokens_are_counted_with_the_tokenizer_not_guessed
    1 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.

Avant de dimensionner quoi que ce soit, vérifiez que les données correspondent à vos attentes :

Fenêtre de terminal
python -m corpus check
Sortie
Checked osha-fr-2021-2025.jsonl.gz: SHA-256 81b47f96634a... is correct
Documents: 628; types: Notice 517, Proposed Rule 72, Rule 39
Published: 2021-01-11 to 2025-12-31
Without text: 0; repeated document numbers: 0; without a page count: 0
Raw 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 comme LD<INF>50</INF>. Le balisage représentait 8,8 % des caractères. corpus/load.py le retire avant tout comptage. Sans cette étape, chaque compte ci-dessous serait trop élevé d’environ un dixième.

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 :

Deux exemples découpés en jetons par l'outil de segmentation cl100k_base. En haut, en vert : « Guardrails are 42 inches high. » (les garde-corps ont une hauteur de 42 pouces), 5 mots, devient 8 jetons : Guard, rails, are, une espace, 42, inches, high et le point. En bas, en rouge : « 29 CFR 1910.134(c)(2)(ii) », 3 mots, devient 13 jetons : 29, CFR, une espace, 191, 0, un point, 134, (c, )(, 2, )(, ii, ). Les deux mènent à la même conclusion : la facture compte les jetons, pas les mots; les références juridiques coûtent plus de jetons par mot.
Découpages réels par l'outil de segmentation cl100k_base. Les mots ordinaires représentent environ un ou deux jetons. Une référence juridique dépasse quatre jetons par mot.
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.

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.

Exécutez d’abord le calcul de taille avec l’estimation :

Fenêtre de terminal
python -m corpus size
Output (start)
Collection: 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 :

corpus/size.py (part)
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 :

Fenêtre de terminal
python -m corpus size
python -m pytest -q
Output (start of the sizing, end of the tests)
Collection: 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.07s
Jetons par mot pour chacun des 626 documents contenant au moins 200 mots, comptés avec cl100k_base. La plupart des documents sont proches de l'estimation. Quelques-uns, remplis de nombres et de références, atteignent 2,44.
Description 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.

Le reste de la sortie du calcul de taille :

Output of python -m corpus size (rest)
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 tokens
Storage: 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 min
New documents per month (60 months): low 0, median 10, mean 10.5, high 37

Chaque ligne multiplie un compte par une valeur mesurée ou un prix :

  • Segments. corpus/chunk.py conserve 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é).
Jetons par document, comptés avec cl100k_base : les trois plus grands, les sept suivants et les 618 autres. Les 10 plus grands documents contiennent 49 % des jetons de la collection. Le plus grand est à lui seul une proposition de 376 pages.
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.

Deux fichiers renseignent le calculateur sur la collection :

  1. Ouvrez demand.toml. Le projet de départ contient encore les valeurs de la collection Larkfield du cours, marquées TODO (à faire). Remplacez-les par vos comptes et changez leur preuve pour verified: (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).

  2. Écrivez les valeurs mesurées de cette collection pour le calculateur :

    Fenêtre de terminal
    python -m corpus write
    Sortie
    Checked osha-fr-2021-2025.jsonl.gz: SHA-256 81b47f96634a... is correct
    ingest_embed_tokens_per_word 1.61 tokens per word
    chunks_per_1000_words 6.11 chunks
    chunk_text_bytes_per_word 7.57 bytes per word
    document_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 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.

Fenêtre de terminal
python -m costmodel options
Output (start)
Model 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.13
Cheapest design with the best measured quality: chat-small only

La 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 :

Output of python -m costmodel options (caching)
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.

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).
decisions/adr-0002-chat-small-with-five-passages.md (Decision and Revisit when)
## 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.

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 :

La conception avec ses points de défaillance. Sans se connecter, les visiteurs envoient leurs questions à l'API. Celle-ci comporte une réplique, une limite de débit par visiteur et un cache de réponses. L'API appelle le fournisseur de modèles (embed-small, chat-small) et PostgreSQL B1ms (segments, vecteurs, cache, journal des questions). L'API du Federal Register, la source, envoie les nouveaux documents au processus d'ingestion après une vérification quotidienne. Ce processus crée les plongements par lots de 100 segments et écrit une transaction par document. Une ligne pointillée relie chaque défaillance à la partie touchée : F1, panne ou 429 chez le fournisseur de modèles; F2, robots et abus chez les visiteurs et l'API; F3, nouvelle règle non chargée à la source; F4, règle de 400 pages échouant à mi-chemin dans le processus; F5, perte de la base de données; F6, réponse interprétée comme un conseil juridique.
Les six défaillances sur la conception. F2 et F6 existent parce que le service est public. F3 et F4 existent parce que la source change et que certains documents sont énormes.
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 :
Fenêtre de terminal
python -m costmodel recovery
Sortie
Recovery (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 yes
Most 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 :

Fenêtre de terminal
python -m costmodel scenarios
Sortie
Scenarios (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.32

python -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 :

Fenêtre de terminal
python -m costmodel growth --scenario high
  • Jetons
  • Appels (pointillés)
  • Le quota
La minute la plus chargée du scénario élevé comparée au quota de chat-small : 100 000 jetons et 100 appels par minute. Les jetons dépassent le quota au mois 0; les appels le dépassent au mois 6.
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é.

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 :

Fenêtre de terminal
python -m corpus new
Sortie
Checked osha-fr-2026-new.jsonl.gz: SHA-256 3ee6af82c139... is correct
New 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.

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 :

Fenêtre de terminal
python -m costmodel check
Sortie
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 assumption
Design review check: 7 of 7 passed

La 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).

  • 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.
  • 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.

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
  1. Créez un dépôt Git à partir de votre dossier et poussez-le vers GitHub. .gitignore exclut les données et l’environnement virtuel.
  2. Placez le tableau de dimensionnement et la fourchette de coûts de review.md en haut du README.
  3. 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é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.

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.

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.

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