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
- 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.
- No comprobar
[DONE]. Una conexión caída parece una respuesta corta. Trate la falta de[DONE]como incompleta y registre elX-Request-ID, como describe la guía de errores. - 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.
- 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. - 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.
