Interfaces en flux continu
- Leçon 11
- 60 min
- Module 4 : États d'interaction propres à l'IA
Où nous en sommes
Dans le module 3, le bureau a appris à charger, garder en cache et modifier les données de l'API de façon sûre. Maintenant, il rencontre le travail d'IA : un brouillon de réponse qui prend des secondes à écrire. Une longue attente, puis un brouillon peut-être coupé, inspire peu confiance. Dans cette leçon, nous affichons le brouillon pendant que le modèle l'écrit, avec un bouton Arrêter, et l'écran ne présente jamais comme terminé un brouillon arrêté ou interrompu. Un long document sur une imprimante lente montre le risque.
Leçon 11 sur 19 · Architecture frontend et performance des applications d'IAInterfaces en flux continu
1. Premiers pas avec le Web
2. Composants et structure de l'application
3. Récupération des données et gestion de l'état
4. États d'interaction propres à l'IA
5. Performance et capacité de croissance
6. Sécurité, accessibilité et remise du travail
Ce que vous saurez faire
Affichez le brouillon de l’IA de Larkfield pendant que le modèle l’écrit, avec un bouton Arrêter. Assurez-vous que l’écran ne présente jamais comme terminé un brouillon arrêté, interrompu ou en échec.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les composants, l’état et les effets avec nettoyage, vus dans Rendu et effets.
fetch, les promesses etasync/await, vus dans L’essentiel de JavaScript.- Comment le bureau des billets lit les données du serveur avec TanStack Query, vu dans Cycle de vie d’une requête. Cette leçon ne l’utilise pas pour le flux, et elle explique pourquoi.
Ce qu’il vous faut sur votre ordinateur
- Votre projet
ticket-deskà la fin de Pagination et formulaires.npm testse termine avec 21 vérifications réussies de l’API simulée etTests 22 passed (22)(22 tests réussis). Si votre projet ne fonctionne plus, copiez l’instantanéend-of-m03, comme l’indique le README des laboratoires. - Le dépôt des laboratoires dans
~/projects/nextia-learning-labs, présenté dans Installer le bureau des tickets. Exécutezgit -C nextia-learning-labs pulldans~/projectspour obtenir les fichiers les plus récents. Vous copiez les fichiers de cette leçon depuis son instantanéend-of-m04. - Node.js 24 (LTS), un terminal, VS Code et un navigateur basé sur Chromium.
Testé avec Node.js 24.18 sur macOS (Apple silicon), dans Chromium. Les commandes Windows (PowerShell) et Linux sont fournies, mais n’ont pas été testées.
Un long document à l’imprimante
Section intitulée « Un long document à l’imprimante »Vous imprimez un document de 20 pages sur une imprimante de bureau lente. Les pages sortent une à la fois. C’est utile : vous pouvez lire la page 1 pendant que la page 2 s’imprime. Vous savez aussi que l’imprimante fonctionne. Si vous voyez une erreur à la page 3, vous appuyez sur Cancel (annuler).
Trois choses peuvent alors se produire. Les 20 pages sortent, et vous vérifiez qu’il n’en manque aucune. Ou vous annulez après la page 7, et vous avez 7 pages d’un document de 20 pages. Ou le papier se bloque après la page 11, et l’imprimante s’arrête toute seule. Dans les deux derniers cas, vous avez une partie du document. Chaque page ressemble à celle du document complet. Vous ne devez pas l’agrafer et l’envoyer comme s’il était complet.
Un brouillon d’IA à l’écran se comporte comme cette imprimante. Cette leçon porte sur deux idées : afficher chaque morceau dès son arrivée, et toujours savoir comment le flux s’est terminé.
Le problème : une longue attente, puis un brouillon peu fiable
Section intitulée « Le problème : une longue attente, puis un brouillon peu fiable »Les agents de Grace ouvrent un billet de soutien et veulent la réponse suggérée par l’IA. Un vrai modèle a écrit le brouillon de T-80008 dans un cours précédent. L’API simulée le reproduit avec les délais enregistrés. Sans flux continu, l’agent ne voit rien pendant 2 secondes. D’autres brouillons enregistrés ont pris jusqu’à 11,7 secondes (la médiane des 69 brouillons est de 2 774 ms). Après quelques secondes devant un panneau vide, les agents cliquent encore ou pensent que le bureau est bloqué.
Le bureau devrait donc afficher le brouillon en flux continu : montrer chaque morceau de texte dès son arrivée. Mais un flux naïf pose un problème plus grave. Voici une première version écrite par Tomás. Elle conserve le texte et un seul indicateur loading (chargement) :
const [text, setText] = useState('');const [loading, setLoading] = useState(false);// … for each piece: setText((t) => t + piece) … when the stream closes: setLoading(false){!loading && text && <button onClick={() => onUse(text)}>Use this draft</button>}Exécutez l’API simulée en mode interrupt (interruption). Ce mode coupe volontairement la connexion après 40 % des morceaux. Cette défaillance est simulée. Le flux de T-80008 s’arrête après 11 de ses 28 morceaux. L’écran de Tomás affiche alors ce texte, sans indicateur de chargement, avec un bouton Utiliser ce brouillon :
I’m sorry you haven’t received a delivery date for your gardenL’indicateur dit « pas de chargement », alors l’écran semble avoir terminé. Un agent pressé clique sur Utiliser ce brouillon et envoie une moitié de phrase au client. Rien n’a signalé d’erreur. Un flux arrêté et un flux en échec se ressemblent aussi : le texte cesse de s’allonger.
L’idée : afficher tôt, nommer chaque fin, vérifier à la fin
Section intitulée « L’idée : afficher tôt, nommer chaque fin, vérifier à la fin »La solution comporte trois parties. Chacune répond à un des problèmes ci-dessus :
- Affichez chaque morceau dès son arrivée, pour que l’agent voie la progression et puisse arrêter le brouillon.
- Donnez un nom distinct à chaque situation. Le bureau ne demande pas « est-ce en chargement? ». Il demande « dans lequel des huit états se trouve le brouillon? ». Un brouillon arrêté, un flux interrompu et un échec sont trois états différents, avec des mots et des boutons différents.
- Vérifiez le résultat final avant que le bureau lui fasse confiance. Seul un brouillon terminé normalement et ayant réussi les vérifications obtient le bouton Utiliser ce brouillon.
Voici trois nouveaux termes. Un flux est une réponse que le serveur envoie par parties, sur une seule connexion ouverte, pendant qu’il la produit. Les événements envoyés par le serveur (SSE) sont un format texte simple pour un tel flux. Chaque partie est un petit message avec un nom et des données. Une machine à états énumère les états possibles et les seuls événements qui permettent de passer d’un état à l’autre.
Ce cours parle d’un morceau de texte, pas d’un « jeton » (token). Les modèles écrivent des jetons, souvent des parties de mots. Les trois vrais flux enregistrés dans le cours Créer des applications fiables avec les API de LLM comptaient chacun de 87 à 106 morceaux. L’API simulée découpe plutôt chaque brouillon enregistré en mots et en signes de ponctuation. T-80008 arrive donc en 28 morceaux. La taille d’un morceau n’a pas d’importance pour l’interface.
Un petit exemple : ce qui arrive, et quand
Section intitulée « Un petit exemple : ce qui arrive, et quand »Regardez le flux lui-même avant le code. Avec l’API simulée en marche (npm run api), envoyez la requête de brouillon depuis un deuxième terminal. -N indique à curl d’afficher chaque partie immédiatement :
curl -N -X POST http://127.0.0.1:8100/v1/tickets/T-80008/draft -H "Accept: text/event-stream"curl.exe -N -X POST http://127.0.0.1:8100/v1/tickets/T-80008/draft -H "Accept: text/event-stream"Voici le début et la fin de la sortie. Le brouillon est la vraie réponse enregistrée de chat-small :
event: startdata: {"ticket_id":"T-80008","model":"chat-small","mode":"recorded"}
event: tokendata: {"text":"I’m"}
event: tokendata: {"text":" sorry"}
…
event: tokendata: {"text":"."}
event: donedata: {"ticket_id":"T-80008","model":"chat-small","language":"en","needs_human":false,"reason":"The customer is asking for a delivery date for an order that has shipped.","confidence":"high","suggested_team":"delivery","reply":"I’m sorry you haven’t received a delivery date for your garden shed. Our delivery team can help check the shipment and tracking information for your order.","citations":[],"policy_answer":null,"recorded_ms":1956}Chaque événement occupe deux lignes, event: (événement) et data: (données), et se termine par une ligne vide. Il existe quatre types : start (début), token (un morceau), done (terminé, avec le brouillon complet et ses champs) et error (erreur). Le nom token vient du contrat de l’API. L’équipe du cours a chronométré chaque événement avec un petit script. L’événement start est arrivé après 2 ms, le premier morceau après 1 790 ms, et le 28e après 1 994 ms. Puis done est arrivé à 2 002 ms.
Presque toute l’attente se situe donc avant le premier morceau. Les vrais flux enregistrés suivent le même profil :
- Flux enregistrés d'un vrai modèle
- Le bureau des billets dans le navigateur (API simulée)
Description textuelle du graphique
Un graphique de quatre lignes sur un axe du temps de 0 à 2 600 millisecondes. Chaque ligne a un point au premier morceau et une courte barre jusqu’à la fin du flux. T-64704 avec chat-small, 106 morceaux : premier morceau à 1 275 ms, fin à 1 597 ms. T-64704 avec chat-strong, 87 morceaux : de 1 883 à 2 420 ms. T-80005 avec chat-small, 90 morceaux : de 2 329 à 2 506 ms. T-80008 sur le bureau des billets, mesuré dans le navigateur, 28 morceaux : premier texte à 1,817 ms et fin à 2,000 ms. Sur chaque ligne, la partie vide avant le point est beaucoup plus longue que la barre.
Les modèles raisonnent d’abord, puis écrivent vite. Pour T-64704 avec chat-small, 80 % du temps s’est écoulé avant le premier morceau. Le flux continu ne produit donc pas le brouillon plus vite. Il montre que la requête est toujours en cours. Son utilité principale est un message clair « Demande de brouillon en cours… » et un bouton Arrêter pendant la longue attente.
Lire un flux dans le navigateur
Section intitulée « Lire un flux dans le navigateur »Le navigateur offre un outil prêt à l’emploi pour les événements envoyés par le serveur : EventSource. Le bureau ne l’utilise pas pour le brouillon, pour deux raisons. EventSource peut seulement envoyer une requête GET. Le brouillon utilise POST, car il demande au serveur d’effectuer un travail. L’outil ne peut pas non plus envoyer d’en-têtes, comme l’en-tête Accept ci-dessus ou, plus tard, un jeton de connexion. Le bureau utilise donc fetch et lit le corps de la réponse morceau par morceau avec un lecteur.
Il y a un piège. Le réseau découpe les données en parties de sa propre taille, sans rapport avec les événements. Une partie peut se terminer au milieu d’un événement. Le bureau conserve donc le texte incomplet dans un tampon jusqu’à l’arrivée de la ligne vide. Voici l’analyseur dans src/api/sse.ts :
export class SseParser { private buffer = '';
/** Adds the next piece of text; gives back the events that are now complete. */ push(text: string): SseEvent[] { this.buffer += text.replace(/\r\n?/g, '\n'); const events: SseEvent[] = []; let end: number; while ((end = this.buffer.indexOf('\n\n')) !== -1) { const block = this.buffer.slice(0, end); this.buffer = this.buffer.slice(end + 2); let event = 'message'; const data: string[] = []; for (const line of block.split('\n')) { if (line.startsWith('event:')) event = line.slice(6).trim(); else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')); } if (data.length) events.push({ event, data: data.join('\n') }); } return events; }}Son test montre le piège avec toutes les valeurs visibles. Le premier envoi se termine au milieu de "Hello" (bonjour). L’analyseur ne renvoie donc pas encore d’événement. Le deuxième envoi le complète et ajoute un deuxième événement :
const p = new SseParser();expect(p.push('event: token\ndata: {"text":"Hel')).toEqual([]);expect(p.push('lo"}\n\nevent: token\ndata: {"text":" there"}\n\n')).toEqual([ { event: 'token', data: '{"text":"Hello"}' }, { event: 'token', data: '{"text":" there"}' },]);streamDraft() dans src/api/drafts.ts envoie le POST, lit le corps avec un lecteur et transmet chaque événement complet à une fonction, onEvent. Deux fins sont importantes. Le corps peut se terminer avant un événement done : la connexion s’est fermée. Ou reader.read() lance une erreur : le réseau a coupé. La prochaine section transforme les deux situations en états.
Description textuelle du diagramme
- L’agent clique sur Rédiger un brouillon. Le panneau définit l’état
connecting(connexion en cours). - Le panneau lance
streamDraftavec unAbortController, qui pourra arrêter la requête plus tard. streamDraftenvoiePOST /v1/tickets/T-80008/draftà l’API simulée.- L’API envoie l’événement
start. Ensuite, elle n’envoie rien pendant environ 1,8 seconde. - Le premier événement
token, « I’m » (je suis), arrive. Le panneau passe àstreaming(réception en cours), et le texte commence à s’allonger. - Ensuite viennent 27 autres événements
token, espacés de quelques millisecondes, puis l’événementdoneavec le brouillon complet. - Le panneau exécute
checkDraft: la réponse finale contient-elle le même texte que l’agent a vu, et tous les champs sont-ils présents? Si oui, l’état devientdone, et Utiliser ce brouillon apparaît.
Une machine à états pour un brouillon
Section intitulée « Une machine à états pour un brouillon »Revenons à l’imprimante. Trois indicateurs oui/non, « impression en cours? », « annulée? » et « papier bloqué? », pourraient indiquer simultanément « impression en cours » et « papier bloqué ». L’indicateur loading de Tomás avait la même faiblesse : deux valeurs pour au moins cinq situations.
Une machine à états évite ce problème. Le brouillon se trouve toujours dans exactement un des huit états, et chaque état a un nom clair :
| État | Ce qu’il signifie | Ce que l’agent peut faire |
|---|---|---|
idle |
Aucun brouillon n’a encore été demandé. | Rédiger un brouillon |
connecting |
La requête est envoyée; aucun texte pour l’instant. | Arrêter |
streaming |
Les morceaux arrivent. | Arrêter |
done |
Le flux s’est terminé normalement, et le brouillon final a réussi les vérifications. | Utiliser ce brouillon, Rédiger un nouveau brouillon, Supprimer |
stopped |
L’agent a appuyé sur Arrêter. Le texte est incomplet. | Rédiger un nouveau brouillon, Supprimer |
interrupted |
La connexion s’est terminée avant done. Le texte est incomplet. |
Rédiger un nouveau brouillon, Supprimer |
failed |
Le serveur a envoyé un événement error, ou rien n’est arrivé. |
Rédiger un nouveau brouillon, Supprimer |
invalid |
done est arrivé, mais le brouillon final n’a pas réussi les vérifications. |
Rédiger un nouveau brouillon, Supprimer |
Un seul état, done, propose Utiliser ce brouillon. Le diagramme montre les événements qui font passer le brouillon d’un état à un autre :
Description textuelle du diagramme
Le brouillon commence dans idle (au repos). Rédiger un brouillon le fait passer à connecting. Le premier morceau de texte le fait passer à streaming, et chaque morceau suivant l’y maintient. Il existe cinq sorties de streaming. L’événement done avec un brouillon qui réussit la vérification mène à done. Un événement done dont le brouillon échoue à la vérification mène à invalid (non valide). Arrêter mène à stopped (arrêté). Une connexion qui se termine trop tôt mène à interrupted (interrompu). Un événement error mène à failed (en échec). Avant tout texte, dans connecting, Arrêter, une connexion fermée et une erreur mènent aux trois mêmes états. Depuis chacun des cinq états de fin, Rédiger un nouveau brouillon ramène à connecting.
Dans le code, une seule fonction décide de chaque changement. On l’appelle un réducteur. Elle prend l’état actuel et un événement, appelé action, puis renvoie l’état suivant. Le hook (fonction React) useReducer de React conserve l’état et appelle le réducteur pour vous. Voici le cœur de src/features/draft/draftMachine.ts :
const active = (s: DraftStatus) => s === 'connecting' || s === 'streaming';
export function draftReducer(state: DraftState, action: DraftAction): DraftState { switch (action.type) { case 'start': return active(state.status) ? state : { ...initialDraft, status: 'connecting' }; case 'token': return active(state.status) ? { ...state, status: 'streaming', text: state.text + action.text, pieces: state.pieces + 1 } : state; case 'done': return active(state.status) ? { ...state, status: 'done', draft: action.draft } : state; case 'stop': return active(state.status) ? { ...state, status: 'stopped' } : state; case 'ended': return active(state.status) ? { ...state, status: 'interrupted' } : state; case 'fail': return active(state.status) ? { ...state, status: 'failed', problem: action.problem } : state; // 'invalid' and 'reset' follow the same pattern }}Lisez l’expression répétée active(state.status) ? … : state. Chaque événement compte seulement pendant qu’un brouillon est en cours. Un morceau qui arrive après Arrêter, ou un done tardif après une interruption, ne change rien. Cette seule règle élimine toute une famille de bogues.
Suivez maintenant trois séquences d’événements dans le réducteur, avec toutes les valeurs visibles. Les trois utilisent les morceaux de T-80008 :
| Événements | État | Texte à l’écran | Morceaux |
|---|---|---|---|
start, 28 × token, done |
done |
la réponse complète, 155 caractères | 28 |
start, 11 × token, la connexion se termine |
interrupted |
« I’m sorry you haven’t received a delivery date for your garden » (Je suis désolé que vous n’ayez pas reçu de date de livraison pour votre jardin) | 11 |
start, 8 × token, error |
failed |
« I’m sorry you haven’t received a delivery date » (Je suis désolé que vous n’ayez pas reçu de date de livraison) | 8 |
Les deux dernières lignes correspondent exactement à ce que l’API simulée envoie dans ses modes interrupt et error. Essayez les mêmes événements, et d’autres, dans l’explorateur.
Explorer
Un brouillon en flux continu : envoyez le prochain événement
Prédisez d’abord : La connexion se termine après 11 morceaux. Que doit dire le panneau, et quels boutons l'agent peut-il utiliser? Ensuite : que se passe-t-il si un événement done arrive après cela?
Commencez par « Write a draft ». Dans l’état idle, tout autre événement ne change rien.
Les huit états
idleconnectingstreaming
donestoppedinterruptedfailedinvalid
- État
idle- Morceaux à l’écran
- 0 sur 28
- Le panneau dit
- No draft yet.
- Le texte a l’air
- aucun texte
- Boutons pour l’agent
- Write a draft
- Un lecteur d’écran entend
- (rien)
Le texte à l’écran
Description textuelle de l’explorateur
L’explorateur commence dans l’état idle, sans texte, avec les mots « Aucun brouillon pour l’instant. » et un bouton Rédiger un brouillon. Huit boutons envoient le prochain événement : Rédiger un brouillon (début), Un morceau de texte, L’agent appuie sur Arrêter, La connexion se termine, Un événement d’erreur, done (le brouillon final), done, avec un brouillon défectueux, et Supprimer.
Après Rédiger un brouillon, l’état est connecting. Le panneau dit « Demande de brouillon en cours… », avec un bouton Arrêter. Chaque Un morceau de texte ajoute le prochain des 28 morceaux, et l’état est streaming. La connexion se termine après 11 morceaux donne interrupted. Les 11 morceaux restent à l’écran en gris. Le panneau dit « La connexion s’est terminée avant la fin du brouillon. Le texte ci-dessous est incomplet. ». Les boutons sont Rédiger un nouveau brouillon et Supprimer. Un événement done après cela ne change rien, car la machine ignore les événements dans un état de fin. done après les 28 morceaux donne done, avec Utiliser ce brouillon. done après moins de morceaux donne invalid, avec « Le brouillon final ne correspond pas au texte affiché. ». done, avec un brouillon défectueux donne invalid, avec « Le brouillon n’a pas de valeur de confiance. ». Un événement d’erreur donne failed, avec « Aucun brouillon. » et l’erreur en mots. Un lecteur d’écran entend une phrase quand l’état change, jamais les morceaux.
Arrêter, et ce que cela arrête vraiment
Section intitulée « Arrêter, et ce que cela arrête vraiment »Stop (arrêter) doit faire plus que changer les mots à l’écran. Il doit fermer la connexion. Sinon, le navigateur continue de lire un brouillon dont personne ne veut, et le serveur continue de l’envoyer. Le bureau utilise un AbortController, que vous avez vu dans Rendu et effets. Sa méthode abort() annule le fetch qui a reçu son signal. Voici la partie de src/features/draft/useDraftStream.ts qui démarre et arrête un brouillon :
const start = useCallback(async () => { controller.current?.abort(); // a second click stops the first draft const c = new AbortController(); controller.current = c; dispatch({ type: 'start' }); let text = ''; let finished = false; try { await streamDraft(ticketId, (e) => { /* token → dispatch token; done → checkDraft; error → fail */ }, c.signal); if (!finished) dispatch({ type: 'ended' }); // the stream closed without "done" or "error" } catch (error) { if (c.signal.aborted) return; // stop() already set the state // A network error after the first piece is an interruption; before it, a failure. dispatch(text ? { type: 'ended' } : { type: 'fail', problem: describeError(error as Error).text }); }}, [ticketId]);
const stop = useCallback(() => { controller.current?.abort(); dispatch({ type: 'stop' });}, []);Deux fonctions de React, appelées hooks, sont nouvelles dans ce code. controller vient de useRef : une boîte dont la valeur .current reste entre les rendus, sans déclencher de rendu quand elle change. useCallback conserve les mêmes fonctions start et stop d’un rendu à l’autre. Ainsi, un effet qui en dépend ne s’exécute pas de nouveau.
Le hook annule aussi la requête lors du nettoyage d’un effet, quand l’agent ouvre un autre billet de soutien. Pendant l’essai de l’équipe du cours, l’API simulée a compté "stopped_by_client": 1 après un clic sur Stop. Le serveur a vu la connexion se fermer.
Avec un vrai fournisseur, Stop ne réduit pas toujours tous les coûts : le fournisseur peut facturer le texte écrit avant l’arrêt. Diffuser les réponses en continu, dans le cours Créer des applications fiables avec les API de LLM, montre le côté serveur.
Vérifier le résultat final
Section intitulée « Vérifier le résultat final »Quand done arrive, le panneau n’affiche pas tout de suite Use this draft (utiliser ce brouillon). checkDraft() dans src/api/drafts.ts vérifie d’abord deux choses :
export function checkDraft(value: unknown, streamedText: string) { const d = value as Partial<Draft> | null; if (!d || typeof d.reply !== 'string' || typeof d.needs_human !== 'boolean' || !Array.isArray(d.citations)) { return { ok: false, problem: 'The draft is not complete.' }; } if (!['high', 'medium', 'low'].includes(String(d.confidence))) return { ok: false, problem: 'The draft has no confidence.' }; if (d.reply !== streamedText) return { ok: false, problem: 'The final draft is not the text that was shown.' }; return { ok: true, draft: d as Draft };}La première vérification porte sur la structure : chaque champ dont le panneau a besoin est présent et du bon type. La deuxième compare le reply final au texte que l’agent a vu. Use this draft copie reply. Donc, si un morceau s’est perdu en chemin, l’agent approuverait un texte et en enverrait un autre. Si l’une des vérifications échoue, l’état devient invalid : « Le brouillon n’a pas réussi les vérifications. Ne l’utilisez pas. »
Ajouter le brouillon au bureau des billets
Section intitulée « Ajouter le brouillon au bureau des billets »-
Dans
~/projects/ticket-desk, copiez les fichiers de cette leçon depuis l’instantanéend-of-m04. Douze fichiers sont nouveaux, etTicketView.tsxchange : il affiche le panneau de brouillon quand un billet a un brouillon. Cinq des nouveaux fichiers sont des tests et un utilitaire de test.Fenêtre de terminal S=../nextia-learning-labs/C22/snapshots/end-of-m04mkdir -p src/features/draftfor f in src/api/sse.ts src/api/sse.test.ts src/api/drafts.ts src/api/drafts.test.ts \src/test/stream.ts src/features/draft/draftMachine.ts src/features/draft/draftMachine.test.ts \src/features/draft/useDraftStream.ts src/features/draft/DraftPanel.tsx \src/features/draft/DraftPanel.test.tsx src/features/draft/Citations.tsx \src/lib/errors.ts src/features/tickets/TicketView.tsx; docp "$S/$f" "$f"doneFenêtre de terminal $S = "..\nextia-learning-labs\C22\snapshots\end-of-m04"New-Item -ItemType Directory -Force src\features\draft | Out-Null$files = 'src\api\sse.ts', 'src\api\sse.test.ts', 'src\api\drafts.ts', 'src\api\drafts.test.ts','src\test\stream.ts', 'src\features\draft\draftMachine.ts', 'src\features\draft\draftMachine.test.ts','src\features\draft\useDraftStream.ts', 'src\features\draft\DraftPanel.tsx','src\features\draft\DraftPanel.test.tsx', 'src\features\draft\Citations.tsx','src\lib\errors.ts', 'src\features\tickets\TicketView.tsx'foreach ($f in $files) { Copy-Item "$S\$f" $f }Deux fichiers appartiennent à la troisième leçon de ce module.
Citations.tsxaffiche les sources d’un brouillon, etsrc/lib/errors.tstransforme les erreurs en mots simples. Le panneau a besoin des deux, alors vous les copiez maintenant. Une rétroaction digne de confiance les explique. -
Ouvrez
src/features/draft/DraftPanel.tsx. TrouvezSTATUS_TEXT, les mots des huit états, et les boutons à la fin. -
Vérifiez les types et exécutez les tests :
Fenêtre de terminal npx tsc --noEmitnpm testtscn’affiche rien. Après les 21 vérifications de l’API simulée, la sortie se termine par ces lignes :Test Files 13 passed (13)Tests 35 passed (35)Les 13 nouvelles vérifications se trouvent dans quatre fichiers.
DraftPanel.test.tsxtransmet de faux événements en continu au vrai panneau : un test pour chaque fin possible, et un pour un billet sans brouillon. -
Démarrez l’API simulée en mode
slow(lent). Le mode lent est construit : un morceau toutes les 60 ms, pour vous laisser observer et appuyer sur Stop.Fenêtre de terminal node mock-api/server.mjs --stream slowMock ticket API on http://127.0.0.1:8100 (large: 10000 tickets; list=normal stream=slow jobs=normal writes=normal)AI drafts are recorded answers from earlier courses; slow and failing answers are simulated. -
Dans un deuxième terminal, démarrez le bureau avec
npm run dev. Ouvrez http://localhost:5173/#/tickets/T-80008. -
Cliquez sur Write a draft (rédiger un brouillon). « Demande de brouillon en cours… » s’affiche pendant environ 0,4 s. Puis « Rédaction du brouillon en cours… » s’affiche pendant que le texte s’allonge. Cliquez sur Stop après quelques mots.

streaming : le texte s'allonge, et le seul bouton est Stop (mode lent). L’image est en anglais. 
stopped : du texte gris, des mots qui indiquent qu'il est incomplet, et aucun bouton Use this draft. L’image est en anglais. -
Arrêtez l’API simulée avec Ctrl+C, puis redémarrez-la sans mode :
npm run api. Cliquez sur Write a new draft (rédiger un nouveau brouillon). Après environ 2 secondes, le brouillon complet apparaît.
done : le seul état avec Use this draft. La raison et les sources l'accompagnent; la troisième leçon les explique. L’image est en anglais. -
Arrêtez l’API simulée, puis démarrez-la avec
node mock-api/server.mjs --stream interrupt. Ouvrez de nouveau T-80008 et cliquez sur Write a draft. La connexion se termine après 11 morceaux.
interrupted : les mêmes 11 morceaux que la version de Tomás proposait d'envoyer, maintenant indiqués comme incomplets. L’image est en anglais. -
Arrêtez l’API simulée, puis démarrez-la avec
node mock-api/server.mjs --stream error. Cliquez encore sur Write a draft. Le panneau indique « Aucun brouillon. » et affiche un message rouge : « Le service d’IA a cessé de répondre. Votre travail est conservé. Réessayez. » -
Arrêtez l’API simulée, puis démarrez-la avec
npm run apipour la prochaine leçon.
Quand diffuser en continu, et à quel coût
Section intitulée « Quand diffuser en continu, et à quel coût »Diffusez en continu quand une personne attend et regarde la réponse : un brouillon à l’écran du soutien, ou un chat. Ne diffusez pas en continu un travail que personne ne regarde, comme la tâche en arrière-plan de la prochaine leçon. Dans ce cas, l’agent a besoin du résultat, pas des morceaux.
La diffusion en continu a des coûts :
- Huit états plutôt que deux. Chacun a besoin de mots, de boutons et d’un test. Les tests du panneau couvrent chaque fin possible.
- Plus de code. L’analyseur, le lecteur et l’annulation exigent du code dont une simple requête n’a pas besoin.
- L’écran est rendu plus souvent. Chaque morceau change l’état, alors React refait le rendu du panneau : 28 fois pour T-80008. L’équipe du cours l’a mesuré dans Mesurer dans le navigateur. Le travail de React pour un brouillon complet a pris moins de 0,01 ms. Ce n’est pas un problème. Faire lire chaque morceau à voix haute par un lecteur d’écran en est un. Interactions accessibles le résout.
- Une réponse partielle peut quand même être facturée. Stop fait gagner du temps à l’agent, mais ne réduit pas toujours le coût du fournisseur.
Kwame demande pourquoi le brouillon n’utilise pas TanStack Query, comme les autres données du serveur. Une requête met en cache une réponse terminée sous une clé. Un flux n’a pas de réponse terminée avant la fin, et c’est l’agent qui le démarre et l’arrête. Le flux a donc son propre hook.
Erreurs courantes
Section intitulée « Erreurs courantes »Erreur courante
Stop change les mots, mais le brouillon continue d'arriver
Symptôme (construit) : après Stop, le panneau indique « Vous avez arrêté le brouillon ». Mais dans le panneau Network (réseau), la requête draft reste ouverte jusqu’à la fin. Les compteurs de l’API simulée à http://127.0.0.1:8100/admin/stats montrent que "completed" augmente, et que "stopped_by_client" reste à 0.
Cause : stop() a envoyé { type: 'stop' }, mais n’a pas appelé controller.current?.abort(). Le réducteur ignore les morceaux tardifs, alors l’écran semble correct. Le navigateur télécharge quand même tout le brouillon, et un vrai fournisseur continue de l’écrire et de le facturer.
Correction : un bouton Stop doit annuler la requête (abort()) et définir l’état. Le test du panneau « Stop termine le flux » le vérifie avec openStream(). Ce faux flux se termine seulement quand le signal de la requête est annulé.
Conséquence dans le travail en IA : chaque brouillon arrêté coûte le prix de la réponse complète.
Erreur courante
Une erreur réseau avant le premier morceau affiche un brouillon gris vide
Symptôme (construit) : l’API simulée ne fonctionne pas. Le panneau indique que la connexion s’est terminée et que « Le texte ci-dessous est incomplet », mais il n’y a aucun texte.
Cause et correction : une interruption n’a de sens que si du texte est arrivé. Le hook décide selon le texte : dispatch(text ? { type: 'ended' } : { type: 'fail', problem: … }). Sans texte, le panneau indique « Aucun brouillon. » et « Le service de billets n’a pas répondu. Vérifiez votre connexion, puis réessayez. »
À vous de jouer : compter les morceaux
Section intitulée « À vous de jouer : compter les morceaux »Changez une chose à l’écran. Pendant la diffusion du brouillon, le panneau indique seulement « Rédaction du brouillon en cours… ». Faites-lui indiquer le nombre de morceaux reçus, par exemple « Rédaction du brouillon en cours… (12 morceaux jusqu’ici) ». Avant de changer le code, prévoyez : de quelle valeur de l’état avez-vous besoin, et faut-il changer le réducteur? Puis démarrez l’API simulée avec --stream slow et vérifiez votre changement sur T-80008.
Afficher la réponse
Le réducteur compte déjà les morceaux dans state.pieces, alors il ne change pas. Seul le panneau change. Dans DraftPanel.tsx, remplacez le paragraphe qui a la classe draft-state :
<p className="draft-state"> {STATUS_TEXT[state.status]} {state.status === 'streaming' && ` (${state.pieces} pieces so far)`}</p>En mode lent, le compte passe de 1 à 28, soit environ 16 morceaux par seconde. npx tsc --noEmit n’affiche rien, et les tests réussissent encore : aucun test ne vérifie les mots de l’état streaming. L’instantané ne contient pas ce changement, et les prochaines leçons n’en dépendent pas.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Dans le flux enregistré de T-64704 avec chat-small, le premier morceau est arrivé après 1 275 ms. Le flux s'est terminé à 1 597 ms. Qu'est-ce que la diffusion en continu améliore pour l'agent, et qu'est-ce qu'elle n'améliore pas?
Afficher la réponse
Elle améliore ce que l’agent voit pendant l’attente. Le panneau indique « Demande de brouillon en cours… », le premier texte apparaît vers 1,3 s, et l’agent peut appuyer sur Stop à tout moment. Elle ne rend pas le brouillon plus rapide. 80 % du temps s’est écoulé avant le premier morceau, pendant que le modèle travaillait. Le brouillon complet a quand même pris environ 1,6 s. Le brouillon ne peut être utilisé qu’après la fin, une fois la vérification finale réussie.
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évoyez : l'API simulée est en mode interrupt, et le flux de T-80008 s'arrête après 11 morceaux. Puis, à cause d'un réseau lent, un événement done arrive avec le brouillon complet. Qu'affiche le panneau, et pourquoi?
Afficher la réponse
Le panneau affiche l’état interrupted : les 11 morceaux en gris, « La connexion s’est terminée avant la fin du brouillon. Le texte ci-dessous est incomplet. », et les boutons Write a new draft et Discard (rejeter). Le done tardif ne change rien, car le réducteur accepte les événements seulement dans connecting et streaming. Même s’il avait accepté le done, la vérification échouerait. La réponse finale est plus longue que les 11 morceaux vus par l’agent, alors le résultat serait invalid.
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
Tomás propose de remplacer les huit états par deux indicateurs, loading et error. Donnez deux situations que ces indicateurs ne peuvent pas distinguer, et dites ce que l'agent verrait de faux.
Afficher la réponse
Un brouillon arrêté par l’agent et un brouillon dont la connexion s’est terminée aboutissent tous deux à « aucun chargement, aucune erreur ». Le panneau afficherait les deux comme terminés, avec Use this draft, et l’agent pourrait envoyer une demi-réponse. Un brouillon arrivé complet, mais qui a échoué à la vérification finale, semble aussi correspondre à « aucun chargement, aucune erreur ». La machine à états donne à chaque situation son propre état, ses propres mots et ses propres boutons. Seul done propose Use this draft, et les tests vérifient chaque fin possible.
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
- Un flux envoie le brouillon par morceaux sur une seule connexion ouverte. Le bureau le lit avec
fetchet un lecteur, pas avecEventSource, car le brouillon est unPOST.SseParsergarde un événement partiel jusqu’à l’arrivée de sa fin. - La majeure partie de l’attente précède le premier morceau : 1 790 sur 2 002 ms pour T-80008. Un message clair « Demande de brouillon en cours… » et Stop sont les plus importants.
- Une machine à états donne au brouillon exactement un des huit états, avec des mots et des boutons différents. Seul
donepropose Use this draft, et les événements après la fin ne changent rien. - Stop annule la requête et définit l’état. Vérifiez le résultat final : sa structure, et la correspondance avec le texte que l’agent a vu.
Ensuite, le travail d’IA d’un nouveau billet s’exécute en arrière-plan pendant quelques secondes. Le bureau le suit, d’abord en demandant des nouvelles chaque seconde, puis avec des événements du serveur.
Leçon suivante : Traitement en arrière-plan