Le streaming améliore la perception de vitesse ; les callbacks et événements rendent l’exécution inspectable. Ces mécanismes répondent à des besoins différents. Une interface peut recevoir des tokens sans disposer d’une trace exploitable, et une application batch peut être parfaitement observée sans afficher de flux.
Que faut-il diffuser ?
Un chat simple affiche surtout les fragments de texte. Un agent doit aussi signaler des étapes compréhensibles : recherche en cours, outil terminé, validation requise ou erreur. Ne transmettez pas directement chaque événement interne au navigateur. Créez un contrat applicatif stable avec quelques types d’événements versionnés.
Callbacks et événements
Les hooks de cycle de vie permettent de réagir au démarrage, aux nouveaux tokens, aux fins d’appel, aux outils et aux erreurs. Utilisez-les pour métriques, traces ou adaptation d’interface, mais évitez d’y placer une logique métier critique difficile à rejouer. Un identifiant de corrélation doit relier requête, modèle, retriever et outils.
Gérer la fin et les erreurs
Une connexion peut tomber après plusieurs fragments. Le client doit distinguer réponse terminée, annulée et échouée. Le serveur doit annuler le travail devenu inutile, fermer les ressources et enregistrer un statut final. Persistez le message complet côté serveur plutôt que de supposer que tous les fragments sont arrivés au client.
Pression, débit et interface
Tous les fragments ne doivent pas provoquer un rendu. Regroupez-les brièvement pour limiter les mises à jour visuelles. Prenez en compte la contre-pression si le consommateur est plus lent que le producteur. Pour les outils longs, diffusez des jalons utiles plutôt que des messages artificiels qui ne reflètent pas l’état réel.
Données sensibles et traces
Les callbacks voient souvent prompts, documents récupérés, arguments d’outils et réponses. Appliquez masquage, échantillonnage, rétention et contrôle d’accès avant l’export vers une plateforme d’observabilité. N’enregistrez pas le raisonnement interne du modèle comme une donnée applicative attendue.
Checklist
- Contrat d’événements distinct de l’API du framework.
- Annulation et déconnexion testées.
- Résultat final persisté côté serveur.
- Erreurs avant et après le premier fragment couvertes.
- Métriques de premier token, durée et usage corrélées.
- Prompts et outils filtrés avant journalisation.
FAQ
Streaming réduit-il le coût ?
Non. Il change surtout la livraison ; le nombre de tokens reste déterminant.
Faut-il afficher les appels d’outils ?
Affichez une information utile et sûre, pas les arguments internes ou secrets.
Callbacks et LangSmith sont-ils identiques ?
Non. Les callbacks sont un mécanisme d’instrumentation ; une plateforme peut consommer les traces produites.
Exemple asynchrone avec événements
~~~python import asyncio from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate
prompt = ChatPromptTemplate.from_template("Résume en 3 points : {text}") chain = prompt | ChatOpenAI(model="gpt-4.1-mini")
async def main(): async for event in chain.astream_events( {"text": "Un texte long à résumer"}, version="v2", ): if event["event"] == "on_chat_model_stream": chunk = event["data"]["chunk"] print(chunk.content, end="", flush=True) elif event["event"] == "on_chain_error": print("échec", event["run_id"])
asyncio.run(main()) ~~~
Dans une API web, interrompez l’appel lorsque le client se déconnecte. Mesurez le temps avant le premier token séparément de la durée totale. Ne journalisez pas automatiquement le contenu des chunks : les flux peuvent contenir des données personnelles. Les callbacks doivent rester rapides ; envoyez les métriques vers une file plutôt que de bloquer la génération.