Streaming SSE avec Django et API OpenAI : Guide pratique

Dans le monde des applications propulsées par l'IA, la différence entre une expérience utilisateur fluide et une expérience statique réside souvent dans la capacité à restituer les données en streaming. Les Server-Sent Events (SSE) sont un protocole qui permet au serveur d'envoyer des mises à jour incrémentales au client, rendant possible l'affichage des réponses d'un modèle de langage mot par mot, au lieu d'attendre la fin de toute la génération. Dans ce guide, nous explorerons comment configurer un endpoint Django qui diffuse les réponses d'une API compatible avec OpenAI.

Qu'est-ce que le streaming SSE et pourquoi l'utiliser

Le streaming SSE exploite la connexion HTTP persistante pour envoyer des événements textuels du serveur vers le navigateur, en utilisant un format simple basé sur des lignes de texte séparées par des doubles sauts de ligne. Contrairement aux WebSocket, SSE est unidirectionnel (serveur-to-client), ce qui le rend idéal pour des scénarios comme la complétion textuelle, où le client envoie une requête et reçoit un flux continu de chunks.

Les avantages sont évidents : le premier token apparaît en quelques millisecondes, l'utilisateur voit le texte apparaître en temps réel, et la complexité de gestion de la connexion est minimale. Pour les applications chatbot ou assistants IA, cette perception d'immédiateté fait la différence entre un produit apprécié et un produit frustrant.

Configuration de l'endpoint Django

Pour activer le streaming dans Django, nous devons répondre avec un générateur Python qui envoie des chunks progressivement. La clé est d'utiliser StreamingHttpResponse avec l'en-tête Content-Type: text/event-stream et de désactiver la mise en cache et le buffering HTTP. Voici la structure de base de l'endpoint :

• Définir une vue qui accepte la requête et transmet le prompt au service IA
• Itérer sur le flux de réponse et encapsuler chaque chunk dans le format SSE
• Retourner un StreamingHttpResponse avec les bons en-têtes

Il est fondamental de gérer les timeouts et les erreurs réseau, car une connexion SSE interrompue ne se rétablit pas automatiquement comme c'est le cas pour les WebSocket. Un bon pattern prévoit un try-except qui envoie un événement error au client en cas de défaillance.

Intégration avec les API OpenAI-compatible

La plupart des fournisseurs IA modernes — OpenAI, Anthropic, Azure OpenAI, mais aussi des solutions self-hosted comme Ollama ou vLLM — supportent le paramètre stream=True dans les requêtes de complétion. Dans Django, nous pouvons nous appuyer sur la bibliothèque openai ou sur httpx pour effectuer des appels en streaming, ou bien utiliser requests avec stream=True et lire le flux ligne par ligne.

Chaque chunk reçu du fournisseur contient généralement un champ delta avec le texte partiel. Notre générateur Django doit transformer chaque chunk dans le format SSE standard : une ligne data: contenant le texte, suivie d'une ligne vide pour délimiter l'événement. Cette approche garantit la meilleure compatibilité avec les clients JavaScript utilisant l'objet natif EventSource.

Frontend et gestion des événements

Côté client, il suffit d'initialiser une nouvelle instance de EventSource pointant vers notre endpoint Django. Chaque fois que le serveur envoie un événement data, le callback onmessage est déclenché et nous pouvons mettre à jour le DOM en concatenant le nouveau token au texte affiché. Pour améliorer l'expérience, il est utile de gérer également l'état de chargement et d'afficher un curseur clignotant pendant la génération.

Une précaution importante est de gérer la reconnexion automatique : EventSource tente de se reconnecter après une erreur, mais dans le contexte d'une requête chat unique, ce comportement peut créer de la confusion. Définir un timeout côté serveur et fermer proprement la connexion lorsque la génération se termine évite les problèmes de connexions orphelines.

Conclusion

Implémenter le streaming SSE avec Django et une API OpenAI-compatible est un investissement qui rapporte immédiatement en termes d'expérience utilisateur. Le pattern est simple mais demande de l'attention aux détails : formatage correct des événements, gestion des erreurs, et fermeture ordonnée de la connexion. L'essentiel est le suivant : commencer par un générateur Python qui lit les chunks depuis le flux du fournisseur et les transmet comme événements SSE, puis ajouter des gestionnaires d'erreur et de timeout. Avec cette base, vous aurez un protocole de chat réactif prêt à être intégré dans n'importe quelle interface web moderne.