Ir al contenido principal
Español— Elegir un idioma
Menú

Streaming SSE

Lección 5 de 16 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Respuestas en tiempo real con Server-Sent Events
  2. Streaming frente a no streaming
  3. El protocolo SSE en detalle
  4. Habilitar streaming en Python
  5. Estructura de un fragmento (chunk)
  6. Reconstruir la respuesta completa
  7. Cuándo usar streaming
  8. Puntos clave

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 usoRecomendación
Chatbot interactivoStreaming (mejor UX)
Procesamiento por lotesSin streaming (más simple)
API backend para frontendStreaming (SSE al navegador)
Pipeline de datosSin streaming (procesamiento atómico)
Extracción estructuradaSin 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.content en lugar de message.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