Streaming SSE
En esta página
Respuestas en tiempo real con Server-Sent Events
Por defecto, la API de Chat Completions espera a que el modelo haya terminado de generar toda su respuesta antes de enviártela. Para una pregunta breve, nadie nota el retraso. Sin embargo, para un informe de mil palabras, esto supone varios segundos con la pantalla en blanco, lo que hace que el usuario se pregunte si la aplicación se ha bloqueado. El streaming resuelve este problema enviando los tokens a medida que se generan, creando el conocido efecto de máquina de escribir que se ve en las interfaces conversacionales.
El protocolo utilizado es Server-Sent Events (SSE), un estándar HTTP que permite al servidor enviar datos al cliente de forma continua a través de una conexión persistente. No hay nada exótico aquí: no hay que instalar WebSockets ni dependencias adicionales.
Streaming frente a no streaming
En el modo sin streaming, que es el predeterminado, el cliente envía la solicitud y espera la respuesta completa:
Client ──── request ────► Server
(wait 3-10s)
Client ◄── complete response ── Server
La ventaja es la simplicidad: la respuesta es atómica, un único objeto JSON fácil de procesar, validar y almacenar. La desventaja es igual de clara: la latencia percibida es alta porque el usuario no ve nada durante todo el proceso de generación.
En modo streaming, el servidor envía los tokens uno a uno o en pequeños grupos:
Client ──── request ────► Server
Client ◄── chunk 1 ─────── Server (after ~200ms)
Client ◄── chunk 2 ─────── Server (after ~250ms)
Client ◄── chunk 3 ─────── Server (after ~300ms)
...
Client ◄── [DONE] ──────── Server
La latencia percibida se reduce drásticamente: el primer carácter aparece en unos pocos cientos de milisegundos, lo que mejora significativamente la experiencia del usuario. A cambio, debes reconstruir el mensaje en el lado del cliente y gestionar un estado que ya no llega como un bloque único.
El protocolo SSE en detalle
Así es exactamente como se ve el flujo HTTP que recibes:
data: {"id":"cmpl-abc","choices":[{"delta":{"content":"Hello"}}],"usage":null}
data: {"id":"cmpl-abc","choices":[{"delta":{"content":" "}}],"usage":null}
data: {"id":"cmpl-abc","choices":[{"delta":{"content":"!"}}],"usage":null}
data: [DONE]
Cada línea comienza con data: seguido de un objeto JSON, y las líneas vacías sirven como separadores entre eventos. Observa el detalle que atrapa a todo el mundo en su primera implementación: el fragmento de texto se encuentra en el campo delta, no en message como en el modo clásico. El flujo termina con un evento data: [DONE], que señala explícitamente el final. Sin él, no podrías distinguir una generación finalizada de una conexión interrumpida.
Habilitar streaming en Python
Con el SDK de Mistral, habilitas el streaming llamando a chat.stream() en lugar de chat.complete():
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
stream = client.chat.stream(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "Explain how an electric motor works."}
]
)
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
print(content, end="", flush=True)
print() # Salto de línea final
El argumento flush=True merece una explicación, ya que olvidarlo es la causa clásica de que el streaming «no funcione». Sin él, Python mantiene los caracteres en el búfer y los muestra en bloques. Esto anula visualmente todos los beneficios del streaming, aunque los fragmentos lleguen correctamente.
Estructura de un fragmento (chunk)
Un fragmento de streaming no se lee como una respuesta completa y las rutas de acceso difieren:
# Sin streaming: response.choices[0].message.content
# Con streaming: chunk.data.choices[0].delta.content
# El primer fragmento suele contener el rol
# chunk.data.choices[0].delta.role == "assistant"
# Los fragmentos siguientes contienen fragmentos de texto
# chunk.data.choices[0].delta.content == "Hello"
# El último fragmento contiene finish_reason
# chunk.data.choices[0].finish_reason == "stop"
El primer fragmento suele llevar el rol sin texto, los siguientes llevan los fragmentos y el último proporciona el finish_reason. Por eso la comprobación if content: en el código anterior no es una precaución innecesaria: concatenar un valor None haría fallar el bucle en la primera iteración.
Reconstruir la respuesta completa
Mostrar fragmentos no es suficiente cuando necesitas conservar la respuesta, por ejemplo, para añadirla al historial de la conversación, registrarla o almacenarla en una base de datos. Por tanto, debes acumular el texto en paralelo a su visualización:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
stream = client.chat.stream(
model="mistral-large-latest",
messages=[{"role": "user", "content": "List 5 programming languages."}]
)
full_response = ""
finish_reason = None
for chunk in stream:
delta = chunk.data.choices[0].delta
if delta.content:
full_response += delta.content
print(delta.content, end="", flush=True)
if chunk.data.choices[0].finish_reason:
finish_reason = chunk.data.choices[0].finish_reason
print(f"\n\nFinish reason: {finish_reason}")
print(f"Complete response ({len(full_response)} characters)")
La variable finish_reason se captura en el mismo bucle por la misma razón que en el modo clásico: una respuesta truncada por max_tokens aparece en pantalla exactamente igual que una respuesta completa, y solo este campo te indicará la diferencia.
Cuándo usar streaming
El streaming no siempre es mejor. Está indicado siempre que haya un humano mirando la pantalla, pero es superfluo o incluso perjudicial cuando una máquina procesa la salida.
| Caso de uso | Recomendación |
|---|---|
| Chatbot interactivo | Streaming (mejor UX) |
| Procesamiento por lotes | Sin streaming (más simple) |
| API backend para frontend | Streaming (SSE al navegador) |
| Pipeline de datos | Sin streaming (procesamiento atómico) |
| Extracción estructurada | Sin streaming (análisis JSON más fiable) |
El último caso es el más instructivo. Si esperas JSON, el streaming no aporta nada: no puedes analizar un objeto incompleto y tendrás que esperar al último fragmento de todos modos. Más vale mantener la llamada atómica y el código simple.
Puntos clave
- El streaming reduce la latencia percibida enviando tokens a medida que se generan
- El protocolo SSE es un estándar HTTP simple y robusto
- En modo streaming, usa
delta.contenten lugar demessage.content - Acumula los fragmentos en el lado del cliente para reconstruir la respuesta completa
- Prefiere el streaming para interfaces de usuario y el modo sin streaming para procesos automatizados