Aller au contenu
English

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.

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

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 mainEnviron 60 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre projet ticket-desk à la fin de Pagination et formulaires. npm test se termine avec 21 vérifications réussies de l’API simulée et Tests 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écutez git -C nextia-learning-labs pull dans ~/projects pour 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.

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) :

A first version (constructed; do not use it)
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 garden

L’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 :

  1. Affichez chaque morceau dès son arrivée, pour que l’agent voie la progression et puisse arrêter le brouillon.
  2. 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.
  3. 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.

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 :

Fenêtre de terminal
curl -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: start
data: {"ticket_id":"T-80008","model":"chat-small","mode":"recorded"}
event: token
data: {"text":"I’m"}
event: token
data: {"text":" sorry"}
…
event: token
data: {"text":"."}
event: done
data: {"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)
Chaque ligne représente un flux. Le point marque le premier morceau; la barre va du premier morceau à la fin. Tout ce qui précède le point est une attente sans rien à afficher.
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.

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 :

src/api/sse.ts (part)
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 :

src/api/sse.test.ts (part)
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.

Un diagramme de séquence avec quatre participants : l'agent, DraftPanel avec useDraftStream, streamDraft (fetch, reader, SseParser) et l'API simulée. L'agent clique sur Rédiger un brouillon. Le panneau définit l'état connecting et lance streamDraft avec un AbortController. streamDraft envoie POST /v1/tickets/T-80008/draft. L'API envoie l'événement start, puis reste environ 1,8 seconde sans rien envoyer, puis envoie le premier événement token, I'm. Le panneau affiche l'état streaming et le texte s'allonge. Ensuite viennent 27 autres événements token, puis l'événement done avec le brouillon complet. Le panneau exécute checkDraft (même texte, tous les champs) et affiche l'état done avec Utiliser ce brouillon.
Un brouillon, du clic à la vérification. La longue pause vient du modèle; le rôle du panneau est d'indiquer ce qui se passe pendant ce temps.
Description textuelle du diagramme
  1. L’agent clique sur Rédiger un brouillon. Le panneau définit l’état connecting (connexion en cours).
  2. Le panneau lance streamDraft avec un AbortController, qui pourra arrêter la requête plus tard.
  3. streamDraft envoie POST /v1/tickets/T-80008/draft à l’API simulée.
  4. L’API envoie l’événement start. Ensuite, elle n’envoie rien pendant environ 1,8 seconde.
  5. Le premier événement token, « I’m » (je suis), arrive. Le panneau passe à streaming (réception en cours), et le texte commence à s’allonger.
  6. Ensuite viennent 27 autres événements token, espacés de quelques millisecondes, puis l’événement done avec le brouillon complet.
  7. 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 devient done, et Utiliser ce brouillon apparaît.

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 :

Un diagramme d'états. Du début à idle. De idle à connecting avec Rédiger un brouillon. De connecting à streaming au premier morceau de texte; de streaming à streaming au morceau suivant. Depuis streaming : done quand done arrive et que la vérification réussit; invalid quand la vérification échoue; stopped avec Arrêter; interrupted quand la connexion se termine; failed lors d'un événement error. Depuis connecting : stopped avec Arrêter, interrupted quand la connexion se termine, failed lors d'une erreur avant tout texte. Depuis chacun des cinq états de fin, Rédiger un nouveau brouillon ramène à connecting.
La machine à états de l'interface pour une requête d'IA de longue durée. Cinq états de fin, et seul done mène à Utiliser ce brouillon. Sur un téléphone, les cinq fins sont énumérées sous les états en cours.
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 :

src/features/draft/draftMachine.ts (part)
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

Commencez par « Write a draft ». Dans l’état idle, tout autre événement ne change rien.

Les huit états

  1. idle
  2. connecting
  3. streaming
  1. done
  2. stopped
  3. interrupted
  4. failed
  5. invalid
É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

(pas encore de texte)
La machine à états et la vérification du bureau des billets, avec les 28 morceaux enregistrés de T-80008. Envoyez les événements dans n'importe quel ordre : l'affichage montre l'état, le texte, les mots du panneau, les boutons de l'agent et ce qu'un lecteur d'écran entend.
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.

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 :

src/features/draft/useDraftStream.ts (part)
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.

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 :

src/api/drafts.ts (part)
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. »

  1. Dans ~/projects/ticket-desk, copiez les fichiers de cette leçon depuis l’instantané end-of-m04. Douze fichiers sont nouveaux, et TicketView.tsx change : 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-m04
    mkdir -p src/features/draft
    for 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; do
    cp "$S/$f" "$f"
    done

    Deux fichiers appartiennent à la troisième leçon de ce module. Citations.tsx affiche les sources d’un brouillon, et src/lib/errors.ts transforme les erreurs en mots simples. Le panneau a besoin des deux, alors vous les copiez maintenant. Une rétroaction digne de confiance les explique.

  2. Ouvrez src/features/draft/DraftPanel.tsx. Trouvez STATUS_TEXT, les mots des huit états, et les boutons à la fin.

  3. Vérifiez les types et exécutez les tests :

    Fenêtre de terminal
    npx tsc --noEmit
    npm test

    tsc n’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.tsx transmet de faux événements en continu au vrai panneau : un test pour chaque fin possible, et un pour un billet sans brouillon.

  4. 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 slow
    Mock 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.
  5. Dans un deuxième terminal, démarrez le bureau avec npm run dev. Ouvrez http://localhost:5173/#/tickets/T-80008.

  6. 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.

    Le panneau de brouillon d'IA de T-80008. Texte en gras : Rédaction du brouillon en cours… En dessous, les premiers mots de la réponse : Je suis désolé que vous n'ayez pas reçu de date de livraison pour votre jardin. Un bouton Stop. Une note en bas : Les brouillons proviennent d'un modèle d'IA. Ils peuvent contenir des erreurs. Vous décidez quoi envoyer.
    streaming : le texte s'allonge, et le seul bouton est Stop (mode lent). L’image est en anglais.
    Le même panneau après Stop. Texte en gras : Vous avez arrêté le brouillon. Le texte ci-dessous est incomplet. La réponse partielle est grise. Deux boutons : Write a new draft et Discard. Il n'y a pas de bouton Use this draft.
    stopped : du texte gris, des mots qui indiquent qu'il est incomplet, et aucun bouton Use this draft. L’image est en anglais.
  7. 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.

    Le panneau de T-80008 quand le brouillon est terminé. Texte en gras : Brouillon terminé. Vérifiez-le avant de l'utiliser. La réponse complète en noir : Je suis désolé que vous n'ayez pas reçu de date de livraison pour votre remise de jardin. Notre équipe de livraison peut vous aider à vérifier l'expédition et les renseignements de suivi de votre commande. En dessous : Pourquoi : Le client demande une date de livraison pour une commande qui a été expédiée. Puis : Ce brouillon n'a pas de sources. Vérifiez vous-même chaque fait qu'il contient. Trois boutons : Write a new draft, Use this draft, Discard.
    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.
  8. 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.

    Le panneau après un flux interrompu. Texte en gras : La connexion s'est terminée avant la fin du brouillon. Le texte ci-dessous est incomplet. Le texte partiel gris : Je suis désolé que vous n'ayez pas reçu de date de livraison pour votre jardin. Boutons : Write a new draft et Discard.
    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.
  9. 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. »

  10. Arrêtez l’API simulée, puis démarrez-la avec npm run api pour la prochaine leçon.

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.

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. »

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 :

src/features/draft/DraftPanel.tsx (your change)
<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é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.

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.

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.

Récapitulatif

  • Un flux envoie le brouillon par morceaux sur une seule connexion ouverte. Le bureau le lit avec fetch et un lecteur, pas avec EventSource, car le brouillon est un POST. SseParser garde 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 done propose 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