Streaming: recibir respuestas en tiempo real
En esta página
Streaming: recibir respuestas en tiempo real
El streaming te permite recibir la respuesta token a token en lugar de esperar a que termine toda la generación. Esto no es solo un detalle estético de la interfaz: es lo que separa un chatbot que parece lento de uno que se siente ágil, incluso cuando el rendimiento del servidor es idéntico.
Por qué usar streaming
Sin streaming, los usuarios a veces miran una pantalla en blanco durante diez o treinta segundos antes de que aparezca de golpe la respuesta completa. Con streaming, las primeras palabras aparecen en menos de un segundo y la lectura comienza mientras la generación continúa. La duración total es la misma; la percepción, no. Activarlo requiere solo un parámetro, stream=True, que convierte el valor de retorno de create() en un iterador de eventos.
from openai import OpenAI
client = OpenAI()
# SIN streaming: espera a tenerlo todo
response = client.responses.create(
model="gpt-5.6-terra",
input="Write a paragraph about artificial intelligence."
)
print(response.output_text) # Aparece todo de una vez tras la espera
# CON streaming: token a token
stream = client.responses.create(
model="gpt-5.6-terra",
input="Write a paragraph about artificial intelligence.",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
print() # Salto de línea al final
Eventos tipados, no un flujo indiferenciado
El flujo no solo transporta texto. Te notifica cuándo se crea la respuesta, cuándo se añade cada elemento de salida, cuándo llegan los fragmentos y cuándo se completa la operación; el evento final incluye las métricas de uso. Filtras por event.type para saber qué estás gestionando. Esta estructura te permite, por ejemplo, mostrar un indicador de carga tan pronto como se dispara response.created y sumar los tokens al final sin necesidad de una segunda llamada a la API.
stream = client.responses.create(
model="gpt-5.6-terra",
input="Hello!",
stream=True
)
for event in stream:
match event.type:
case "response.created":
print(f"[Response created] ID: {event.response.id}")
case "response.output_item.added":
print(f"[New output item]")
case "response.output_text.delta":
print(f"[Text] {event.delta}", end="")
case "response.output_text.done":
print(f"\n[Text complete]")
case "response.completed":
print(f"[Done] Tokens: {event.response.usage.total_tokens}")
# Salida:
# [Response created] ID: resp_abc123
# [New output item]
# [Text] Hello[Text] ! [Text] How[Text] can[Text] I...
# [Text complete]
# [Done] Tokens: 25
En una aplicación real, casi siempre querrás hacer dos cosas a la vez: mostrar los fragmentos y reconstruir el texto completo para poder archivarlo o devolvérselo al llamador. La regla es simple: acumula mientras iteras, porque una vez consumido el flujo, no se puede rebobinar.
def stream_and_collect(prompt: str) -> str:
"""Transmite la respuesta mientras la recoge."""
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
print(event.delta, end="", flush=True)
print() # Salto de línea
return full_text
result = stream_and_collect("List 3 European capitals.")
print(f"\nCollected text ({len(result)} characters)")
Streaming y llamadas a funciones
Las llamadas a funciones también se transmiten por flujo, con sus propios eventos: los argumentos llegan en fragmentos mediante response.function_call_arguments.delta, y response.function_call_arguments.done indica que el JSON está completo. Esto tiene una consecuencia práctica importante: nunca intentes deserializar los argumentos antes del evento done, o solo tendrás un JSON truncado.
stream = client.responses.create(
model="gpt-5.6-terra",
input="What time is it in Tokyo?",
tools=[{
"type": "function",
"name": "get_time",
"description": "Get the time in a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}],
stream=True
)
for event in stream:
match event.type:
case "response.output_text.delta":
print(event.delta, end="")
case "response.function_call_arguments.delta":
print(f"[Args] {event.delta}", end="")
case "response.function_call_arguments.done":
print(f"\n[Function call complete]")
# Salida:
# [Args] {"city": "Tokyo"}
# [Function call complete]
El caso asíncrono
En cuanto tu aplicación sirva a varios usuarios simultáneamente, cambia a AsyncOpenAI: el cliente síncrono bloquearía el bucle de eventos durante toda la generación, haciendo que tus otras peticiones tuvieran que esperar. La sintaxis difiere en solo dos palabras clave: await en la creación y async for en la iteración.
from openai import AsyncOpenAI
import asyncio
async_client = AsyncOpenAI()
async def stream_async(prompt: str):
"""Transmisión asíncrona de la respuesta."""
stream = await async_client.responses.create(
model="gpt-5.6-terra",
input=prompt,
stream=True
)
async for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
print()
asyncio.run(stream_async("Tell a short joke."))
En la web, el streaming es inútil si se detiene en tu servidor: necesitas extenderlo hasta el navegador. FastAPI lo habilita con StreamingResponse, alimentado por un generador que reenvía los fragmentos según van llegando.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from openai import OpenAI
app = FastAPI()
client = OpenAI()
@app.get("/chat")
async def chat(question: str):
def generate():
stream = client.responses.create(
model="gpt-5.6-terra",
input=question,
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
yield event.delta
return StreamingResponse(generate(), media_type="text/plain")
Errores a mitad del flujo
Un detalle merece tu atención: en el streaming, un error puede ocurrir después de que ya se hayan mostrado fragmentos. El usuario ve entonces una respuesta que empieza pero se corta. Por tanto, envuelve la iteración en sí, no solo la creación del flujo, para poder señalar limpiamente la interrupción en lugar de dejar una frase a medias.
from openai import APIError
def stream_with_errors(prompt: str):
"""Streaming con gestión robusta de errores."""
try:
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)
print()
except APIError as e:
print(f"\nAPI error during streaming: {e.message}")
except Exception as e:
print(f"\nUnexpected error: {e}")
stream_with_errors("Explain streaming in 2 sentences.")
Puntos clave
- Activa el streaming con
stream=Truepara una experiencia en tiempo real - Filtra los eventos por
event.typepara gestionar correctamente cada tipo de dato response.output_text.deltacontiene los fragmentos de textoresponse.completedseñala el final e incluye las métricas de uso- Usa
AsyncOpenAIpara streaming en aplicaciones asíncronas - Gestiona siempre los errores, incluso en modo streaming