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

Streaming optimizado

Lección 5 de 20 Actualizado el 28 de julio de 2026 Avanzado
En esta página
  1. Qué cambia realmente el streaming
  2. Consumo del flujo en el lado del cliente
  3. Reenvío del flujo al navegador
  4. Mantenimiento de la conexión en el tiempo
  5. Puntos clave

Qué cambia realmente el streaming

El streaming no hace que el modelo sea más rápido: hace que la espera sea soportable. Para una respuesta que tarda cinco segundos en generarse, un usuario sin streaming mira una pantalla en blanco durante cinco segundos antes de recibir un bloque de texto. Con streaming, ve las primeras palabras tras unos pocos cientos de milisegundos y lee a medida que el modelo escribe. La duración total es idéntica, pero la percepción es completamente distinta. Por eso, en producción, omitir el streaming es casi siempre un error de diseño y no una elección consciente.

Sin embargo, el flujo debe atravesar toda tu cadena. Un flujo generado correctamente por la API pero acumulado por tu servidor de aplicación o almacenado en búfer por tu proxy inverso llega al usuario en un único bloque: has pagado el precio de la complejidad del streaming sin obtener sus beneficios. Esta lección sigue, por tanto, la ruta completa, desde la llamada a la API hasta el navegador.

Consumo del flujo en el lado del cliente

Con la API de Responses, establecer stream=True transforma la respuesta en una secuencia de eventos tipados que iteras a medida que llegan. Cada fragmento de texto llega en un evento response.output_text.delta; el final del flujo se señala con response.completed, que contiene el objeto de respuesta completo, útil para recuperar el uso de tokens.

import openai

client = openai.OpenAI()

def generate_streaming(prompt: str):
    """Generación con streaming mediante la API de Responses."""
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.completed":
            print()  # Salto de línea al final
            return event.response

La bandera flush=True no es cosmética: sin ella, Python almacena la salida en búfer por su cuenta y acabas con el comportamiento por bloques que intentabas evitar. Este detalle se repite en cada capa de la cadena y constituye la principal dificultad del streaming.

El mecanismo también cubre las llamadas a funciones. Los argumentos de las herramientas se construyen progresivamente y puedes mostrarlos a medida que se generan para indicar al usuario que se está formulando una búsqueda, en lugar de dejarle mirando una interfaz congelada mientras el modelo prepara su llamada.

tools = [
    {
        "type": "function",
        "name": "search_product",
        "description": "Busca un producto en el catálogo.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "category": {"type": "string"},
            },
            "required": ["query"],
        },
    }
]

def streaming_with_tools(prompt: str):
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        tools=tools,
        stream=True,
    )

    for event in stream:
        match event.type:
            case "response.output_text.delta":
                print(event.delta, end="", flush=True)
            case "response.function_call_arguments.delta":
                # Argumentos de la función que se están generando actualmente
                print(f"[arg: {event.delta}]", end="")
            case "response.function_call_arguments.done":
                print(f"\n[Llamada a función completada]")

Reenvío del flujo al navegador

Tu frontend no se comunica directamente con la API de OpenAI, sino con tu servidor, que debe, por tanto, reenviar el flujo. Los eventos enviados por el servidor (SSE) son el formato natural para esto: una respuesta HTTP que permanece abierta, donde cada línea data: transporta un fragmento JSON. El siguiente ejemplo reenvía el texto a medida que llega y luego emite un mensaje final que contiene el recuento de tokens, lo que te permite facturar o registrar sin una segunda llamada.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import openai
import json

app = FastAPI()
client = openai.OpenAI()

@app.post("/api/chat")
async def chat_streaming(request: dict):
    prompt = request["message"]

    async def generate():
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt,
            stream=True,
        )

        for event in stream:
            if event.type == "response.output_text.delta":
                data = json.dumps({"text": event.delta})
                yield f"data: {data}\n\n"
            elif event.type == "response.completed":
                usage = event.response.usage
                data = json.dumps({
                    "end": True,
                    "input_tokens": usage.input_tokens,
                    "output_tokens": usage.output_tokens,
                })
                yield f"data: {data}\n\n"

    return StreamingResponse(
        generate(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",  # Importante para nginx
        },
    )

Luego está el proxy inverso, el sospechoso habitual cuando «el streaming no funciona en producción aunque funcionaba en local». Por defecto, nginx acumula la respuesta del backend antes de transmitirla. La siguiente configuración desactiva este comportamiento solo para la ruta específica.

location /api/chat {
    proxy_pass http://127.0.0.1:8000;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection "";
    chunked_transfer_encoding on;
}

Mantenimiento de la conexión en el tiempo

Un flujo abierto durante varias decenas de segundos está más expuesto que una llamada breve: una caída de red, un límite de cuota alcanzado y la generación se detiene a mitad de frase. Tu estrategia de reintentos debe distinguir entre estos dos casos, porque requieren enfoques diferentes. Un error de conexión debe reintentarse con retroceso exponencial, dando tiempo a que la red se recupere sin saturar la API; un exceso de cuota debe reintentarse tras una espera fija, ya que la ventana del límite de velocidad se restablece a intervalos regulares.

import openai

def resilient_streaming(prompt: str, max_attempts: int = 3):
    """Streaming con gestión de errores y reintentos."""
    for attempt in range(max_attempts):
        try:
            stream = client.responses.create(
                model="gpt-5.6-terra",
                input=prompt,
                stream=True,
            )

            full_text = ""
            for event in stream:
                if event.type == "response.output_text.delta":
                    full_text += event.delta
                    yield event.delta

            return  # Éxito, salir

        except openai.APIConnectionError:
            if attempt < max_attempts - 1:
                import time
                time.sleep(2 ** attempt)  # Retroceso exponencial
            else:
                raise
        except openai.RateLimitError:
            import time
            time.sleep(5)  # Espera fija para límite de velocidad

Un último ajuste mejora la comodidad de lectura. Emitir cada token produce un texto entrecortado, especialmente si tu interfaz aplica una animación o si el resultado se dirige a síntesis de voz. Acumular hasta el final de una frase da un ritmo más cercano a la lectura humana, a costa de un ligero retraso adicional en el primer fragmento.

def streaming_by_sentence(prompt: str):
    """Acumula y emite por frases completas."""
    buffer = ""

    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            buffer += event.delta
            # Buscar final de frase
            for separator in [".\n", "!\n", "?\n", ". ", "! ", "? "]:
                if separator in buffer:
                    parts = buffer.split(separator, 1)
                    yield parts[0] + separator.rstrip()
                    buffer = parts[1] if len(parts) > 1 else ""

    if buffer.strip():
        yield buffer.strip()

Observa el if buffer.strip() final: sin él, una respuesta que no termine con puntuación fuerte perdería sus últimas palabras. Este tipo de descuido pasa desapercibido en las pruebas y se manifiesta en producción en respuestas truncadas por max_output_tokens.

Puntos clave

  • Usa siempre streaming en producción para reducir la latencia percibida
  • Configura nginx con proxy_buffering off para SSE
  • Gestiona los errores con reintentos y retroceso exponencial
  • Acumula por frases para una visualización más natural