BroadRouter

Le streaming LLM expliqué : chunks SSE, deltas, usage et annulation

Par l’équipe BroadNet Inference · 4 min de lecture · Publié · Mis à jour

Une API LLM diffuse une chat completion sous forme de Server-Sent Events : chaque ligne data contient un chunk JSON dont choices[0].delta porte le morceau de texte suivant. Concaténez les deltas, arrêtez-vous à data: [DONE], et activez stream_options include_usage pour recevoir le nombre de tokens dans un dernier chunk dont la liste choices est vide. Pour annuler, fermez la connexion.

Sans streaming, une chat completion ne renvoie rien tant que la réponse entière n’est pas prête. Une réponse de 600 tokens à environ 100 tokens par seconde représente plusieurs secondes de silence. Avec le streaming, les premiers mots s’affichent dès que le modèle les écrit. Cet article explique ce qui circule réellement sur le réseau, comment le parser, comment récupérer l’usage en tokens d’un stream et comment en arrêter un proprement. Pour les règles propres à BroadNet en version courte, voir le guide de référence du streaming.

À quoi ressemble un stream SSE sur le réseau ?

Les Server-Sent Events sont une réponse HTTP ordinaire avec Content-Type: text/event-stream. Le serveur garde la connexion ouverte et écrit des événements. Chaque événement se compose d’une ou plusieurs lignes data: suivies d’une ligne vide. Les API compatibles OpenAI placent un chunk JSON dans chaque événement et terminent par un [DONE] littéral :

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One, "},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"two, three."},"finish_reason":"stop"}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":6,"total_tokens":20}}

data: [DONE]

La forme ci-dessus est illustrative et abrégée. Les vrais chunks portent aussi model et created, et les modèles de raisonnement peuvent indiquer des tokens de raisonnement dans usage.

Que contient un chunk ?

Champ Où Signification
choices[0].delta.role Premier chunk Généralement assistant. Envoyé une fois.
choices[0].delta.content La plupart des chunks Le morceau de texte suivant. Peut être vide.
choices[0].delta.tool_calls Appels d’outils Fragments du nom de fonction et des arguments JSON, à assembler par index.
choices[0].finish_reason Dernier chunk de contenu stop, length ou tool_calls. null jusque-là.
usage Dernier chunk, si demandé Totaux de toute la requête. null partout ailleurs.

L’idée clé : un delta, pas un instantané. Chaque chunk ne contient que la nouveauté. Vous reconstituez le message en assemblant les morceaux dans l’ordre. Les appels d’outils sont diffusés de la même façon : les arguments arrivent en fragments de chaîne qui ne forment un JSON valide qu’à l’arrivée du dernier ; ne les parsez donc qu’une fois finish_reason à tool_calls.

Comment obtenir l’usage en tokens d’un stream ?

Une réponse sans streaming inclut toujours usage. Un stream, non, sauf si vous le demandez. Réglez stream_options: {"include_usage": true} et le serveur envoie un chunk supplémentaire avant [DONE]. Ce chunk contient les totaux et un tableau choices vide. Chez BroadNet Inference, l’usage peut aussi inclure prompt_tokens_details.cached_tokens et completion_tokens_details.reasoning_tokens quand le modèle les indique : c’est ce qu’il vous faut pour journaliser les coûts.

Le bug classique : un code qui lit chunk.choices[0] sur chaque chunk lève une erreur d’index sur le chunk d’usage. Vérifiez d’abord choices.

Python : streamer, collecter l’usage, annuler

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",  # DeepSeek V4.1 Flash, a reasoning model
    messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
    stream=True,
    stream_options={"include_usage": True},
    max_tokens=2000,  # reasoning counts toward this limit
)

def user_pressed_stop():  # replace with your own condition
    return False

parts, usage, finish = [], None, None
try:
    for chunk in stream:
        if chunk.choices:
            choice = chunk.choices[0]
            if choice.delta.content:
                parts.append(choice.delta.content)
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason:
                finish = choice.finish_reason
        if chunk.usage:
            usage = chunk.usage
        if user_pressed_stop():  # your own condition
            break
finally:
    stream.close()  # closes the HTTP connection

text = "".join(parts)

break seul arrête la lecture, mais le socket reste ouvert jusqu’au passage du ramasse-miettes. Fermez-le explicitement pour que le serveur voie la déconnexion.

Node : streamer avec un AbortController

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY });
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard stop after 30 s

const stream = await client.chat.completions.create(
  {
    model: "broadnet/deepseek-v4.1-flash",
    messages: [{ role: "user", content: "Explain SSE in three sentences." }],
    stream: true,
    stream_options: { include_usage: true },
  },
  { signal: controller.signal },
);

let text = "";
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) text += delta;
  if (chunk.usage) console.log(chunk.usage);
}

Le README d’openai-node documente l’option signal, qui fonctionne aussi pendant la lecture du corps. Dans un serveur web, reliez controller.abort() à l’événement close de la requête du client, pour qu’un utilisateur qui quitte la page arrête aussi la génération. Plus de détails dans le guide du SDK Node.

curl : voir les événements bruts

curl -N https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count to five."}]}'

-N désactive la mise en mémoire tampon de la sortie pour que les événements s’affichent dès leur arrivée. Appuyez sur Ctrl+C pour annuler : cela ferme la connexion. Le générateur de requêtes API produit cette requête, ainsi que les versions Python et Node, pour n’importe quel modèle et n’importe quelle URL de base.

Comment annuler un stream, et qu’est-ce que cela coûte ?

Annuler, en SSE, c’est simplement fermer la connexion. Il n’existe pas de message « stop ». La suite dépend du serveur : un serveur bien conçu remarque le socket fermé et arrête de générer. Les tokens produits avant ce moment représentent un vrai travail. La référence de l’API de BroadNet ne documente pas la facturation des streams annulés : prévoyez donc qu’en paiement à l’usage les tokens générés jusqu’à la déconnexion soient facturés, et vérifiez vos relevés d’usage. Avec un forfait, un stream annulé ne coûte rien de plus, mais ne libère la session qu’une fois que le serveur s’arrête.

Cinq bugs de streaming à vérifier

  1. Proxys qui mettent en mémoire tampon. Nginx et certains CDN mettent les réponses en mémoire tampon, si bien que le client reçoit tout d’un coup. Désactivez la mise en mémoire tampon du proxy pour la route de streaming.
  2. Pas de vérification de [DONE]. Une connexion tombée ressemble à une réponse courte. Traitez l’absence de [DONE] comme une réponse incomplète et notez le X-Request-ID, comme le décrit le guide des erreurs.
  3. Relancer en plein stream. Les SDK ne relancent plus une fois que le corps commence à arriver. Une relance est une nouvelle requête et, en paiement à l’usage, une nouvelle facture.
  4. Ignorer finish_reason: length. Sur les modèles de raisonnement comme DeepSeek V4.1 Flash, la réflexion compte dans max_tokens : une limite basse peut arrêter le stream avant tout texte visible. Ce que coûtent les tokens de raisonnement.
  5. Mal découper les lignes. Si vous parsez le SSE à la main, accumulez les octets jusqu’à voir une ligne vide. Une lecture TCP peut s’arrêter au milieu d’un chunk JSON.

La place de BroadNet Inference

BroadNet Inference utilise le format de streaming standard compatible OpenAI : les SDK Python et Node le parsent sans modification. L’usage du dernier chunk inclut les tokens en cache et de raisonnement quand le modèle les indique. Sa documentation précise que le streaming doit tout de même être vérifié modèle par modèle avant la mise en production : exécutez donc le code ci-dessus sur le modèle exact que vous livrez. Si c’est surtout la rapidité du premier token qui vous importe, lisez ensuite TTFT ou débit. Si vous avez besoin de voix en temps réel via WebSockets, cette API n’est pas faite pour cela : elle propose les chat completions et la transcription de fichiers.

Questions fréquentes

Quelle est la différence entre SSE et WebSockets pour le streaming LLM ?

SSE est unidirectionnel, du serveur vers le client, sur une réponse HTTP normale. C’est tout ce dont une chat completion a besoin, c’est pourquoi les API compatibles OpenAI utilisent SSE. Les WebSockets sont bidirectionnels et nécessitent une mise à niveau du protocole ; ils servent à la voix en temps réel, pas aux chat completions.

Pourquoi usage vaut-il null dans mes chunks de streaming ?

L’usage n’est envoyé que si vous le demandez. Ajoutez stream_options avec include_usage à true. Tous les chunks sauf le dernier ont alors usage à null, et le dernier porte les totaux avec une liste choices vide.

Suis-je facturé si j’annule un stream ?

Cela varie selon les fournisseurs, et beaucoup ne le documentent pas. Partez du principe que les tokens générés avant que le serveur ne remarque la fermeture de la connexion sont facturés. Journalisez le X-Request-ID et comparez avec vos relevés d’usage.

Comment savoir qu’un stream s’est terminé normalement ?

Vous avez reçu data: [DONE] et le dernier chunk de contenu avait un finish_reason comme stop. Un finish_reason à length signifie que max_tokens a coupé la réponse. Pas de [DONE] signifie que la connexion est tombée.

Le streaming rend-il le modèle plus rapide ?

Non. Le temps total de génération est le même. Le streaming réduit le délai avant que l’utilisateur ne voie les premiers mots, et c’est ce qui donne une impression de rapidité à une interface de chat.

Lire en MarkdownDemander à ChatGPTDemander à ClaudeDemander à Perplexity