BroadRouter

Streaming de LLM explicado: chunks SSE, deltas, usage y cancelación

Por el equipo de BroadNet Inference · 4 min de lectura · Publicado · Actualizado

Una API de LLM transmite un chat completion como Server-Sent Events: cada línea data contiene un chunk JSON cuyo choices[0].delta trae el siguiente trozo de texto. Concatene los deltas, deténgase en data: [DONE] y active include_usage en stream_options para recibir el recuento de tokens en un último chunk con la lista choices vacía. Para cancelar, cierre la conexión.

Sin streaming, un chat completion no devuelve nada hasta que la respuesta completa está lista. Una respuesta de 600 tokens a unos 100 tokens por segundo supone varios segundos de silencio. Con streaming, las primeras palabras aparecen en cuanto el modelo las escribe. Este artículo cubre lo que realmente viaja por la red, cómo analizarlo, cómo obtener el uso de tokens de un stream y cómo detenerlo limpiamente. Para las reglas específicas de BroadNet en formato breve, vea la guía de referencia de streaming.

¿Qué aspecto tiene un stream SSE en la red?

Server-Sent Events es una respuesta HTTP normal con Content-Type: text/event-stream. El servidor mantiene la conexión abierta y va escribiendo eventos. Cada evento es una o más líneas data: seguidas de una línea en blanco. Las APIs compatibles con OpenAI ponen un chunk JSON en cada evento y terminan con un [DONE] literal:

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 forma anterior es ilustrativa y está recortada. Los chunks reales también llevan model y created, y los modelos de razonamiento pueden informar tokens de razonamiento en usage.

¿Qué contiene un chunk?

Campo Dónde Qué significa
choices[0].delta.role Primer chunk Normalmente assistant. Se envía una vez.
choices[0].delta.content La mayoría de chunks El siguiente trozo de texto. Puede estar vacío.
choices[0].delta.tool_calls Llamadas a herramientas Fragmentos del nombre de la función y de los argumentos JSON, que se unen por index.
choices[0].finish_reason Último chunk de contenido stop, length o tool_calls. null hasta entonces.
usage Chunk final, si se pidió Totales de toda la petición. null en todos los demás.

La idea clave es delta, no instantánea. Cada chunk contiene solo lo nuevo. Usted reconstruye el mensaje uniendo los trozos en orden. Las llamadas a herramientas se transmiten igual: los argumentos llegan como fragmentos de texto que no son JSON válido hasta que llega el último, así que analícelos solo cuando finish_reason sea tool_calls.

¿Cómo se obtiene el uso de tokens de un stream?

Una respuesta sin streaming siempre incluye usage. Un stream no, a menos que lo pida. Ponga stream_options: {"include_usage": true} y el servidor enviará un chunk extra antes de [DONE]. Ese chunk trae los totales y un array choices vacío. En BroadNet Inference, usage puede incluir además prompt_tokens_details.cached_tokens y completion_tokens_details.reasoning_tokens cuando el modelo los informa, que es lo que necesita para el registro de costos.

El error típico: un código que lee chunk.choices[0] en cada chunk lanza un error de índice con el chunk de usage. Compruebe choices primero.

Python: streaming, recoger usage y cancelar

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 por sí solo deja de leer, pero el socket sigue abierto hasta que el recolector de basura lo libera. Ciérrelo explícitamente para que el servidor vea la desconexión.

Node: streaming con 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);
}

El README de openai-node documenta la opción signal, y funciona mientras todavía se está leyendo el cuerpo. En un servidor web, conecte controller.abort() al evento close de la petición del cliente, para que un usuario que abandona la página detenga también la generación. Más configuración en la guía del SDK de Node.

curl: ver los eventos en bruto

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 desactiva el búfer de salida para que los eventos se impriman según llegan. Pulse Ctrl+C para cancelar; eso cierra la conexión. El generador de peticiones a la API crea esta petición, y sus versiones en Python y Node, para cualquier modelo y URL base.

¿Cómo se cancela un stream y cuánto cuesta?

En SSE, cancelar es simplemente cerrar la conexión. No hay un mensaje de «stop». Lo que pasa después depende del servidor: uno que se comporte bien detecta el socket cerrado y deja de generar. Los tokens producidos antes de ese momento fueron trabajo real. La referencia de la API de BroadNet no documenta la facturación de los streams cancelados, así que planifique como si los tokens generados hasta la desconexión se facturaran en pago por uso, y revise sus registros de uso. En un plan de tarifa plana, un stream cancelado no cuesta nada extra, pero solo libera la sesión cuando el servidor se detiene.

Cinco errores de streaming que conviene revisar

  1. Proxies con búfer. Nginx y algunas CDN almacenan las respuestas en búfer, así que el cliente lo recibe todo de golpe. Desactive el búfer del proxy en la ruta de streaming.
  2. No comprobar [DONE]. Una conexión caída parece una respuesta corta. Trate la falta de [DONE] como incompleta y registre el X-Request-ID, como describe la guía de errores.
  3. Reintentar a mitad del stream. Los SDK no reintentan una vez que empieza a llegar el cuerpo. Un reintento es una petición nueva y, en pago por uso, una factura nueva.
  4. Ignorar finish_reason: length. En modelos de razonamiento como DeepSeek V4.1 Flash el pensamiento cuenta dentro de max_tokens, así que un límite pequeño puede detener el stream antes de que aparezca texto visible. Lo que cuestan los tokens de razonamiento.
  5. Partir mal las líneas. Si analiza SSE a mano, acumule bytes hasta ver una línea en blanco. Una lectura TCP puede terminar a mitad de un chunk JSON.

Dónde encaja BroadNet Inference

BroadNet Inference usa la forma de streaming estándar compatible con OpenAI, así que los SDK de Python y Node la analizan sin cambios. El usage del chunk final incluye los tokens en caché y de razonamiento cuando el modelo los informa. Su documentación indica que el streaming debe verificarse modelo a modelo antes de usarlo en producción, así que ejecute el código anterior con el modelo exacto que vaya a usar. Si lo que más le importa es la rapidez con que llega el primer token, lea a continuación TTFT frente a throughput. Si necesita voz en tiempo real por WebSockets, esta API no está pensada para eso; ofrece chat completions y transcripción de archivos.

Preguntas frecuentes

¿Qué diferencia hay entre SSE y WebSockets para el streaming de LLM?

SSE es unidireccional, del servidor al cliente, sobre una respuesta HTTP normal. Es todo lo que necesita un chat completion, por eso las APIs compatibles con OpenAI usan SSE. Los WebSockets son bidireccionales y requieren actualizar el protocolo; se usan para voz en tiempo real, no para chat completions.

¿Por qué usage es null en los chunks de mi stream?

Usage solo se envía si lo pide. Añada stream_options con include_usage en true. Entonces todos los chunks salvo el último tienen usage en null, y el último trae los totales con una lista choices vacía.

¿Me cobran si cancelo un stream?

Depende del proveedor, y muchos no lo documentan. Dé por hecho que se facturan los tokens generados antes de que el servidor detectara la conexión cerrada. Registre el X-Request-ID y compárelo con sus registros de uso.

¿Cómo sé que un stream terminó con normalidad?

Recibió data: [DONE] y el último chunk de contenido tenía un finish_reason como stop. Un finish_reason length significa que max_tokens cortó la respuesta. Si no hay [DONE], la conexión se cayó.

¿El streaming hace más rápido al modelo?

No. El tiempo total de generación es el mismo. El streaming reduce el tiempo hasta que el usuario ve las primeras palabras, que es lo que hace que una interfaz de chat parezca rápida.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity