Streaming

Dans une interface de chat, l’utilisateur s’attend à voir la réponse apparaître tout de suite, pas à fixer un indicateur de chargement pendant de longues secondes. Ce temps de génération est réel et on ne peut pas le supprimer, mais on peut le rendre supportable. La méthode converse_stream envoie le texte au fur et à mesure de sa génération.

Le principe

Au lieu d’attendre la réponse complète, le streaming renvoie des morceaux de texte dès qu’ils sont prêts. Quand vous appelez converse_stream, vous recevez aussitôt un objet de flux qui produit des événements pendant que le modèle génère. L’attente perçue se réduit au délai avant le premier fragment, quelle que soit la longueur totale de la réponse.

L’appel

Le passage au streaming ne change presque rien :

messages = []
add_user_message(messages, "Décris en une phrase une base de données imaginaire")

response = client.converse_stream(modelId=model_id, messages=messages)

for event in response["stream"]:
    print(event)

Mêmes paramètres que converse ; seule la méthode change, et la nature du retour : response["stream"] est un itérateur d’événements. Ce code les affiche bruts. Lancez-le une fois : c’est le meilleur moyen de voir le protocole défiler avant de l’apprivoiser. Côté droits IAM, le streaming demande bedrock:InvokeModelWithResponseStream.

Les événements du flux

Chaque événement est un dictionnaire à une seule clé, qui dit son type :

1. messageStart : le début du message, avec son rôle.
2. contentBlockDelta : un fragment du bloc en cours. Il en arrive beaucoup.
3. contentBlockStop : la fin d’un bloc de contenu.
4. messageStop : la fin du message, avec la raison d’arrêt (stopReason).
5. metadata : les tokens consommés et la latence.

Avec Haiku 5.5, le message peut contenir deux blocs, comme à la leçon 4 : d’abord la réflexion, puis le texte. Les fragments de réflexion sont des contentBlockDelta dont le delta porte une clé reasoningContent, souvent une simple signature. Les fragments de réponse portent une clé text. Conséquence pratique : pendant que le modèle réfléchit, aucun texte n’arrive. Prévoyez dans votre interface un indicateur du type « réflexion en cours ».

Extraire le texte

Le cours officiel lit event["contentBlockDelta"]["delta"]["text"] pour chaque fragment. Avec un modèle qui réfléchit, ce code lève une KeyError au premier fragment de réflexion. On filtre donc les fragments qui portent du texte, et on récupère au passage la raison d’arrêt et les tokens :

response = client.converse_stream(modelId=model_id, messages=messages)

text = ""
stop_reason = None
usage = None

for event in response["stream"]:
    if "contentBlockDelta" in event:
        delta = event["contentBlockDelta"]["delta"]
        if "text" in delta:
            print(delta["text"], end="", flush=True)
            text += delta["text"]
    elif "messageStop" in event:
        stop_reason = event["messageStop"]["stopReason"]
    elif "metadata" in event:
        usage = event["metadata"]["usage"]

print("\n\nMessage complet :\n" + text)
print(stop_reason, usage)

Le flux ne se lit qu’une fois : d’où le nouvel appel en tête de ce code. end="" supprime le saut de ligne de print et flush=True affiche chaque fragment sans attendre : le texte apparaît de façon fluide. L’accumulation dans text n’est pas décorative : c’est ce message complet qu’il faut ajouter à l’historique pour le tour suivant. Afficher en direct ne dispense pas de garder la réponse.

En production

Dans une vraie application, print cède la place à un relais. Le flux décrit ici relie votre serveur à Bedrock ; il reste à transporter les fragments jusqu’au navigateur, par exemple avec des Server-Sent Events ou des WebSockets. Mettez à jour l’interface à chaque fragment, enregistrez le message complet à la fin, et gérez les coupures : une connexion peut tomber au milieu d’une génération, et l’interface doit le dire proprement au lieu de rester figée.

À vous de jouer

Le premier fragment. Mesurez avec time.perf_counter() le délai avant le premier fragment de texte, puis la durée totale de la génération, pour une question courte et pour une demande de texte long. Comparez avec la durée d’un appel converse sur la même demande.

Une fonction réutilisable. Écrivez chat_stream(messages, system=None), qui affiche la réponse en direct et renvoie le texte complet. Utilisez-la dans la boucle de conversation de la leçon 5, avec add_assistant_message après chaque réponse.

Sources officielles : Streaming (Claude Academy) · ConverseStream (documentation AWS) · Streaming Messages (documentation Claude)

Points clés à retenir

• converse_stream prend les mêmes paramètres que converse et renvoie un flux d’événements.
• Ordre des événements : messageStart, des contentBlockDelta, contentBlockStop, messageStop, metadata.
• Avec Haiku 5.5, certains fragments portent de la réflexion (reasoningContent) : ne lisez que les deltas qui ont une clé text.
• Accumulez le texte pendant l’affichage : l’historique a besoin du message complet.
• En production, relayez les fragments au navigateur et gérez les coupures.