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.
Leçon 8 sur 22 · Projet intégrateur : créer, évaluer et livrer un produit d'IAFondations du backend
1. Choisir et délimiter le projet
2. Préparer les données et l'architecture
3. Créer un parcours utilisateur complet
4. Ajouter la fiabilité et le contrôle d'accès
5. Évaluer et améliorer
6. Déployer et exploiter
7. Préparer la présentation du portfolio
Ce que vous saurez faire
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 main
Ce que vous devez savoir
- Le dossier de conception de votre projet : les contrats, le schéma et les états d’ingestion, dans Architecture et contrats.
- Les modèles de requête et un format d’erreur unique dans FastAPI, dans Validation et réponses d’erreur.
- L’adaptateur : le seul code qui communique avec un modèle, avec une simulation derrière, dans La frontière de l’application.
- Une file d’attente, un processus et un bail, dans Cycle de vie d’une tâche.
Ce qu’il vous faut sur votre ordinateur
- Votre projet à la fin du module 2, dans
~/projects/doc-assistant:python -m pytestaffiche23 passed(23 tests réussis), etpython -m doc_assistant.migratea 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.
Une soirée d’essai avec un seul plat
Section intitulée « Une soirée d’essai avec un seul plat »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.
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 brambleInes (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 v1Answer (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 da9d0f3916c83fd4b1ace0a89d593e32Lisez-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 Entitycontent-type: application/jsonx-request-id: 61bfb5970c5b495ccache-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.
Les téléversements sont des tâches avec des états
Section intitulée « Les téléversements sont des tâches avec des états »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.
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.
Sam construit la tranche
Section intitulée « Sam construit la tranche »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.
-
Enregistrez d’abord votre travail dans un commit (une version enregistrée) :
git add -Aetgit commit -m "End of Module 2". Copiez ensuite les fichiers de l’instantané par-dessus votre projet. Votre.envet votre base de données restent en place.Fenêtre de terminal cd ~/projects/doc-assistantcp -R ../nextia-learning-labs/C27/snapshots/end-of-m03/. .Fenêtre de terminal cd ~\projects\doc-assistantCopy-Item -Recurse -Force ..\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 avecgit checkout -- docs. LeREADME.mdest maintenant celui de l’instantané : il énumère les commandes de cette étape. -
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 detorch, comme l’indiquerequirements.txt.Fenêtre de terminal pip install -r requirements.txt -
Ouvrez
.env.exampleet.envcôte à côte. Copiez dans.envchaque ligne qui lui manque : les paramètres de ce module, deANSWER_PROVIDERàDEV_USER. Gardez votre mot de passe. Choisissez ensuite les deux substituts : ajoutez la ligneEMBEDDER=hashet changezANSWER_PROVIDERpourmock. Votre.envcontient alors ces deux lignes :Fenêtre de terminal EMBEDDER=hashANSWER_PROVIDER=mock -
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 dbpython -m pytestL’exécution de Sam a affiché :
.............................................................. [100%]62 passed in 3.14s -
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_packIdentity: 2 shops, 7 people, 6 membershipslarkfield: 36 documents uploaded, 0 already therebramble: 15 documents uploaded, 0 already thereIndexing with hash-384 ...Indexed 51 documents in 0.2 s (failed 0).bramble: 15 documents, 60 passages, 0 failedlarkfield: 36 documents, 185 passages, 0 failed -
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.pyLe 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.) -
Dans le premier terminal, vérifiez que l’API fonctionne et qu’elle est prête. Sur Windows, tapez
curl.exeau lieu decurl.Fenêtre de terminal curl -s http://127.0.0.1:8000/healthcurl -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"}/healthindique que le processus fonctionne./readyindique 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.
Téléverser, suivre, poser une question
Section intitulée « Téléverser, suivre, poser une question »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-hourstitle: Help desk holiday hoursversion: 1effective_from: 2026-10-11effective_to: ""owner: "Grace (support lead)"access: publiclanguage: endoc_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.-
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/documentsHTTP/1.1 202 Acceptedcontent-type: application/jsonlocation: /v1/tenants/larkfield/documents/09fd15f3-f76c-4923-b419-f726b33839afx-request-id: 80fe4d52a9c9458acache-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. -
Deux secondes plus tard, demandez le
Location. Mettez votre propredocument_iddans 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"}}} -
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/answersDans PowerShell, placez d’abord le corps dans une variable :
$body = '{"question": "Is the help desk open on 26 December?"}'. Envoyez-le ensuite aveccurl.exe -s -H "Content-Type: application/json" -d $bodyet 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.
Ce que la tranche ne fait pas encore
Section intitulée « Ce que la tranche ne fait pas encore »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 :
curl -s http://127.0.0.1:8000/v1/tenants/bramble/documentsLa 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.
Erreurs fréquentes
Section intitulée « Erreurs fréquentes »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 Conflictcontent-type: application/jsonx-request-id: 6cab6eac213b4d35cache-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.
Votre projet
Section intitulée « Votre projet »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 pytestré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_idqui 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érification des connaissances
Section intitulée « Vérification des connaissances »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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- 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é), oufailedavec 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