Aller au contenu
English

Architecture et contrats

  • Leçon 6
  • 90 min
  • Module 2 : Préparer les données et l'architecture

Où nous en sommes

Dans la leçon précédente, nous avons préparé un ensemble de données avec des difficultés voulues. Avant de construire, nous devons décider comment les parties communiquent et ce qu'elles stockent. Des parties construites sans entente écrite ne s'emboîtent pas, et la boutique se perd entre elles. Dans cette leçon, nous écrivons d'abord les contrats, comme le bon de commande entre un serveur et un cuisinier.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Décrivez comment les parties de votre produit communiquent et ce qu’elles stockent, avant de les construire. Des parties construites selon un même accord écrit s’assemblent bien. L’identité de la boutique ne se perd jamais entre elles.

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

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Docker Desktop, en cours d’exécution. L’image de la base de données occupe environ 690 Mo sur disque et se télécharge une seule fois.
  • Le port 5432 libre sur votre ordinateur. Si une autre instance PostgreSQL l’utilise, l’exercice guidé indique quoi changer.

Aucun compte et aucune clé. Rien n’appelle un modèle.

Testé avec Python 3.12.13, Docker Engine 29.6.1 et PostgreSQL 18.6 avec pgvector 0.8.7, sur macOS (Apple silicon). Les commandes Windows (PowerShell) et Linux sont fournies, mais n’ont pas été testées.

Dans un restaurant achalandé, le serveur et le cuisinier se parlent rarement. Le bon de commande communique pour eux. Il indique le numéro de table, les plats et des notes comme « sans noix ». Le serveur sait quoi écrire, et le cuisinier sait quoi lire. Deux nouveaux employés peuvent commencer lundi sans se rencontrer, car le bon est le même pour tous.

Si le bon n’indique aucun numéro de table, le cuisinier prépare quand même le repas, et celui-ci reste bon. Le repas arrive à la mauvaise table. Personne ne le remarque avant qu’un client se plaigne.

Le problème : des parties construites séparément ne s’assemblent pas

Section intitulée « Le problème : des parties construites séparément ne s’assemblent pas »

Sam construira le produit par parties dans les trois prochains modules : l’API, la page, le processus d’ingestion, la recherche et la réponse. Différents réviseurs reçoivent différentes parties à des jours différents. Tomás veut sauter la conception : « On verra ce que chaque partie demande quand on l’écrira. »

Voici ce qui arrive sans accords écrits. Les cours précédents ont mesuré ces défaillances, ou cet ensemble de données les rend inévitables :

  • La clé perd l’identité de la boutique. Le fichier gift-cards.md de Bramble et le fichier gift-cards.md de Larkfield partagent la clé de document gift-cards. Le cours RAG construisait les identifiants de segments à partir de la clé du document, de la version et de la position. Cela convenait pour une seule boutique. Avec deux boutiques, le même fichier téléversé par chacune aurait les mêmes identifiants de segments. Le deuxième téléversement entrerait en conflit avec le premier ou, pire, le remplacerait.
  • Deux modèles de plongement mélangés. Le cours RAG interrogeait son index e5 avec des vecteurs de questions provenant d’un autre modèle de même taille. Les deux avaient 384 nombres, donc rien n’échouait. Le taux de réussite est tombé à 0,068 : presque chaque recherche renvoyait les mauvais passages, sans message d’erreur.
  • La mauvaise version. Dans le même cours, sans filtre de date, 5 passages d’une version expirée se retrouvaient parmi les 5 premiers résultats.
  • La page et l’API ne s’entendent pas. La page attend une réponse au téléversement. L’API répond immédiatement et indexe plus tard. La page affiche « terminé » pour un document dont le traitement échoue ensuite.

Aucun de ces bogues n’est difficile à corriger. Chacun coûte cher à trouver plus tard, car rien ne plante.

Un contrat est un accord écrit à la frontière entre deux parties. Il précise ce qu’une partie envoie et ce que l’autre renvoie. Il indique aussi les erreurs possibles et qui peut faire une demande. C’est le bon de commande. Chaque côté peut être construit et testé séparément selon ce contrat.

La conception de Sam comprend quatre contrats, un pour chaque endroit où les parties se rencontrent :

  1. Le contrat de l’API (entre la page et l’API) : méthodes, chemins, formats des requêtes et réponses, codes d’erreur et rôles autorisés.
  2. Le schéma de base de données (entre le code et ses données) : tables, clés et règles appliquées par la base de données elle-même.
  3. Les états d’ingestion (entre le téléversement et le processus) : les états possibles d’un document et ce qui déclenche chaque transition.
  4. Les métadonnées de récupération (entre l’index et la recherche) : les faits que chaque segment conserve et les filtres qui les utilisent.

Un contrat n’est pas du code. C’est une page du dossier de conception, docs/design-pack/architecture.md, que les réviseurs lisent avant que le code existe. Kwame, l’architecte de solutions, révise les parties et l’API. Mei, l’ingénieure de données, révise l’ingestion et la suppression.

Commencez par le plus petit contrat : l’identifiant d’un segment. La première section du fichier gift-cards.md de Bramble est Amounts (montants). Après l’analyse, elle s’étend du caractère 12 au caractère 79 du texte du document. Supposons que les deux boutiques téléversent le même fichier. L’outil de découpage du projet construira ensuite l’identifiant à partir de ces valeurs, dans cet ordre :

Boutique Le texte soumis au hachage Les 12 premiers caractères de son SHA-256
(aucune, selon la règle du cours RAG) gift-cards|1|12|79 987c93cee1ea, pour les deux boutiques
Bramble Books bramble|gift-cards|1|12|79 a1e046fa0990
Larkfield larkfield|gift-cards|1|12|79 eaef0328d7a2

Vous pouvez vérifier une ligne vous-même :

Fenêtre de terminal
python -c "import hashlib; print(hashlib.sha256(b'larkfield|gift-cards|1|12|79').hexdigest()[:12])"
eaef0328d7a2

Sans la boutique, les deux téléversements obtiennent 987c93cee1ea. Avec elle, les identifiants diffèrent. Un segment ne peut jamais être confondu avec celui de l’autre boutique. Le schéma répète ensuite la règle : la clé primaire d’un segment est (tenant_id, chunk_id). La clé qui relie un segment à son document inclut aussi la boutique :

FOREIGN KEY (tenant_id, document_id) REFERENCES documents (tenant_id, document_id) ON DELETE CASCADE

La base de données refuse donc un segment de Bramble qui pointe vers un document de Larkfield, même si le code contient un bogue. Un des nouveaux tests le prouve. Le contrat tient en trois lignes de conception et élimine toute une catégorie de défaillances.

Sam garde l’architecture aussi petite que le permettent les critères d’acceptation. Un seul processus API fait tout : il sert la page, répond aux questions et exécute le processus d’ingestion dans un fil d’exécution en arrière-plan. Une base PostgreSQL avec l’extension pgvector stocke les documents, fichiers, segments, vecteurs et réponses de toutes les boutiques. Un adaptateur donne accès au fournisseur de modèles. Par défaut, il rejoue des réponses enregistrées.

À gauche, le navigateur affiche une page simple pour le téléversement, le statut, les questions et les preuves. Une flèche portant les mentions POST /documents 202, GET /documents/{id}, POST /answers 200 entre dans le processus API (FastAPI), sur votre ordinateur. Dans le processus API : les routes, qui vérifient la requête, l'appelant et l'adhésion; le pipeline de réponse, qui récupère, assemble, génère, vérifie et stocke; le processus d'ingestion, un fil d'exécution qui analyse, découpe et produit des plongements; les modèles locaux sur le processeur, pour les plongements e5-small. Une flèche pointillée relie les routes au processus d'ingestion : une ligne de documents représente la tâche. Le pipeline de réponse interroge PostgreSQL selon la boutique, l'accès, la date et le modèle. Le processus prend une tâche en charge et sauvegarde les segments. PostgreSQL avec pgvector contient les lignes de Larkfield et de Bramble Books, séparées par une ligne : tenant_id sur chaque ligne, sécurité au niveau des lignes. Le pipeline de réponse envoie seulement la question et les passages au fournisseur de modèles, hors de votre ordinateur. Celui-ci fournit des réponses enregistrées par défaut ou utilise un point de terminaison en direct. Le fournisseur d'identité d'exercice, du module 4, fournit ses clés publiques aux routes.
Les parties de Sam et les contrats qui les relient. Un processus, une base de données avec un espace par boutique et un fournisseur de modèles qui ne voit que la question et les passages.
Description textuelle du diagramme

Le navigateur affiche une page simple. Il communique seulement avec l’API : il téléverse un document (202 Accepted, accepté), demande son statut et envoie une question (200 avec la réponse). Dans le processus API, les routes vérifient la requête, l’appelant et l’adhésion. Elles appellent ensuite le pipeline de réponse ou créent une ligne de document. Cette ligne représente la tâche d’ingestion. Le fil d’exécution la prend en charge, analyse et découpe le document, puis produit ses plongements avec le modèle e5 local. Il sauvegarde ensuite les segments. Le pipeline de réponse interroge PostgreSQL avec quatre filtres : la boutique, le niveau d’accès, la date et le modèle de plongement. Chaque ligne de PostgreSQL contient un tenant_id. La sécurité au niveau des lignes, ajoutée au module 4, sépare les boutiques une deuxième fois. Seuls la question et les passages vont au fournisseur de modèles. Le fournisseur d’identité d’exercice arrive au module 4.

Chaque partie a une seule tâche et une chose qu’elle ne doit jamais faire. La deuxième colonne est la partie du contrat que les réviseurs vérifient le plus :

Partie Sa seule tâche Elle ne doit jamais
Page permettre à un membre de téléverser, suivre le statut, poser une question et lire les preuves afficher le texte du serveur comme du HTML; conserver un jeton
Routes vérifier la requête, l’appelant et son adhésion; appeler un service faire confiance à une boutique ou à un rôle envoyé par le navigateur
Pipeline de réponse transformer une question en réponse stockée avec des citations chercher dans une autre boutique; envoyer autre chose que la question et les passages au modèle
Processus d’ingestion indexer les documents téléversés, un à la fois perdre un document : une défaillance se termine par failed (échec), avec une raison
PostgreSQL conserver les données de chaque boutique, séparées par tenant_id laisser une requête d’une boutique voir les lignes d’une autre
Fournisseur de modèles rédiger une réponse à partir des passages recevoir un document que l’appelant n’a pas le droit de lire

« Pourquoi pas une file de messages pour les tâches et une base de données vectorielle pour la recherche? » demande Tomás. Kwame lui retourne la question : quel critère d’acceptation en a besoin? Deux boutiques téléversent quelques documents par semaine. Une ligne de documents avec un statut constitue une file complète. Le processus la prend en charge avec FOR UPDATE SKIP LOCKED, comme dans le cours Mettre à l’échelle les API et les charges de travail d’IA. pgvector cherche parmi les 245 passages des deux boutiques en environ 9 ms, selon les mesures du module 3. Chaque système ajouté doit être démarré, sécurisé, sauvegardé et expliqué dans une démo. De plus, un deuxième stockage aurait besoin de sa propre copie de la règle des locataires. Sam consigne la décision, sa raison et le seuil qui justifierait de la changer.

Chaque chemin contenant des données de boutique commence par /v1/tenants/{tenant}. La boutique dans le chemin n’est qu’une demande : l’adhésion de l’appelant décide. Chaque erreur a le même format, {"code", "message", "request_id"}, comme dans le cours Créer et déployer votre première API. Voici quatre lignes de la table du contrat de Sam. La table complète se trouve dans docs/design-pack/architecture.md.

Méthode et chemin Qui peut l’appeler Réussite Erreurs
POST /v1/tenants/{t}/documents propriétaire, personnel 202 {document, duplicate: false} et un en-tête Location (emplacement) 401, 403, 404, 409 conflict (conflit), 413 file_too_large (fichier trop volumineux), 415 unsupported_file (fichier non pris en charge), 422
GET /v1/tenants/{t}/documents/{id} tous les membres 200 {document} avec status (statut) : uploaded (téléversé), parsing (analyse en cours), indexed (indexé) ou failed (et error, erreur) 401, 404
POST /v1/tenants/{t}/answers tous les membres 200 {answer} avec les affirmations, les citations, le coût et le temps 401, 404, 422, 504 provider_timeout (délai du fournisseur dépassé), et d’autres
GET /v1/tenants/{t}/chunks/{chunk_id} tous les membres, selon leur niveau d’accès 200 {chunk} : la preuve derrière une citation 401, 404

Deux choix dans cette table comptent plus tard. Un téléversement répond 202 Accepted, pas 200 : l’API a sauvegardé le fichier, mais l’indexation n’a pas commencé. La page doit donc demander le statut et afficher « indexation en cours » jusqu’à ce que le document soit indexed ou failed. L’API répond aussi 404 pour les données d’une autre boutique, jamais 403. Ainsi, une personne étrangère à la boutique ne peut pas savoir si un document existe.

Le schéma se trouve dans migrations/001_core.sql : sept tables. Chaque table contenant des données de boutique possède tenant_id, et chaque clé qui pointe vers une autre ligne l’inclut. La table documents contient les faits de l’inventaire de l’ensemble de données : doc_key, version, access, effective_from et effective_to. Elle stocke aussi sha256, l’empreinte du fichier, et embedder, le nom du modèle qui a produit ses vecteurs. UNIQUE (tenant_id, doc_key, version) permet la version 1 de returns-policy dans les deux boutiques. Cette contrainte refuse une deuxième copie dans la même boutique.

La base de données vérifie aussi les valeurs permises par le contrat. Une contrainte CHECK refuse tout statut hors des quatre états et tout niveau d’accès autre que public (public) et staff (personnel). Une faute de frappe dans le code ne peut donc pas inventer un cinquième état.

La ligne documents représente aussi la tâche d’ingestion. Il n’y a pas de table de tâches séparée. Son status passe par quatre états :

Un diagramme d'états. Début : téléversement accepté, 202, mène à uploaded (téléversé). Uploaded passe à parsing (analyse en cours) quand le processus prend la tâche en charge, avec un bail de 5 minutes. Parsing passe à indexed (indexé) quand le document est analysé, découpé, converti en plongements et sauvegardé dans une transaction. Parsing passe immédiatement à failed (échec) quand le fichier ne peut pas être analysé, avec la raison. Parsing retourne à uploaded après une autre erreur, pour réessayer, avec au plus 3 tentatives. Parsing retourne à parsing quand le bail expire parce qu'un processus s'est arrêté : la tâche est reprise. Indexed et failed se terminent tous deux quand le document est supprimé.
Les états d'ingestion d'un document. Un fichier impossible à analyser échoue immédiatement; les autres erreurs entraînent de nouvelles tentatives, au plus trois fois.
Description textuelle du diagramme

Un téléversement crée le document dans l’état uploaded et répond 202. Le processus prend la tâche en charge, ce qui la fait passer à parsing et lui donne un bail de 5 minutes. Cette prise en charge expire automatiquement, comme dans la leçon Cycle de vie d’une tâche du cours Mettre à l’échelle les API et les charges de travail d’IA. Si l’analyse, le découpage, la production des plongements et la sauvegarde réussissent, une transaction fait passer le document à indexed. Si le fichier ne peut pas être analysé, il passe immédiatement à failed, avec la raison, car réessayer ne servirait à rien. Toute autre erreur, comme une connexion perdue à la base de données, le ramène à uploaded pour une autre tentative. Il y a au plus 3 tentatives. Si un processus s’arrête, son bail expire et une autre prise en charge reprend le document. Supprimer un document indexed ou failed le retire avec son fichier, ses segments et ses vecteurs.

Le contrat précise aussi ce que la personne voit. uploaded et parsing s’affichent comme « indexation en cours », et la page redemande le statut toutes les 1,5 secondes. indexed affiche le nombre de passages. failed affiche la raison, par exemple « Ce fichier n’est pas un PDF lisible ». Mei vérifie surtout une règle : aucun parcours ne laisse un document bloqué dans parsing pour toujours.

Chaque segment représente une section d’une version de document, et son texte commence par le titre du document. La recherche filtre les résultats avant de sélectionner les 5 premiers passages :

  • la boutique : tenant_id;
  • le niveau d’accès : un membre en lecture seule cherche uniquement dans les documents publics;
  • la date : effective_from <= as_of <= effective_to, pour qu’une version expirée ne soit jamais en concurrence;
  • le modèle de plongement : le embedder du document doit correspondre au modèle qui a produit le plongement de la question.

Chacun de ces quatre filtres répond à une défaillance de la section sur le problème. Chaque passage fourni au modèle reçoit aussi un en-tête avec son identifiant, son titre, son type, sa version et ses dates. Le modèle peut alors le citer et voir quelle version il lit.

Exercice guidé : le schéma dans une vraie base de données

Section intitulée « Exercice guidé : le schéma dans une vraie base de données »

Vous copiez les fichiers de cette leçon, démarrez PostgreSQL dans Docker, appliquez le schéma et exécutez les nouveaux tests.

  1. Copiez les fichiers de cette leçon à partir de l’instantané end-of-m02 :

    Fenêtre de terminal
    S=../nextia-learning-labs/C27/snapshots/end-of-m02
    mkdir -p migrations docs/design-pack
    cp "$S/doc_assistant/config.py" "$S/doc_assistant/migrate.py" doc_assistant/
    cp "$S/migrations/001_core.sql" migrations/
    cp "$S/tests/conftest.py" "$S/tests/test_schema.py" tests/
    cp "$S/docs/design-pack/architecture.md" docs/design-pack/
    cp "$S/compose.yaml" "$S/.env.example" .
  2. Créez votre fichier .env à partir de l’exemple. Il contient le mot de passe de la base de données, donc Git l’ignore.

    Fenêtre de terminal
    cp .env.example .env
  3. Ouvrez .env dans VS Code. Remplacez change-me-on-your-computer par votre propre mot de passe aux trois endroits. Si votre ordinateur utilise déjà le port 5432, ajoutez la ligne DB_PORT=5433. Remplacez aussi 5432 par 5433 dans les deux URL.

  4. Démarrez la base de données. --wait rend la main quand PostgreSQL est prêt à accepter des connexions :

    Fenêtre de terminal
    docker compose up -d --wait db

    La première fois, Docker télécharge l’image (environ 690 Mo sur disque). Docker crée un réseau, le volume pgdata et le conteneur, puis attend. La dernière ligne indique que la base de données est prête :

    Container doc-assistant-db-1 Healthy

    Sans --wait, la commande rend la main dès que le conteneur démarre. Une migration exécutée à ce moment peut échouer, car PostgreSQL démarre encore. Lors de l’essai de l’auteur, elle s’est arrêtée avec le message « This probably means the server terminated abnormally before or while processing the request. » (Le serveur s’est probablement arrêté anormalement avant ou pendant le traitement de la requête.) Relancez-la quelques secondes plus tard, ou utilisez --wait.

  5. Appliquez le schéma :

    Fenêtre de terminal
    python -m doc_assistant.migrate
    applied 001_core
    1 migration(s) applied.
  6. Exécutez la commande de nouveau. Une migration ne s’exécute qu’une seule fois :

    Fenêtre de terminal
    python -m doc_assistant.migrate
    python -m doc_assistant.migrate --status
    The database is up to date.
    001_core applied
  7. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest
    ....................... [100%]
    23 passed in 0.25s

    Les cinq nouveaux tests s’exécutent dans une base de données distincte, assistant_test, qu’ils recréent chaque fois. Ils vérifient quatre choses. Les tables existent. Un segment de Bramble ne peut pas pointer vers un document de Larkfield. La même clé de document peut exister dans deux boutiques. Et la base de données refuse un état ou un niveau d’accès inventé.

Pour voir les tables, interrogez PostgreSQL dans son conteneur :

Fenêtre de terminal
docker compose exec db psql -U assistant -d assistant -c '\dt'
List of tables
Schema | Name | Type | Owner
--------+-------------------+-------+-----------
public | answers | table | assistant
public | chunks | table | assistant
public | document_files | table | assistant
public | documents | table | assistant
public | memberships | table | assistant
public | schema_migrations | table | assistant
public | tenants | table | assistant
public | users | table | assistant
(8 rows)

schema_migrations est le registre du programme de migration : le nom et le SHA-256 de chaque fichier appliqué.

Écrivez-les après l’ensemble de données et avant la première intégration. Un contrat écrit avant le code permet de construire la page et le processus à des jours différents. Les deux suivent ce contrat. Écrivez seulement ce qu’un réviseur ou un test peut vérifier : chemins, structures, codes, clés, états et filtres.

Il faut un après-midi de rédaction, et les contrats doivent rester exacts. Quand le module 4 ajoute la connexion, le tableau change d’abord, puis le code. Inclure le locataire dans chaque clé ralentit peu le système. Le cours Authentification, autorisations et applications multilocataires a mesuré environ 0,1 ms par requête pour la sécurité au niveau des lignes. Cette simplification a aussi une limite. À des centaines de téléversements par minute, la première modification serait d’ajouter un processus distinct. python -m doc_assistant.worker existe pour cela dès le module 3.

Erreur courante

Les tests s'exécutent avant le démarrage de la base de données

Symptôme : les nouveaux tests s’arrêtent avec cinq erreurs :

E psycopg.OperationalError: connection failed: connection to server at "127.0.0.1", port 5432 failed: could not receive data from server: Connection refused
...
ERROR tests/test_schema.py::test_the_core_tables_exist - psycopg.OperationalE...
ERROR tests/test_schema.py::test_a_chunk_cannot_point_at_another_shops_document
ERROR tests/test_schema.py::test_the_same_document_key_may_exist_in_two_shops
ERROR tests/test_schema.py::test_states_and_access_levels_are_checked[status-done]
ERROR tests/test_schema.py::test_states_and_access_levels_are_checked[access-secret]
18 passed, 5 errors in 0.23s

Cause : .env définit TEST_DATABASE_URL, donc les tests tentent de se connecter, mais aucun PostgreSQL n’écoute. Docker Desktop est fermé, ou le conteneur est arrêté.

Correction : démarrez Docker Desktop, puis exécutez docker compose up -d --wait db, et relancez les tests. Pour exécuter seulement les tests sans base de données, retirez TEST_DATABASE_URL de .env. Les cinq tests sont alors ignorés, avec une raison.

Erreur courante

Une migration déjà appliquée est modifiée

Symptôme : Tomás ajoute une ligne à 001_core.sql après son application. --status et le programme de migration signalent tous deux la modification. Le programme n’applique rien (code de sortie 1) :

001_core CHANGED after it was applied
Stopped: 001_core changed after it was applied. Write a new migration.

Cause : votre base de données contient déjà l’ancien 001_core. Modifier le fichier ne modifie pas la base de données. Le programme compare le SHA-256 de chaque fichier appliqué avec son registre, comme dans le cours Bases de données et stockage pour les applications d’IA. Il s’arrête à la première différence.

Correction : restaurez le fichier (git checkout migrations/001_core.sql). Une modification à un schéma déjà appliqué doit aller dans un nouveau fichier : 002_...sql. Le contrat dans architecture.md énumère les migrations dans l’ordre, pour que le réviseur voie chaque modification.

Dans les deux parcours, rédigez docs/design-pack/architecture.md pour votre produit à partir de docs/templates/architecture.md. Dans le parcours standard, partez du fichier de Sam et adaptez ce que votre produit fait différemment.

  1. Dessinez vos composants. Partez du bloc Mermaid dans le fichier de Sam. Retirez chaque composant qu’aucun critère d’acceptation n’exige. Pour chaque composant, écrivez son unique tâche et la chose qu’il ne doit jamais faire.
  2. Rédigez le tableau du contrat : une ligne par point de terminaison, avec les appelants autorisés, la réponse de succès et chaque code d’erreur.
  3. Rédigez le modèle de données. Indiquez la colonne qui précise le locataire de chaque ligne, et chaque clé qui doit l’inclure.
  4. Dessinez les états d’ingestion. Pour chaque état, écrivez ce qui en fait sortir un document et ce que la personne voit.
  5. Énumérez les métadonnées de récupération et le filtre qui utilise chaque champ.
  6. Rédigez migrations/001_core.sql à partir de votre modèle de données. Appliquez-le, puis exécutez python -m doc_assistant.migrate --status.
  7. Demandez à un réviseur de vérifier le document selon vos critères d’acceptation, ou relisez-le vous-même le lendemain. Retirez un composant ou un champ qu’aucun critère n’exige.

Preuves à conserver : architecture.md, la sortie de python -m doc_assistant.migrate --status et la sortie des tests.

Liste de vérification

  • Chaque composant a une tâche et une chose qu’il « ne doit jamais » faire.
  • Chaque point de terminaison précise ses appelants, sa réponse de succès et ses erreurs, dans une structure d’erreur unique.
  • Chaque table contenant des données de locataire a une colonne de locataire. Chaque clé entre ces tables l’inclut.
  • Les états d’ingestion n’ont aucune impasse : chaque document finit indexed (indexé), failed (en échec) ou supprimé.
  • La recherche filtre par locataire, accès, date et modèle avant de retenir les meilleurs résultats.
  • J’ai retiré au moins un composant ou champ qu’aucun critère d’acceptation n’exige, et j’ai noté pourquoi.

Changez une condition. Ines demande une nouvelle fonctionnalité : un membre peut télécharger le fichier original d’un document pour vérifier le texte complet. Rédigez la ligne du contrat correspondante. Répondez ensuite : quelle table contient les octets, quelle clé les trouve, et que reçoit un membre en lecture seule pour un document réservé au personnel?

Afficher une réponse possible
Méthode et chemin Appelants autorisés Succès Erreurs
GET /v1/tenants/{t}/documents/{id}/file chaque membre, selon son niveau d’accès 200 avec les octets du fichier et son content_type; le nom du fichier dans un en-tête Content-Disposition 401, 404

Les octets sont dans document_files, accessibles par (tenant_id, document_id). La boutique fait partie de la clé, donc un chemin Larkfield ne peut pas atteindre un fichier Bramble. Un membre en lecture seule qui demande un document réservé au personnel reçoit 404. Le corps de la réponse est identique à celui d’un document inexistant. Un code 403 lui indiquerait que le document existe. Un document en échec conserve aussi son fichier, pour que la personne voie ce qu’elle a téléversé.

Vérifiez votre compréhension

Pourquoi un téléversement répond-il 202 Accepted plutôt que 200 OK, et que doit faire la page en conséquence?

Afficher la réponse

202 signifie « enregistré, pas terminé » : l’API conserve le fichier et crée la ligne du document. Le processus l’indexe plus tard. L’indexation peut prendre quelques secondes et peut échouer. La page doit donc demander l’état du document avec GET /v1/tenants/{t}/documents/{id}. Elle affiche « indexing » (indexation en cours) tant que l’état est uploaded (téléversé) ou parsing (analyse en cours). Elle affiche ensuite le nombre de passages, ou la raison de l’état failed. Un code 200 ferait annoncer le succès trop tôt à la page.

Vérifiez votre compréhension

Prédisez : Ines téléverse une deuxième fois la version 1 de la politique de retours de Bramble, comme nouveau fichier légèrement modifié. Le schéma contient UNIQUE (tenant_id, doc_key, version). Que se passe-t-il, et que devrait-elle faire à la place?

Afficher la réponse

La base de données refuse la deuxième ligne ayant la même boutique, la même clé et la même version. L’API répond 409 conflict (conflit). C’est le bon résultat : deux textes différents ne doivent pas être tous deux la « version 1 ». Elle devrait téléverser le texte modifié comme une nouvelle version, avec sa propre valeur effective_from. Larkfield peut toujours avoir son propre returns-policy, car la boutique fait partie de la clé unique.

Vérifiez votre compréhension

Vérification pratique : montrez que votre schéma refuse un segment qui pointe vers un document d'un autre locataire. Quelle contrainte le refuse, et quel test le prouve?

Afficher la réponse

C’est la clé étrangère (tenant_id, document_id) REFERENCES documents (tenant_id, document_id) qui le refuse. Un segment avec tenant_id = 'bramble' et l’identifiant d’un document Larkfield n’a aucune ligne correspondante. Dans le projet de Sam, tests/test_schema.py::test_a_chunk_cannot_point_at_another_shops_document en insère un et attend ForeignKeyViolation. Votre réponse doit nommer votre propre contrainte et votre test, et montrer que le test réussit.

Récapitulatif

  • Un contrat est un accord écrit à une frontière : ce qui est envoyé, ce qui revient, les erreurs et les appelants autorisés. Écrivez-le avant le code.
  • Sam en a quatre : le contrat de l’API, le schéma de la base de données, les états d’ingestion et les métadonnées de récupération. Ils sont tous dans docs/design-pack/architecture.md.
  • La boutique est dans chaque clé : identifiants de segments, clés primaires et clés étrangères. La base de données refuse un segment qui pointe vers un document d’une autre boutique.
  • Un téléversement répond 202. La ligne documents représente la tâche : uploaded, parsing, puis indexed ou failed avec une raison.
  • La recherche filtre par boutique, accès, date et modèle de plongement (embedding) avant de retenir les 5 meilleurs résultats.
  • Un processus et une base de données suffisent pour deux petites boutiques. Chaque composant supplémentaire exige un critère qui le justifie.
  • python -m doc_assistant.migrate applique 001_core. Les tests affichent 23 passed (23 tests réussis).

Ensuite, vous examinez la même conception du point de vue d’un attaquant, et vous fixez un budget.

Leçon suivante : Revue des menaces et des coûts