Aller au contenu
English

Fondations du backend

  • Leçon 8
  • 120 min
  • Module 3 : Créer un parcours utilisateur complet

Où nous en sommes

Dans le module 2, nous avons conçu sur papier l'ensemble de données, les contrats et les défenses. Maintenant, nous construisons. Mais si nous terminons chaque partie séparément, rien ne fonctionne ensemble avant la fin. Dans cette leçon, nous faisons fonctionner un parcours utilisateur sur le serveur, avec des substituts pour les parties lentes et coûteuses, comme la soirée d'essai d'un nouveau restaurant avec un seul plat.

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

Ce que vous saurez faire

Faites d’abord fonctionner un parcours utilisateur sur le serveur : téléverser un document, suivre son état, poser une question et enregistrer la réponse. Des substituts remplacent les parties lentes et coûteuses. Chaque ajout se connecte ainsi à quelque chose qui fonctionne déjà.

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

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre projet à la fin du module 2, dans ~/projects/doc-assistant : python -m pytest affiche 23 passed (23 tests réussis), et python -m doc_assistant.migrate a appliqué 001_core.
  • Docker Desktop en cours d’exécution et environ 1 Go d’espace disque libre pour les paquets de ce module.
  • Le dépôt des exercices à côté de votre projet, dans ~/projects/nextia-learning-labs, comme dans Préparer le dépôt du projet intégrateur.

Un nouveau restaurant n’ouvre pas avec un menu de quarante plats. Il commence par une soirée d’essai avec un seul plat. Un client commande, la cuisine prépare, un serveur sert et le client paie. Chaque partie fonctionne une fois, de l’entrée à la facture.

La soirée d’essai révèle les problèmes qu’aucune partie ne montre seule. Les bons de commande sont trop petits pour être lus. Les assiettes ne passent pas dans le passe-plat. Le lecteur de cartes se trouve au mauvais bout de la salle. Les cuisiniers pourraient cuisiner parfaitement, et la soirée échouerait quand même.

Le problème : trois semaines de pièces, rien à essayer

Section intitulée « Le problème : trois semaines de pièces, rien à essayer »

Sam a le dossier de conception du module 2. Tomás a un plan : « Rendre la recherche parfaite d’abord. Puis ajouter un modèle de reclassement (reranker). Puis la page. » Cela semble prudent. Mais après trois semaines, Grace ne pourrait toujours pas téléverser un document ni poser une question.

Pire encore, les parties se rencontreraient pour la première fois à la fin. Deux réalités de ce projet apparaissent seulement quand les parties se connectent. L’étape de réponse a besoin du nom de la boutique pour sa requête (prompt). La boutique de l’appelant doit donc passer de l’URL au modèle. De plus, la première recherche ou indexation après un démarrage charge le modèle de plongement (embedding). Dans les exécutions du cours, cela prend environ 4 secondes, avant tout travail. Un téléversement qui attend l’indexation fait aussi attendre le navigateur. Un arrêt brutal en cours de route fait perdre le téléversement. Chacune de ces réalités change la conception et coûte plus cher à corriger tardivement.

L’idée : un chemin minimal à travers chaque couche

Section intitulée « L’idée : un chemin minimal à travers chaque couche »

Créez d’abord la version minimale de chaque couche, puis connectez-les. Une personne doit pouvoir effectuer toute la tâche une fois. Ce chemin est une tranche verticale. Dessinez les couches du produit les unes au-dessus des autres : la page, l’API, l’ingestion, l’étape de réponse et la base de données. Une tranche traverse toutes les couches, comme un couteau coupe un gâteau.

Le jalon de ce module, « Un parcours » dans le mandat de Sam, correspond à cette tranche. Un nouvel utilisateur téléverse un document, le voit indexé, pose une question et lit une réponse avec une citation.

Deux panneaux avec les mêmes cinq rangées : page, API, ingestion, étape de réponse, base de données. À gauche, couche par couche : la base de données et l'API sont construites, l'ingestion est partiellement construite, l'étape de réponse est à peine construite et la page est vide. Après trois semaines, une personne n'a rien à essayer. À droite, une tranche verticale : une colonne étroite traverse les cinq rangées : une page simple, dix points de terminaison avec un format d'erreur unique, des tâches passant de téléversé à indexé, une réponse simulée avec une citation, le schéma 001. Après une semaine, une personne peut téléverser, poser une question et lire une réponse.
Le même travail dans deux ordres. Couche par couche, rien ne fonctionne avant la fin. Une tranche verticale fonctionne tôt, et chaque leçon suivante améliore une couche.
Description textuelle du diagramme

À gauche : chaque couche est terminée avant de commencer la suivante. Après trois semaines, la base de données et l’API sont complètes, l’ingestion est à moitié faite, et aucune page n’existe. Personne ne peut essayer le produit. À droite : chaque couche reçoit d’abord sa version la plus simple. Une page simple, dix points de terminaison avec un format d’erreur unique, des tâches avec des états, une réponse simulée avec une citation et la première migration. Après une semaine, une personne peut effectuer toute la tâche une fois. Les semaines servent d’illustration, pas de mesure.

Une tranche n’est pas une démo avec de faux écrans. Chaque partie contient du vrai code que les modules suivants conservent. Seules deux parties sont des substituts : des remplacements simples pour les parties lentes ou coûteuses, avec la même interface.

Deux substituts : aucun modèle, aucun téléchargement

Section intitulée « Deux substituts : aucun modèle, aucun téléchargement »

Une équipe de tournage utilise une doublure pendant les répétitions. La doublure a la taille de l’acteur et suit les mêmes repères. L’équipe peut ainsi préparer l’éclairage et les caméras. Le véritable acteur arrive quand tout le reste fonctionne.

Le projet intégrateur a deux parties lentes ou payantes, et chacune reçoit un substitut. Un paramètre dans .env choisit chacune :

Partie Version réelle (dans « Intégrer la récupération ») Substitut (maintenant) Paramètre
Modèle de plongement e5 : téléchargement de 470 Mo; environ 4 s de chargement, puis environ 6 s pour indexer l’ensemble hash : chaque mot ajoute 1 à l’un des 384 nombres. Aucun téléchargement, aucun sens EMBEDDER
Modèle de réponse Réponses réelles recorded (enregistrées), ou appels live (en direct) avec votre propre clé mock (simulé) : la première phrase du meilleur passage, avec une citation ANSWER_PROVIDER

Les deux substituts ont la même petite interface que les parties réelles. Le pipeline appelle embedder.embed_queries([...]) et provider.complete(request), sans savoir quelle version répond. C’est l’adaptateur de La frontière de l’application. Il a maintenant trois fournisseurs dans doc_assistant/providers.py : mock, recorded et live.

La règle complète de la simulation tient en une phrase : copier la première phrase du meilleur passage et citer ce passage. Voici le petit exemple tiré de l’exécution de Sam avec les deux substituts :

$ python -m scripts.ask "How long does delivery to Ontario take?" --tenant bramble
Ines (staff) at Bramble Books asks: How long does delivery to Ontario take?
Passages found: e5e28bf8b6a1 faq v4, 20804b124392 delivery-policy v1, c230e31d26bd delivery-policy v1, 3716423a735e events-and-room-hire v1, 1c43933c27c8 returns-policy v1
Answer (answerable): How long does a special order take?
- How long does a special order take? [Frequently asked questions, How long does a special order take?, v4]
mock mock | 6 ms | tokens 0 in, 0 out | US$0.000000 | trace da9d0f3916c83fd4b1ace0a89d593e32

Lisez-le ligne par ligne. La recherche par hachage a classé la FAQ en premier. Elle partage les mots « How long » (combien de temps) et « take » (prendre) avec la question. Elle ne comprend pas que la question porte sur la livraison. La simulation a ensuite copié la première phrase de ce passage, qui est un titre sous forme de question. Les deux substituts ont fait exactement leur travail, et la réponse est inutile. C’est acceptable pour un substitut : le format est correct, la citation est réelle, le coût est nul. Chaque ligne indique mock. Avec le vrai modèle de plongement, dans la dernière leçon du module, la même simulation copie une phrase de la politique de livraison : « We ship within 2 business days. » (Nous expédions dans un délai de 2 jours ouvrables.)

Quand utiliser les substituts. Utilisez-les pendant que vous connectez les parties et dans les tests. Ils sont rapides, gratuits et donnent toujours la même sortie. Quand les éviter. Ne mesurez jamais la qualité avec eux et ne présentez jamais une réponse simulée comme celle du produit. Ce qu’ils coûtent. Deux chemins de code à maintenir et une étiquette sur chaque sortie.

Des points de terminaison validés et un format d’erreur unique

Section intitulée « Des points de terminaison validés et un format d’erreur unique »

Chaque requête passe une vérification avant l’exécution du code du projet. Vous avez vu cela dans Validation et réponses d’erreur. Voici pourquoi c’est encore plus important pour un produit d’IA : une requête qui atteint le modèle coûte de l’argent. Une question de deux lettres, ou un champ inconnu de l’API, doit être bloqué à l’entrée.

doc_assistant/models.py définit ce qu’une question peut être :

class AskRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
question: str = Field(min_length=3, max_length=500, description="The question, in plain words.")
as_of: date | None = Field(default=None, description="The date the answer is for (default: today). ...")

doc_assistant/errors.py donne à chaque défaillance un format unique, {"code", "message", "request_id"}, avec details pour une erreur de validation. code sert aux programmes et ne change jamais; message sert aux personnes. Le request_id figure aussi dans l’en-tête X-Request-ID et dans la ligne du journal de la requête. Une erreur inattendue n’affiche jamais son texte ni sa trace de pile. Le journal les contient, sous le même identifiant.

L’exécution de Sam, avec une question de deux lettres :

HTTP/1.1 422 Unprocessable Entity
content-type: application/json
x-request-id: 61bfb5970c5b495c
cache-control: no-store
{"code":"validation_error","message":"The request is not valid.","request_id":"61bfb5970c5b495c","details":[{"field":"question","problem":"String should have at least 3 characters"}]}

Les téléversements sont vérifiés dans ingest.create_document, avant tout enregistrement. Sam a essayé une mauvaise requête de chaque type. Voici les réponses réelles, réduites au statut et au corps :

Requête Statut code message (et details)
Un fichier .docx 415 unsupported_file Téléversez un fichier .md, .txt, .html ou .pdf.
Un fichier vide 422 empty_file Le fichier est vide.
Un fichier de 5 000 001 octets 413 file_too_large Le fichier fait 5 000 001 octets; la limite est de 5 000 000 octets.
Un téléversement avec access=everyone 422 validation_error Les métadonnées du document ne sont pas valides. access : doit être public ou staff
Une question avec un champ supplémentaire, "shop": "bramble" 422 validation_error La requête n’est pas valide. shop : les entrées supplémentaires ne sont pas permises
Une boutique inexistante : /v1/tenants/acme/documents 404 not_found Introuvable.
Un identifiant de document qui n’est pas un identifiant : …/documents/42 404 not_found Introuvable.

La page de la prochaine leçon lit code et message de chacune de ces réponses de la même façon. Un seul format signifie un seul morceau de code pour gérer toutes les erreurs.

L’indexation est lente : analyser le fichier, le découper en passages et calculer un vecteur pour chaque passage. Le téléversement ne l’attend donc pas. C’est le reçu du nettoyeur de Cycle de vie d’une tâche. L’API vérifie le fichier, enregistre les octets et une ligne avec status = 'uploaded' (état téléversé). Elle répond immédiatement avec 202 Accepted (accepté) et un Location (emplacement) à suivre. Le processus effectue la partie lente plus tard.

Le module 2 a établi que la table des documents est la file d’attente. Aucune table de tâches distincte n’est donc nécessaire. Le processus dans doc_assistant/worker.py réserve le plus ancien document en attente avec FOR UPDATE SKIP LOCKED. Deux processus ne prennent donc jamais le même document. Il définit parsing (analyse en cours) avec un bail de 5 minutes. Il termine à indexed (indexé), ou à failed (échec) avec une raison sur laquelle une personne peut agir. Par défaut, il s’exécute comme fil d’exécution dans le processus de l’API (INGEST_WORKER=thread). Le modèle de plongement est alors chargé une seule fois, et vous avez besoin d’un terminal de moins.

Un diagramme de séquence avec trois participants : le client, l'API et le fil d'exécution de traitement, ainsi que la base de données. Le client envoie le fichier. L'API vérifie la taille, le type et les métadonnées, enregistre la ligne à l'état uploaded et les octets dans une transaction, puis répond 202 avec un en-tête Location. Le processus, qui cherche du travail chaque seconde, réserve le document avec FOR UPDATE SKIP LOCKED et définit parsing avec un bail de 5 minutes. Il analyse, découpe et calcule les plongements, puis enregistre les segments et définit indexed dans une transaction. Le client demande le Location et voit indexed avec le nombre de passages.
Un téléversement dans l'exécution de Sam. La réponse au téléversement arrive avant le début du travail lent.
Description textuelle du diagramme

Le client envoie le fichier. L’API vérifie sa taille, son type et ses métadonnées. Elle enregistre ensuite la ligne à l’état uploaded et les octets du fichier dans une transaction. Elle répond 202 avec un en-tête Location, en 12 ms dans l’exécution de Sam. Le fil d’exécution de traitement cherche du travail chaque seconde. Il réserve la plus ancienne ligne en attente avec FOR UPDATE SKIP LOCKED et définit parsing avec un bail de 5 minutes. Il analyse ensuite le fichier, le découpe et calcule les plongements : 2 passages. Il enregistre les segments et leurs vecteurs, puis définit indexed, dans une transaction. Cela se termine 0,26 seconde après le téléversement, avec le substitut par hachage. Un GET sur le Location affiche alors indexed et chunk_count (nombre de segments) 2.

Les trois leçons de ce module partagent un instantané, end-of-m03. Cette leçon lit et exécute son backend, la suivante sa page, et la dernière sa récupération. Dans le parcours standard, copiez maintenant l’instantané par-dessus votre projet. Dans le parcours avec votre propre idée, suivez la lecture. Écrivez les mêmes parties pour votre produit dans Votre projet ci-dessous.

  1. Enregistrez d’abord votre travail dans un commit (une version enregistrée) : git add -A et git commit -m "End of Module 2". Copiez ensuite les fichiers de l’instantané par-dessus votre projet. Votre .env et votre base de données restent en place.

    Fenêtre de terminal
    cd ~/projects/doc-assistant
    cp -R ../nextia-learning-labs/C27/snapshots/end-of-m03/. .

    La copie remplace aussi votre mandat, vos critères, votre plan et votre dossier de conception par les fichiers de Sam dans docs/. Récupérez les vôtres depuis votre dernier commit avec git checkout -- docs. Le README.md est maintenant celui de l’instantané : il énumère les commandes de cette étape.

  2. Installez les nouveaux paquets, avec l’environnement virtuel actif. Ce module ajoute FastAPI, les paquets du modèle et torch, soit environ 900 Mo. Sur Linux sans GPU, installez d’abord la version pour processeur de torch, comme l’indique requirements.txt.

    Fenêtre de terminal
    pip install -r requirements.txt
  3. Ouvrez .env.example et .env côte à côte. Copiez dans .env chaque ligne qui lui manque : les paramètres de ce module, de ANSWER_PROVIDER à DEV_USER. Gardez votre mot de passe. Choisissez ensuite les deux substituts : ajoutez la ligne EMBEDDER=hash et changez ANSWER_PROVIDER pour mock. Votre .env contient alors ces deux lignes :

    Fenêtre de terminal
    EMBEDDER=hash
    ANSWER_PROVIDER=mock
  4. Démarrez la base de données et exécutez les tests. Les tests utilisent aussi les substituts, ainsi que leur propre base de données.

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

    L’exécution de Sam a affiché :

    .............................................................. [100%]
    62 passed in 3.14s
  5. Chargez les boutiques, les personnes et les 51 documents. Le script téléverse chaque fichier avec le même code que l’API. Il exécute ensuite le processus jusqu’à ce que la file d’attente soit vide.

    Fenêtre de terminal
    python -m scripts.load_pack
    Identity: 2 shops, 7 people, 6 memberships
    larkfield: 36 documents uploaded, 0 already there
    bramble: 15 documents uploaded, 0 already there
    Indexing with hash-384 ...
    Indexed 51 documents in 0.2 s (failed 0).
    bramble: 15 documents, 60 passages, 0 failed
    larkfield: 36 documents, 185 passages, 0 failed
  6. Démarrez l’API dans un deuxième terminal, avec l’environnement virtuel actif. Laissez-la fonctionner.

    Fenêtre de terminal
    fastapi dev doc_assistant/main.py

    Le journal contient volontairement un avertissement : AUTH_MODE=dev: every request without a token acts as usr-sam. Use it only on your computer. (Chaque requête sans jeton agit comme usr-sam. Utilisez ce mode seulement sur votre ordinateur.)

  7. Dans le premier terminal, vérifiez que l’API fonctionne et qu’elle est prête. Sur Windows, tapez curl.exe au lieu de curl.

    Fenêtre de terminal
    curl -s http://127.0.0.1:8000/health
    curl -s http://127.0.0.1:8000/ready
    {"status":"ok","version":"1.0.0"}
    {"status":"ready","version":"1.0.0","answer_provider":"mock","auth_mode":"dev"}

    /health indique que le processus fonctionne. /ready indique qu’il peut servir : la base de données répond et toutes les migrations sont appliquées.

Dans l’exécution du cours, l’API utilisait le port 8313, car un autre programme utilisait le port 8000. Vos commandes utilisent 8000.

Grace demande à Sam d’ajouter les heures du service d’assistance pendant les fêtes. Sam écrit un petit document. Il est inventé pour cette leçon. Enregistrez-le sous holiday-hours.md dans le dossier du projet :

---
doc_id: holiday-hours
title: Help desk holiday hours
version: 1
effective_from: 2026-10-11
effective_to: ""
owner: "Grace (support lead)"
access: public
language: en
doc_type: policy
---
# Help desk holiday hours
## Closed days
The help desk is closed on 25 December, 26 December and 1 January.
## Short days
On 24 December and 31 December, the help desk is open from 9 am to 2 pm.
  1. Téléversez-le dans Larkfield :

    Fenêtre de terminal
    curl -s -i -F file=@holiday-hours.md http://127.0.0.1:8000/v1/tenants/larkfield/documents
    HTTP/1.1 202 Accepted
    content-type: application/json
    location: /v1/tenants/larkfield/documents/09fd15f3-f76c-4923-b419-f726b33839af
    x-request-id: 80fe4d52a9c9458a
    cache-control: no-store
    {"document":{"document_id":"09fd15f3-f76c-4923-b419-f726b33839af","doc_key":"holiday-hours","version":"1","title":"Help desk holiday hours","doc_type":"policy","language":"en","access":"public","effective_from":"2026-10-11","effective_to":"","file_name":"holiday-hours.md","size_bytes":391,"sha256":"8c0cef055010b024f38d67267596d7b3428310e2ee6595441645b0d61db0091c","status":"uploaded","error":null,"attempts":0,"chunk_count":0,"uploaded_by":"usr-sam","uploaded_at":"2026-10-11T16:48:15.139950+00:00","indexed_at":null,"links":{"self":"/v1/tenants/larkfield/documents/09fd15f3-f76c-4923-b419-f726b33839af"}},"duplicate":false}

    L’état est uploaded : le fichier est enregistré et rien n’est encore indexé. Les métadonnées viennent de l’en-tête du fichier. Un champ de formulaire, comme -F access=staff, a priorité sur elles.

  2. Deux secondes plus tard, demandez le Location. Mettez votre propre document_id dans l’URL :

    Fenêtre de terminal
    curl -s http://127.0.0.1:8000/v1/tenants/larkfield/documents/<document_id>
    {"document":{"document_id":"09fd15f3-f76c-4923-b419-f726b33839af","doc_key":"holiday-hours","version":"1","title":"Help desk holiday hours","doc_type":"policy","language":"en","access":"public","effective_from":"2026-10-11","effective_to":"","file_name":"holiday-hours.md","size_bytes":391,"sha256":"8c0cef055010b024f38d67267596d7b3428310e2ee6595441645b0d61db0091c","status":"indexed","error":null,"attempts":1,"chunk_count":2,"uploaded_by":"usr-sam","uploaded_at":"2026-10-11T16:48:15.139950+00:00","indexed_at":"2026-10-11T16:48:15.404206+00:00","links":{"self":"/v1/tenants/larkfield/documents/09fd15f3-f76c-4923-b419-f726b33839af"}}}
  3. Posez une question :

    Fenêtre de terminal
    curl -s -H "Content-Type: application/json" -d '{"question": "Is the help desk open on 26 December?"}' http://127.0.0.1:8000/v1/tenants/larkfield/answers

    Dans PowerShell, placez d’abord le corps dans une variable : $body = '{"question": "Is the help desk open on 26 December?"}'. Envoyez-le ensuite avec curl.exe -s -H "Content-Type: application/json" -d $body et la même URL. La réponse, abrégée :

    {
    "answer": {
    "answer_id": "d4b37692-24a8-42c8-9128-fefd36463883",
    "answerable": true,
    "answer": "On 24 December and 31 December, the help desk is open from 9 am to 2 pm.",
    "claims": [
    {
    "text": "On 24 December and 31 December, the help desk is open from 9 am to 2 pm.",
    "citations": [
    {
    "chunk_id": "935f8e210cba",
    "document_id": "09fd15f3-f76c-4923-b419-f726b33839af",
    "title": "Help desk holiday hours",
    "doc_key": "holiday-hours",
    "version": "1",
    "section": "Short days",
    "access": "public"
    }
    ],
    "problems": []
    }
    ],
    "passages": "(5 passages, the best first)",
    "needs_review": false,
    "note": "",
    "provider": "mock",
    "model": "mock",
    "input_tokens": 0,
    "output_tokens": 0,
    "cost_usd": 0.0,
    "latency_ms": 7,
    "trace_id": "5a62cdf3e53caf875cfd30b0dbbbcf04"
    }
    }

Lisez cette réponse comme un enregistrement, pas comme une réponse. La recherche par hachage a classé les deux passages du nouveau document en premier, avec le même score, 0,6565. La simulation a copié la première phrase de « Short days » (journées courtes). Elle ne répond pas à la question sur le 26 décembre. La réponse se trouve dans « Closed days » (jours de fermeture), le deuxième passage. Un vrai modèle lit les cinq passages; la simulation en lit un seul. L’API l’a enregistrée avec ses citations, son fournisseur et son identifiant de trace. GET /v1/tenants/larkfield/answers la répertorie.

Personne ne se connecte. Chaque requête agit comme Sam (AUTH_MODE=dev). Rien ne vérifie que Sam appartient à la boutique dans le chemin :

Fenêtre de terminal
curl -s http://127.0.0.1:8000/v1/tenants/bramble/documents

La réponse, réduite à la boutique et aux nombres :

{"tenant": "bramble", "shop": "Bramble Books", "role": "staff", "counts": {"indexed": 15}}

Sam travaille chez Larkfield, et l’API vient de lui afficher les documents de Bramble Books. Appliquer les autorisations comble cette lacune. La revue des menaces de Sam dans le dossier de conception nomme déjà la menace : « Ines remplace larkfield par bramble dans l’URL ». Elle nomme aussi le contrôle, une vérification d’adhésion, que la tranche n’a pas encore. Une tranche peut avoir des lacunes connues. Elle ne doit pas les cacher : l’avertissement au démarrage et le README les signalent tous les deux.

Erreur courante

Le même fichier donne encore un conflit 409

Symptôme : vous téléversez holiday-hours.md une deuxième fois, et l’API répond :

HTTP/1.1 409 Conflict
content-type: application/json
x-request-id: 6cab6eac213b4d35
cache-control: no-store
{"code":"conflict","message":"Version 1 of holiday-hours already exists. Upload it with a new version number, or delete the old one first.","request_id":"6cab6eac213b4d35"}

Cause : le schéma permet une ligne par boutique, clé de document et version. Le fichier indique version: 1, et la version 1 existe déjà.

Solution : si le document a changé, augmentez version dans ses métadonnées d’en-tête, ou envoyez -F version=2. S’il n’a pas changé, vous n’avez rien à faire. Dans le module 4, Gérer les défaillances traite le même fichier comme un doublon sans danger (200, "duplicate": true), conformément au contrat.

Erreur courante

La recherche ne trouve rien après un changement d'EMBEDDER

Symptôme : vous définissez EMBEDDER=e5, redémarrez, et chaque réponse indique « The documents do not answer this question. » (les documents ne répondent pas à cette question).

Cause : les vecteurs de deux modèles ne sont pas comparables, même s’ils ont la même longueur. Chaque document conserve le nom du modèle qui a créé ses vecteurs. La recherche lit seulement les segments du modèle actuel. Vos segments ont été créés par hash-384.

Solution : refaites l’indexation avec le nouveau modèle : python -m scripts.load_pack --reset. La dernière leçon de ce module le fait et montre la sortie.

Erreur courante

curl n'affiche rien, ou indique « Connection refused » (connexion refusée)

Symptôme : curl -s http://127.0.0.1:8000/health n’affiche rien. Sans -s, curl indique qu’il n’a pas pu se connecter.

Cause : l’API ne fonctionne pas, ou elle s’est arrêtée au démarrage. Une raison fréquente : la base de données ne fonctionne pas, donc l’API ne peut pas s’y connecter.

Solution : regardez d’abord le terminal de l’API. Démarrez la base de données avec docker compose up -d --wait db, puis redémarrez l’API.

Faites la même étape pour votre produit : une tranche du backend, avec des substituts, avant tout modèle réel.

  • Parcours standard. Exécutez les étapes ci-dessus sur votre copie. Ensuite, téléversez un document que vous avez écrit vous-même et posez une question à laquelle seul ce document répond.
  • Parcours avec votre idée. Écrivez le backend de votre parcours utilisateur unique, dans le même ordre. D’abord, les modèles de requête et un format d’erreur. Ensuite, le téléversement qui renvoie 202 et une tâche avec des états. Puis, la question, par un adaptateur avec une simulation. Réutilisez les fichiers de l’instantané quand ils conviennent à votre domaine. Chaque fichier indique sa provenance et conserve son avis de licence MIT.

Preuves à conserver. Enregistrez une transcription du terminal dans docs/evidence/m03-backend.txt : pytest, /ready, un téléversement avec son code 202, l’état indexé, une réponse et les cas d’erreur du tableau ci-dessus. Indiquez votre ordinateur et votre version de Python en haut. Votre README y renvoie dans le module 7.

Liste de vérification

  • python -m pytest réussit, et les tests utilisent les substituts, pas un modèle réel.
  • Chaque point de terminaison de votre tranche vérifie ses entrées avant de faire tout travail.
  • Chaque erreur a le même format, avec un request_id qui figure aussi dans le journal.
  • Un téléversement répond immédiatement avec 202, et son état passe à indexed (indexé), ou à failed (échec) avec une raison.
  • Chaque réponse simulée indique mock (simulation), et vous ne présentez jamais sa qualité.
  • Les lacunes connues de la tranche sont consignées, par exemple « personne ne se connecte encore ».

Vérifiez votre compréhension

Tomás dit : « Une tranche verticale, c'est du gaspillage. Nous allons jeter la simulation et le modèle de plongement par hachage de toute façon. » Donnez deux raisons pour lesquelles Sam les a créés en premier.

Afficher la réponse

Premièrement, la tranche a relié toutes les parties tôt. Les problèmes qui apparaissent seulement quand les parties se connectent sont ressortis dès la première semaine. La requête a besoin du nom de la boutique, et un téléversement ne doit pas attendre l’indexation. Découverts plus tard, ces problèmes coûteraient chacun plus cher à corriger. Deuxièmement, les substituts ne sont pas jetés. Les tests les conservent, car ils sont rapides, gratuits et reproductibles : 62 tests réussissent sans modèle ni clé. Pour l’utilisation réelle, seul un réglage dans .env change.

Vérifiez votre compréhension

Prédisez : vous téléversez un PDF tronqué pendant le téléversement. Quel code d'état le téléversement reçoit-il, et que montre GET sur son Location quelques secondes plus tard?

Afficher la réponse

Le téléversement reçoit 202 Accepted (accepté). L’API vérifie seulement ce qu’elle peut vérifier immédiatement : la taille, le type de fichier et les métadonnées. Un PDF tronqué passe ces vérifications. Le processus trouve le problème lorsqu’il analyse le fichier. Il définit immédiatement failed, sans nouvelle tentative, car une nouvelle analyse échouerait de la même façon. L’état affiche alors failed avec une raison : « This file is not a readable PDF (PdfStreamError). » (ce fichier n’est pas un PDF lisible). La prochaine leçon le montre sur la page.

Vérifiez votre compréhension

Pourquoi l'API répond-elle à une question de deux lettres avec 422 avant toute recherche, plutôt que de laisser le modèle décider?

Afficher la réponse

Une requête qui atteint la recherche et le modèle prend du temps et, avec un modèle réel, coûte de l’argent. Elle ne peut pas donner de réponse utile. Le modèle de requête (3 à 500 caractères, aucun champ inconnu) la rejette dès l’entrée. Son erreur suit le format commun et nomme le champ incorrect. Ainsi, la page et chaque script peuvent afficher le problème de la même façon.

Récapitulatif

  • Une tranche verticale relie la version minimale de chaque couche pour qu’une personne puisse accomplir toute la tâche une fois. C’est le jalon de ce module.
  • Les substituts remplacent les parties lentes et coûteuses derrière la même interface : le modèle de plongement par hachage et le fournisseur simulé. Utilisez-les pour connecter et tester, jamais pour mesurer la qualité.
  • Chaque requête est vérifiée avant tout travail, et chaque erreur a un seul format : code, message, request_id.
  • Un téléversement est une tâche : 202 immédiatement, puis uploaded → parsing → indexed (téléversé → analyse → indexé), ou failed avec une raison. La table des documents sert de file d’attente.
  • La tranche a une lacune connue : personne ne se connecte encore. Le module 4 la corrige.

Ensuite, Grace obtient une page pour utiliser la tranche sans terminal.

Leçon suivante : Fondations du frontend