Respuestas en streaming

Semana 3 · Capítulo 4 · Básico

El problema

• Las respuestas de un solo golpe se bloquean hasta que toda la respuesta está lista
• Eso funciona para una oración
• Para un párrafo, el lector se queda viendo cómo no pasa nada
• Misma latencia, pésima sensación

Qué cambia

• El servidor manda tokens conforme los genera
• El cliente los imprime conforme llegan
• Mismo modelo, mismo prompt, misma latencia total
• Distinta latencia percibida — eso es la mayor parte de lo que los usuarios notan

OpenAI: un keyword

stream = client.responses.create(
    model="gpt-5.4-nano",
    input=prompt,
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

• stream=True cambia el tipo de retorno a eventos tipados
• Filtra sobre response.output_text.delta
• flush=True no es negociable; Python bufferea stdout por defecto

Gemini: método aparte

stream = client.models.generate_content_stream(
    model="gemini-3.1-flash-lite",
    contents=prompt,
)
for chunk in stream:
    if chunk.text:
        print(chunk.text, end="", flush=True)

• generate_content_stream es el gemelo en streaming
• Cada chunk trae un delta en .text o viene vacío
• Misma UX, distinta ergonomía de SDK

Cuándo conviene el streaming

• Output largo (párrafos, traducciones, reescrituras)
• UX tipo chat donde la espera es lo peor
• Sáltatelo para respuestas de una línea — el overhead no lo vale

Tres showcases esta semana

• Explicador en vivo — preguntas y respuestas; mira la respuesta tomar forma
• Traducción en streaming — pega texto + idioma destino; oración por oración
• Reescritura en vivo — pega un borrador; una versión más ajustada llega en streaming

Cada uno es su propio proyecto de docker-compose bajo code/showcase/<slug>/.

El patrón de dos callables

def run_stream(input: str) -> Iterator[str]:
    stream = client.responses.create(..., stream=True)
    for event in stream:
        if event.type == "response.output_text.delta":
            yield event.delta

def run(input: str) -> str:
    return "".join(run_stream(input))

• run_stream es la lección
• run es un acumulador de una línea
• La UI local usa el stream; el widget de prueba del sitio usa el string final

El backend tiene dos endpoints

• POST /api/ai → string final (sin streaming)
• POST /api/ai/stream → feed SSE de eventos {delta}
• Un dispatch compartido, dos superficies

Conclusión

El streaming está a un argumento de keyword de una app que se siente mejor. El modelo nunca se volvió más rápido. La experiencia de la espera, sí. Úsalo cada vez que el output sea lo bastante largo como para que un lector se cambie de pestaña.