Qué te ofrece el streaming
Sin streaming, la API mantiene toda la respuesta hasta que el modelo termina, luego la envía como un solo cuerpo JSON. Para una respuesta larga, esto puede significar varios segundos de pantalla en blanco. Con stream: true, el servidor envía la misma respuesta como una serie de pequeños eventos, cada uno con unos pocos caracteres de la respuesta, y tu interfaz de usuario puede mostrarlos a medida que llegan.
El formato de red son eventos enviados por el servidor (SSE) sobre una respuesta HTTP normal. Cada evento es una línea que comienza con data: seguida de un fragmento JSON, y el stream termina con data: [DONE]. Rara vez analizas esto manualmente, porque los SDKs de OpenAI lo hacen por ti. Si quieres ver los bytes crudos, la vista general para desarrolladores muestra la disposición del endpoint y la documentación de la API enumera cada parámetro.
Hay dos cosas que vale la pena decidir antes de escribir código. Primero, quién lee el stream: un navegador hablando con tu servidor, o solo tu servidor. Segundo, qué haces cuando la conexión se rompe a mitad de camino. El resto de esta página cubre ambos.
Python: streaming con el SDK de OpenAI
Instala el SDK con pip install openai, crea un cliente con nuestra URL base y pasa stream=True. El ID del modelo es uncensored.
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key="YOUR_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a four-line poem about rain."}],
stream=True,
)
text = []
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text.append(piece)
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
print("tokens:", usage)
Nota la protección chunk.choices and .... El fragmento final que contiene el uso puede tener una lista choices vacía, y acceder a ella generaría un error. Recopilar piezas en una lista y unirlas al final también es más barato que la concatenación repetida de cadenas en respuestas largas.
Node: la misma llamada en JavaScript
Con el paquete oficial openai para Node, el stream es un iterador asíncrono. Este ejemplo usa módulos ES.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredllmapi.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses for a stream." }],
stream: true,
});
let full = "";
let usage = null;
for await (const chunk of stream) {
const piece = chunk.choices?.[0]?.delta?.content;
if (piece) {
full += piece;
process.stdout.write(piece);
}
if (chunk.usage) usage = chunk.usage;
}
console.log("\nusage:", usage);
Si no quieres usar el SDK, fetch también funciona: envía el mismo cuerpo JSON con stream: true, luego lee response.body con un TextDecoder y divide por líneas en blanco. El SDK te ahorra manejar eventos que quedan cortados en un límite de chunk, que es el error habitual en parseadores escritos a mano.
Lectura del uso y el saldo
El uso se informa al final del stream. Ese es el número que debes registrar para el seguimiento de costos, porque es contra lo que se carga tu saldo. A $0,15 por 1M tokens de entrada y $0,50 por 1M tokens de salida, una respuesta con 1.200 tokens de entrada y 800 tokens de salida cuesta 1.200 x 0.15 / 1.000.000 + 800 x 0.50 / 1.000.000 = $0,00018 + $0,0004 = $0,00058.
Cada respuesta también incluye un encabezado X-Balance-USD con tu crédito restante, para que puedas mostrar una advertencia de saldo bajo sin una segunda petición. También puedes llamar a GET /v1/balance en un temporizador. Las peticiones fallidas o rechazadas no se cobran, lo que significa que un error antes del primer token no cuesta nada.
Los mismos encabezados de respuesta incluyen X-Request-Id. Guárdalo junto a tu propia línea de registro para cada stream. Si un stream se comporta de manera extraña, ese ID es lo que das a soporte para que se pueda encontrar la petición.
Streams interrumpidos y qué hacer al respecto
Los streams se rompen. Un teléfono cambia de Wi-Fi a datos móviles, un proxy cierra una conexión inactiva, un usuario cierra la pestaña. Planifícalo desde el principio.
Mantén el texto parcial
Añade cada pieza a un búfer a medida que llega, y guarda el búfer cuando el bucle termine o lance una excepción. Si el stream falló, tienes una respuesta parcial utilizable. Muéstrala con un botón de reintento en lugar de descartarla.
Reintentar o continuar
La recuperación más simple es reenviar la petición original. Para una respuesta corta está bien. Para una larga, puedes enviar el texto parcial guardado como un mensaje del asistente y pedirle al modelo que continúe desde donde se detuvo. El resultado puede no coincidir con lo que habría producido el primer stream, así que trátalo como un mejor esfuerzo y etiquétalo en tu interfaz de usuario si la exactitud importa.
Cierra lo que abandones
Una petición transmitida ocupa su ranura de concurrencia hasta que termina el stream. Una clave completa permite 8 peticiones a la vez, y una clave de prueba solo 2. Si tu servidor sigue leyendo un stream para un usuario que se ha ido, esa ranura permanece ocupada. Cancela la petición cuando el cliente se desconecte. En Python, llama a stream.close(); en Node, llama a stream.controller.abort().
Retransmisión de un stream a un navegador
Nunca pongas tu clave de API en el código del navegador. La configuración habitual es un pequeño endpoint en tu propio servidor que llama a la API con stream: true y retransmite cada pieza a la página. En Node con Express, establece Content-Type: text/event-stream, escribe cada pieza como data: ... seguido de una línea en blanco, y escucha el evento close en la petición para abortar la llamada upstream. En la página, EventSource maneja puntos finales GET, mientras que fetch con un lector maneja cuerpos POST, que es lo que necesitas cuando envías un historial de mensajes.
Mantén el historial de mensajes en tu servidor o en el cuerpo de la petición, y recorta los turnos más antiguos cuando la conversación sea larga. La ventana de contexto es de 100.000 tokens para prompt más completion, lo cual es mucho chat, pero una sesión de larga duración eventualmente la alcanzará.
Límites de peticiones durante el streaming
Los límites son 300 peticiones por minuto y 8 peticiones concurrentes en una clave completa, y 60 por minuto y 2 concurrentes en una clave de prueba. Superarlos devuelve HTTP 429. El código de error te dice qué límite alcanzaste: rate_limited significa demasiadas peticiones por minuto, y concurrency significa demasiadas a la vez. En sobrecarga temporal, la API también devuelve 429 con un encabezado Retry-After: 5.
Dado que un 429 llega antes de que se transmitan tokens, manéjalo antes de empezar a leer. Un pequeño envoltorio de reintento es suficiente:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.uncensoredllmapi.com/v1", api_key="YOUR_KEY")
def open_stream(messages, tries=4):
for n in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, stream=True
)
except RateLimitError as e:
wait = 5 if n == 0 else 5 * (n + 1)
time.sleep(wait)
raise RuntimeError("still rate limited")
Para aplicaciones de chat con muchos usuarios, la solución real para los errores de concurrency es una cola pequeña en tu lado que permita no más de 8 streams en vivo a la vez.
Lista de verificación antes de lanzar un chat con streaming
- Protege contra
choicesvacíos en el último fragmento. - Almacena en búfer el texto parcial y persistelo en caso de error.
- Cancela la petición al origen cuando el navegador se desconecta.
- Limita los flujos en vivo a tu límite de concurrencia.
- Registra el uso y el ID de petición por flujo.
- Desactiva el almacenamiento intermedio de respuestas en cualquier proxy inverso delante de tu servidor, o los tokens llegarán por ráfagas.
El último punto suele fallar en los primeros despliegues. Nginx, por ejemplo, almacena en búfer las respuestas proxy por defecto, así que el flujo funciona en localhost y parece congelado en producción hasta que se desactiva el almacenamiento intermedio para esa ruta. Para salida JSON en lugar de texto libre, consulta las notas sobre modo JSON. Para probar el código anterior, crea una clave de API; las cuentas nuevas pueden reclamar $0,50 de crédito de prueba con un clic, válido por 7 días. Las recargas son solo con cripto (USDT en TRC20 o USDC en Base), desde $20.
