Streaming des API d’IA : SSE et délais

Maîtrisez les événements Chat et Responses, le parsing SSE, la première sortie effective, les délais par phase et les annulations 499.

Le streaming d’une API d’IA envoie des événements pendant la génération au lieu d’attendre le corps complet. Il améliore la réactivité perçue sans forcément réduire la latence du modèle, et impose au client d’interpréter le bon protocole.

Chat Completions diffuse des fragments de complétion ; Responses utilise des événements typés. Un client peut recevoir HTTP 200 sans rien afficher s’il attend la mauvaise structure.

Commencer sans mise en mémoire tampon

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_RESPONSES_MODEL","input":"Explain SSE.","stream":true}'

Testez d’abord la même requête sans streaming pour séparer validation et parsing. Utilisez un ID de Modèles et tarifs.

Traiter SSE comme un protocole

Server-Sent Events contient des enregistrements délimités, pas des fragments JSON arbitraires. Le client doit éviter le buffering dans HTTP, proxy et UI, rassembler les lectures partielles, reconnaître texte, raisonnement, outils, fin et erreurs, conserver annulation et usage final, puis fermer après l’événement terminal.

Mesurer plusieurs phases

Mesure Signification
Connexion et authentification Atteindre la passerelle et valider la clé
Headers upstream La route choisie commence à répondre
Première sortie effective Premier texte, raisonnement ou outil utile
Premier texte visible Premier contenu vu par l’utilisateur
Temps total Fin, échec ou annulation

Un appel d’outil peut être utile avant tout texte. Pour l’exploitation, mesurez la première sortie effective ; pour l’UX, ajoutez le premier texte visible.

Délais par phase

Séparez timeout de connexion, headers ou première sortie, inactivité du flux et deadline globale. Raisonnement et outils peuvent retarder le texte. Réglez ces budgets avec des charges réelles, pas avec un unique délai court.

Si client, navigateur ou proxy ferme trop tôt, Modelflare peut inscrire 499. Cela prouve une annulation downstream, pas une panne du modèle ou du canal. Comparez Abort, délais du proxy, première sortie, modèle, groupe et heure.

Si aucun texte n’apparaît

  1. Répétez avec "stream": false.
  2. Confirmez le support de l’endpoint.
  3. Capturez les événements bruts avant l’UI.
  4. Cherchez un outil ou raisonnement sans texte.
  5. Écartez le buffering intermédiaire.
  6. Vérifiez l’événement terminal du parser.
  7. Comparez statut, délais et annulation.

Si le mode normal fonctionne et que les événements arrivent, le problème est souvent dans le parsing ou l’affichage. Sinon, consultez le guide des erreurs. Pour le format : Responses API ou Chat Completions.

Comparer les deux endpoints sans mise en mémoire tampon

En complément de l’exemple Responses, testez Chat Completions avec son propre format :

curl -N -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "Explique SSE en trois points."}],
    "stream": true
  }'

L’analyseur doit :

  • éviter la mise en mémoire tampon dans la bibliothèque HTTP, le proxy et l’interface ;
  • réunir les lectures partielles jusqu’à obtenir un événement complet ;
  • interpréter le type d’événement propre à l’endpoint choisi ;
  • distinguer texte, raisonnement, outils, fin et erreurs ;
  • accepter une réponse utile sans texte visible ;
  • conserver l’annulation et l’utilisation finale ;
  • fermer le flux après l’événement terminal.

Liste de contrôle pour la diffusion en production

  • Associer explicitement l’analyseur à Chat Completions ou Responses.
  • Tester texte, raisonnement, outils seuls, erreurs et fin normale.
  • Mesurer séparément premier événement, première sortie effective et premier texte visible.
  • Définir des délais pour connexion, première sortie, inactivité et opération complète.
  • Utiliser un signal d’annulation intentionnel.
  • Traiter chaque nouvelle tentative comme une nouvelle requête sans idempotence sûre.
  • Conserver identifiant, statut, modèle, groupe et temps pour le diagnostic.
  • Vérifier qu’aucun intermédiaire ne remet le flux en mémoire tampon.

Questions fréquentes

La diffusion accélère-t-elle la génération du modèle ?

Pas nécessairement. Elle expose la sortie plus tôt ; l’attente du premier événement et la vitesse suivante dépendent toujours du modèle, de la route, du contexte, du raisonnement et des outils.

Pourquoi curl fonctionne-t-il alors que l’application n’affiche rien ?

L’application ou un intermédiaire peut mettre le corps en mémoire tampon, ou l’analyseur peut attendre des fragments Chat Completions tout en recevant des événements Responses. Capturez les événements bruts avant de changer de modèle.

Faut-il relancer un flux interrompu ?

Uniquement si l’opération peut être répétée sans risque. Le travail upstream ou un outil peut déjà avoir été exécuté ; bornez les tentatives et exigez l’idempotence en présence d’effets de bord.