Aller au contenu
English

Travail final

  • Après les études de cas
  • environ 3 h

Où nous en sommes

Dans ce cours, vous avez rendu fiable sous la charge un service d'IA lent et limité par un quota : mesurer d'abord, utiliser l'attente, mettre en cache avec soin, placer le travail lent dans une file, contenir les défaillances et rendre compte honnêtement. Maintenant, l'assistant documentaire vit une journée de publication des politiques. Dans ce travail, vous placez par vous-même son travail d'IA lent dans une file d'attente bornée, et vous prouvez ce qu'il peut supporter.

Ce que vous saurez faire

Appliquez chaque module du cours à une tâche que vous n’y avez pas créée. Déplacez le travail d’IA lent d’un deuxième service de Larkfield dans une file d’attente bornée en arrière-plan. Puis prouvez quatre choses avec des tests de charge et des exécutions consignées. Vous savez ce que le service peut supporter, et pourquoi. Un message répété produit un seul effet. Une surcharge donne une réponse claire, plutôt qu’une accumulation sans fin. Et votre rapport indique ce que vos tests ne permettent pas de dire sur la production.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 180 minutes
  • Vous avez terminé les modules 1 à 6. Chaque partie ci-dessous nomme les leçons qu’elle utilise.
  • Les études de cas ne sont pas nécessaires pour ce travail. Le certificat en exige au moins une.
  • Le service : votre docs-assistant du travail final du cours Bases de données et stockage pour les applications d’IA. Si vous ne l’avez pas, créez d’abord son noyau minimal : des documents avec des versions et un fichier stocké, et des segments avec un vecteur et une version de plongement. Vous n’avez pas besoin ici d’optimiser les index ni de faire l’exercice de restauration de ce travail.
  • Ou une autre tâche de Larkfield, si vous préférez. Elle doit être nouvelle, et non la réception de billets de ce cours. Elle doit appeler le fournisseur pour au moins une étape de clavardage et une étape de plongement. Certaines tâches doivent comporter plusieurs étapes. Par exemple, un résumé nocturne des billets ouverts de chaque client, avec un plongement de chaque résumé. Indiquez dans votre rapport le service choisi. Les étapes ci-dessous utilisent l’assistant documentaire; adaptez les noms à votre tâche.
  • Le projet du cours, comme source de code : votre ticket-api à la fin du module 6, ou l’instantané end-of-m06 (voir les instantanés). Vous pouvez en copier du code : le fournisseur simulé simulator/, ticket_api/jobs.py, worker.py, ratelimit.py, resilience.py, loadtest/shapes.py, et les scripts percentiles, machine, queue_watch, compare et cost. Indiquez dans votre rapport ce que vous avez copié et modifié. Ne copiez pas les routes des billets en les renommant : le réviseur cherche les décisions nécessaires à ce service.
  • Docker avec PostgreSQL 18 et pgvector, Azurite et Valkey, comme dans le cours. Le fournisseur d’IA est celui du cours, simulé. Aucun compte ni paiement n’est nécessaire.
  • Chaque test de charge de ce travail cible vos propres services sur votre propre ordinateur. Ne dirigez jamais un test de charge vers un vrai fournisseur d’IA ni vers un service qui ne vous appartient pas.
  • Vous pouvez faire ce travail en plusieurs séances. Exécutez les tests après chaque changement.

La situation : une journée de publication des politiques

Section intitulée « La situation : une journée de publication des politiques »

Les agents du service de soutien posent des questions à l’assistant documentaire pendant qu’ils traitent des billets. Ses réponses proviennent des documents de politiques de Larkfield, découpés en segments ayant chacun un plongement (embedding). Créer les segments d’une nouvelle version de document est un travail lent qui attend le fournisseur. Un long document comporte beaucoup de segments, et chaque segment a besoin d’un plongement.

Omar présente la nouvelle charge de travail. La veille du Vendredi fou, l’équipe des politiques publie de nouvelles versions de nombreux documents à la fois : retours, délais de livraison, remboursements. Un script les téléverse tous en quelques minutes. L’assistant peut citer une nouvelle version seulement quand ses segments et ses vecteurs existent. L’équipe des politiques veut aussi un court résumé de chaque version, rédigé par le modèle, pour la page de nouvelles du service de soutien.

Kwame pose ses questions habituelles : « Combien ça va coûter, et quelle est la limite? » Mei surveille ses connexions à la base de données. Tomás a déjà dit deux fois : « Ajoutez des processus. »

Après ce travail, un téléversement est enregistré immédiatement et reçoit la réponse 202 Accepted (accepté). Une tâche dans une file PostgreSQL effectue le travail d’IA plus tard, dans un processus distinct :

  • Découper la version du document en segments (sans appel au fournisseur).
  • Résumer la version : un appel de clavardage à chat-small.
  • Créer les plongements de chaque segment : un appel à embed-small par segment, ou par lot de segments si vous choisissez des lots.

Vos données. Utilisez les 36 documents de politiques dans data/source/documents/ de votre ticket-api (Markdown, CC0). Écrivez un script avec une graine aléatoire fixe qui crée de nouvelles versions légèrement modifiées pour vos tests de charge. Toutes les données sont inventées : dites-le dans votre rapport.

Votre fournisseur. Exécutez le fournisseur simulé du cours. Son quota de clavardage est de 100 requêtes par minute, et son quota de plongement est de 100 000 jetons par minute. Ces quotas proviennent du compte réel. Le simulateur calcule le temps de votre résumé comme celui d’un brouillon de réponse, car il ne connaît pas votre requête. Dites-le partout où vous présentez le temps d’un résumé.

Utilise Exécuter la charge de travail d’IA sur votre ordinateur, Modèle de charge de travail, Latence et capacité, Trouver le goulot d’étranglement et Limites des dépendances.

  1. Écrivez le modèle de charge de travail dans docs/workload.md. Indiquez ce qui arrive : les téléversements et les questions que les agents posent en même temps. Précisez leur fréquence un jour normal et le jour de publication des politiques. Donnez la minute la plus chargée et le facteur multiplicatif prévu, en justifiant chaque nombre.
  2. Mesurez une tâche exécutée seule, avec le fournisseur simulé : le temps de chaque étape, le nombre de segments et les jetons de chaque appel. Utilisez au moins 10 documents de longueurs différentes. Présentez la médiane et le temps le plus lent, pas seulement la moyenne.
  3. Calculez ce que chaque limite permet, en tâches par minute, en montrant tous les nombres. Faites-le pour le quota de clavardage (un résumé par tâche), le quota de plongement (les jetons des segments d’une tâche) et les processus (tâches simultanées ÷ durée d’une tâche). Additionnez les connexions à la base de données de tous les processus. Indiquez quelle limite est atteinte en premier, et à quelle charge de travail.
  4. Calculez le coût d’IA d’une tâche et du jour de publication des politiques à partir des nombres de jetons et des prix datés dans prices.py. Précisez que les prix changent.
  5. Donnez une lettre à chaque hypothèse, comme dans Recommandation de capacité. Chaque affirmation faite ensuite dans votre rapport nomme les lettres sur lesquelles elle repose.

Partie 2 : une file d’attente bornée en arrière-plan

Section intitulée « Partie 2 : une file d’attente bornée en arrière-plan »

Utilise Travail d’E/S et travail de calcul, Cycle de vie d’une tâche et Contre-pression.

  1. Ajoutez une table jobs avec une migration. Enregistrez la version du document et sa tâche dans une seule transaction. Il ne doit jamais y avoir une version sans sa tâche, ni une tâche sans sa version. Le téléversement reçoit 202, avec l’adresse de la tâche dans Location (emplacement).
  2. Ajoutez un processus qui réserve les tâches avec FOR UPDATE SKIP LOCKED et un bail. Donnez aux tâches les états du cours, ou expliquez chaque état que vous modifiez. Ajoutez GET /v1/jobs/{id}, une route d’annulation pour une tâche en file d’attente (409 conflict, conflit, sinon), et GET /v1/queue. La route de la file affiche les tâches en attente, prêtes et en cours, les messages non traitables et l’âge de la plus ancienne tâche.
  3. Tant que sa tâche n’a pas réussi, une nouvelle version ne peut pas être trouvée par recherche. L’assistant continue de citer la version publiée précédente. Indiquez comment un lecteur peut savoir qu’une version plus récente attend.
  4. Bornez la file d’attente. Choisissez QUEUE_MAX selon l’attente maximale que vous pouvez promettre à l’équipe des politiques, pas selon l’espace dans la base de données. Montrez le calcul. Quand la file est pleine, répondez 503 queue_full (file pleine) avec un Retry-After (délai avant une nouvelle tentative) fondé sur le rythme réel, sans rien enregistrer.
  5. Ajoutez une limite de requêtes par appelant, avec 429 rate_limited (limite de requêtes atteinte) et Retry-After. Ainsi, un seul script ne peut pas remplir la file pour tout le monde.
  6. Donnez à chaque téléversement accepté une estimation de son attente. Indiquez l’erreur possible de cette estimation au début d’une rafale.

Utilise Livraison et nouvelles tentatives, Contenir les défaillances et Arrêt en douceur.

  1. Acceptez un Idempotency-Key (clé d’idempotence) sur le téléversement, pour chaque appelant. Une répétition avec le même corps renvoie la même version et la même tâche, avec Idempotent-Replayed: true (requête idempotente répétée). La même clé avec un autre corps reçoit 422. Quand deux copies arrivent en même temps, un index unique tranche, pas une vérification en Python.
  2. Enregistrez immédiatement le résultat de chaque étape, avec l’identifiant de la tâche, selon une règle d’unicité. Il faut un résumé par tâche et une ligne de segment par tâche et position de segment. Avant une étape, le processus saute ce qui est déjà enregistré. Une deuxième livraison ne doit ajouter ni segment, ni vecteur, ni résumé.
  3. Retentez ce qui pourrait fonctionner la prochaine fois, avec un délai d’attente croissant exponentiel, de la gigue et un nombre maximal de tentatives. Ensuite, placez la tâche parmi les messages non traitables. Marquez immédiatement comme failed (échoué) une erreur qu’une nouvelle tentative ne peut pas corriger. Un 429 du fournisseur fait attendre la tâche sans consommer de tentative.
  4. Fixez le délai maximal du fournisseur à partir de votre appel mesuré le plus lent, avec une marge. Ajoutez un disjoncteur devant le fournisseur. Quand il est ouvert, les tâches attendent sans consommer de tentatives.
  5. Gérez SIGTERM : ne prenez aucune nouvelle tâche et laissez les tâches en cours se terminer pendant un délai inférieur au délai de grâce de votre plateforme. Puis remettez les tâches inachevées dans la file sans consommer de tentative.
  6. Mesurez votre tâche la plus longue. Un document avec beaucoup de segments prend beaucoup plus de temps qu’un billet. Si une tâche peut dépasser son bail, ajoutez un signal périodique qui prolonge le bail, ou découpez-la en tâches plus petites. Indiquez votre choix et sa raison.

Partie 4 : tests de charge et recommandation de capacité

Section intitulée « Partie 4 : tests de charge et recommandation de capacité »

Utilise Mise à l’échelle horizontale, Signaux de mise à l’échelle, Concevoir un test de charge, Comparer les configurations et Recommandation de capacité.

  1. Écrivez les quatre parties de chaque test avant de l’exécuter : la question, la charge de travail de la partie 1, le profil de charge, et l’environnement avec ses mesures. Réinitialisez les données, videz le cache et redémarrez le fournisseur simulé avant chaque passage. Consignez python -m scripts.machine avant et après chaque exécution.
  2. Exécutez un test de référence de base stable au rythme d’un jour normal, puis une rafale correspondant à la minute la plus chargée du jour de publication. Relevez deux types de temps : la réponse au téléversement (p50, p95, p99) et le temps entre la soumission et le résultat de chaque tâche. Relevez la file chaque seconde : sa longueur et sa plus ancienne tâche.
  3. Exécutez un test de surcharge au-delà de la limite, comme dans Contre-pression. Comptez les téléversements acceptés, refusés et perdus, les valeurs de Retry-After et le maximum atteint par la file.
  4. Comparez deux configurations qui diffèrent par un seul réglage, avec au moins trois passages chacune. Par exemple, un processus contre deux, ou un lot de 16 segments par appel de plongement contre un segment par appel. Présentez la médiane et l’étendue de chaque colonne de la fiche de résultats. Dites « aucune différence démontrée » quand les étendues se chevauchent.
  5. Choisissez un signal de mise à l’échelle du processus à partir de vos exécutions, avec son minimum et son maximum. Indiquez ce que des processus supplémentaires peuvent corriger, et ce qu’ils ne peuvent pas corriger.
  6. Écrivez docs/capacity-report.md. Il contient la question, la charge de travail, vos mesures et une amélioration démontrée, avec les résultats avant et après. Il contient aussi le coût et le prochain goulot d’étranglement, avec les mesures à prendre avant le prochain changement. Ajoutez une section « Ce que ce test ne permet pas de dire ».

Aucune affirmation de capacité en production à partir d’un test sur un portable. Votre rapport ne doit pas dire combien de téléversements la production peut supporter. Il ne doit pas non plus prédire la vitesse du fournisseur réel le jour de publication des politiques. Vous avez mesuré un ordinateur, le fournisseur simulé, des données inventées et de courtes exécutions. Les affirmations sur les profils de charge et les comparaisons sont acceptables, avec leurs conditions. Par exemple : « avec une limite de 50, une surcharge n’a perdu aucun téléversement » ou « le quota de clavardage est atteint en premier ». Un nombre absolu pour la production ne l’est pas. Si quelqu’un en a besoin, votre rapport indique quelle exécution réelle doit le mesurer.

Un parcours normal qui fonctionne ne suffit pas. Montrez chacun de ces cas avec un test ou une exécution consignée, et indiquez lequel. Chaque exécution cible vos propres services sur votre propre ordinateur. Identifiez chaque cas construit comme tel.

  1. Le même téléversement envoyé deux fois avec un seul Idempotency-Key donne une version et une tâche. La deuxième réponse contient Idempotent-Replayed: true. Un autre corps avec la même clé reçoit 422.
  2. Un processus plante au milieu d’une tâche, après l’enregistrement de certains segments (cas construit). La tâche est livrée de nouveau après son bail. À la fin, chaque position de segment a exactement une ligne et un vecteur, et le résumé est enregistré une fois. Consignez les appels au fournisseur de la tâche et expliquez chaque appel répété.
  3. Une file pleine répond 503 queue_full avec un Retry-After, sans enregistrer de version. Un appelant qui dépasse sa limite reçoit 429 rate_limited, tandis que les autres reçoivent encore 202.
  4. Quand le quota du fournisseur est épuisé (python -m simulator --mode quota le rend 10 fois plus petit), les tâches attendent. Elles ne consomment aucune tentative et ne deviennent pas des messages non traitables.
  5. Une panne simulée ouvre le disjoncteur. Comptez les appels qui ont atteint le fournisseur pendant la panne. Après la panne, les tâches en attente réussissent. Avec le disjoncteur désactivé (cas construit), montrez que les tentatives s’épuisent, puis relancez volontairement un message non traitable.
  6. Un SIGTERM pendant une longue tâche remet celle-ci dans la file, sans changer ses tentatives et en conservant ses étapes enregistrées. Après un SIGKILL (cas construit), la tâche reste running (en cours) jusqu’à la fin de son bail. Un autre processus la termine ensuite sans doublon.
  7. Sans processus de traitement actif, les téléversements reçoivent encore 202. Montrez la mesure qui vous l’indique : l’âge de la plus ancienne tâche augmente, et rien ne se termine.
  8. Les connexions de tous vos processus d’API et de traitement restent ensemble sous la limite de la base de données. Montrez la somme pour votre plus grande configuration, avec la taille de chaque pool de connexions (pool).

Avant de soumettre, prouvez que le projet fonctionne à partir de zéro, sur votre ordinateur :

  1. Copiez le projet dans un nouveau dossier, sans .venv, .env ni vos sorties d’exécution.
  2. Supprimez la base de données et les fichiers avec docker compose down --volumes. Puis redémarrez PostgreSQL, Azurite et Valkey.
  3. Créez un nouvel environnement virtuel, installez les dépendances de requirements.txt et créez .env à partir de .env.example.
  4. Appliquez les migrations, chargez les données et exécutez tous les tests.
  5. Démarrez le fournisseur simulé, l’API et un processus de traitement. Téléversez un document, suivez sa tâche jusqu’à succeeded (réussi), puis exécutez une fois votre vérification des doublons (cas de défaillance 2).

Collez les commandes et leurs sorties dans votre rapport. Si une étape nécessitait quelque chose d’absent du README, corrigez le README et recommencez les étapes.

Votre dossier de projet (sans .env, .venv ni les sorties d’exécution volumineuses), avec vos migrations, votre code, vos tests, vos fichiers de tests de charge, vos scripts, docs/workload.md, docs/capacity-report.md, vos fiches de résultats remplies et REPORT.md :

# Larkfield document assistant: background ingestion under load
## Workload and assumptions (the workload model, one job measured alone, each limit in jobs per
minute, the cost, the lettered assumptions)
## The queue (the jobs table, one transaction, states and routes, the bound and its
arithmetic, the rate limit, the wait estimate)
## One effect per message (idempotency keys, saved steps and their unique rules, retries, 429
handling, timeout, breaker, drain, lease or heartbeat)
## Load-test evidence (each test's four parts, the machine and its load, the baseline, the
burst, the overload, the comparison with medians and ranges)
## Capacity recommendation (the improvement, the next bottleneck, what this test does not say)
## Failure paths (each of the eight, with the test or the run that shows it)
## Fresh-environment run (the commands and their outputs)
## Limits (simulated provider, made-up data, your computer, what you copied,
what you did not test)

Un réviseur évalue chaque élément requis comme démontré, partiellement démontré ou pas encore démontré, avec une raison concrète. Pour terminer le cours, vous devez démontrer les quatre éléments. Vous pouvez améliorer un élément et le soumettre à nouveau.

Élément requis Démontré Partiellement démontré, par exemple Pas encore démontré, par exemple
Hypothèses de capacité La charge de travail comporte des chiffres et des justifications. Une tâche est mesurée seule, avec les médianes et le temps le plus long. Chaque limite est calculée en tâches par minute, et la première limite atteinte est nommée. Le coût utilise le nombre de jetons et des prix datés. Chaque affirmation précise ses hypothèses. Les limites sont calculées, mais le quota de plongements ou les connexions à la base de données manquent. Ou le temps de la tâche provient d’une seule exécution. Aucune charge de travail précisée : « dix fois plus », sans chiffres. Ou le rapport transforme un résultat sur un portable en chiffre de production.
Preuves des tests de charge Chaque test précise sa question, sa charge de travail, son profil et son environnement. La charge de la machine est consignée. Le test en rafale rapporte le temps entre la soumission et le résultat, pas seulement le 202 (accepté). La comparaison modifie un seul réglage, avec au moins trois passages, des médianes et des étendues. Quand les étendues se chevauchent, elle indique « aucune différence démontrée ». Les tests ont été exécutés, mais avec un seul passage chacun. Ou seul le temps de réponse au téléversement a été mesuré. Ou la charge moyenne manque. Aucun test de charge, ou un test de charge sur un service qui ne vous appartient pas. Ou deux réglages ont changé entre les exécutions comparées.
Traitement des tâches sans effets en double Une requête répétée et une livraison répétée ne produisent chacune qu’un effet. Un test et une exécution consignée le montrent, et les règles d’unicité de la base de données l’imposent. Un 429 (trop de requêtes) ne compte pas comme une tentative. Les nouvelles tentatives sont limitées, avec mise à l’écart des messages en échec définitif. Le coupe-circuit, le drainage et le bail ou le signal de vie sont en place. La tâche la plus longue est mesurée. Un seul effet par message, mais un 429 compte comme une tentative. Ou la tâche la plus longue peut dépasser son bail, et rien ne gère ce cas. Une deuxième livraison ajoute des segments, des vecteurs ou un deuxième résumé. Ou la clé d’idempotence est globale, permettant à un appelant de rejouer le téléversement d’un autre.
Limites explicites et comportement en surcharge La file d’attente a une limite choisie selon un temps d’attente promis, avec le calcul. En surcharge, le service répond 503 queue_full (file pleine) ou 429 rate_limited (débit limité), avec un Retry-After (délai avant une nouvelle tentative) réaliste. Il n’enregistre rien de ce qu’il refuse et ne perd rien de ce qu’il accepte. Le nombre de processus a un maximum, et les connexions restent sous la limite de la base de données. La limite fonctionne, mais Retry-After est un nombre fixe. Ou la limite n’a aucune justification, ou sa condition de concurrence n’est pas mentionnée. La file d’attente n’a aucune limite, donc une longue rafale fait croître indéfiniment les tâches en attente. Ou un téléversement refusé est partiellement enregistré.

Même si le reste est solide, le travail reste incomplet tant qu’une livraison en double produit deux effets. Il reste aussi incomplet si la surcharge n’est pas limitée. Un 202 rapide ne compense pas un deuxième ensemble de vecteurs ni une file d’attente sans limite. Une phrase qui transforme un test sur portable en capacité de production fait échouer l’élément où elle apparaît.

Les résultats du cours peuvent vous aider à juger les vôtres, mais ce ne sont pas des cibles. Dans Contre-pression, une limite de 100 a permis d’accepter de 172 à 173 billets de soutien sur 300. Le service en a refusé de 127 à 128, avec un Retry-After de 88 à 128 secondes. La file d’attente a atteint un maximum de 107. Dans Livraison et nouvelles tentatives, une tâche livrée deux fois a laissé 3 résultats d’IA et fait 3 appels au fournisseur. Le processus naïf en a produit 6 de chaque. Dans Contenir les défaillances, le coupe-circuit a réduit les appels de 150 à 8 pendant une panne de 20 secondes. Votre service, ses tâches et votre ordinateur sont différents.

Erreur courante

Un long document est traité deux fois

Symptôme : les documents courts se terminent à la tentative 1, mais les plus longs se terminent à la tentative 2. Le compteur du fournisseur montre plus d’appels de plongement que de segments. Pourtant, la table des segments contient une seule ligne par position.

Cause : la tâche a duré plus longtemps que son bail. Dans le cours, la tâche d’un billet prenait environ 2,2 secondes, bien moins que le bail de 30 secondes. Un document avec de nombreux segments peut prendre beaucoup plus de temps, surtout quand le quota fait attendre certains appels. À l’expiration du bail, un autre processus prend la tâche alors que le premier travaille encore dessus. Vos règles d’unicité ont empêché les lignes en double, mais les deux processus ont payé certains appels.

Solution : mesurez la tâche la plus longue sous charge, pas seule. Ajoutez ensuite un signal de vie qui prolonge locked_until (verrouillé jusqu’à) tant que le processus progresse. Ou divisez la tâche en lots de segments, avec une tâche par lot. Vérifiez à nouveau avec le document le plus long dans une rafale. Comparez les appels au fournisseur avec les segments.

Récapitulatif

Dans ce cours, vous avez rendu un service d’IA lent et limité par des quotas fiable sous charge :

  • Mesurer d’abord : un modèle de charge de travail chiffré, des centiles plutôt que des moyennes et un goulot d’étranglement trouvé en décomposant le temps.
  • Profiter de l’attente : des appels asynchrones pour le travail d’E/S, davantage de processus seulement si les limites le permettent, et la somme de chaque réglage par processus.
  • Utiliser le cache avec soin : des clés qui incluent tout ce qui change la réponse, y compris l’identité de l’appelant; une invalidation par générations; et un cache qui laisse passer les requêtes en cas de panne.
  • Mettre le travail lent en file d’attente : des tâches enregistrées avec leurs données dans une seule transaction, un effet par message, des nouvelles tentatives limitées, des messages mis à l’écart après échec définitif et une limite avec un Retry-After réaliste.
  • Contenir les défaillances : des délais d’expiration fondés sur des mesures, un coupe-circuit, un signal de mise à l’échelle auquel davantage de processus peuvent remédier et un drainage à chaque arrêt.
  • Rapporter honnêtement : des comparaisons équitables avec plusieurs passages et des étendues, et une recommandation qui précise ce que le test ne démontre pas.

Si vous n’en avez pas encore fait, choisissez une étude de cas pour le certificat : Plan de capacité à partir d’une trace de trafic publique ou File d’attente et cache pour une API de données ouvertes.