Streaming de API de IA: SSE y timeouts

Aprende eventos de Chat Completions y Responses, parsing SSE, primer resultado efectivo, timeouts por fase y diagnóstico de 499.

El streaming de una API de IA entrega eventos mientras el modelo genera, en vez de esperar al cuerpo completo. Mejora la percepción de respuesta, pero no reduce necesariamente la latencia del modelo y exige que el cliente interprete el protocolo correcto.

Chat Completions transmite fragmentos de completado; Responses usa eventos tipados. Un cliente puede recibir HTTP 200 y no mostrar nada si espera la forma equivocada.

Empieza sin buffering

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_RESPONSES_MODEL","input":"Explain SSE.","stream":true}'

Prueba la misma petición con streaming desactivado para separar validación de parsing. Usa un ID real de Modelos y precios.

Trata SSE como un protocolo

Server-Sent Events contiene registros delimitados, no trozos arbitrarios de JSON. El cliente debe evitar buffering en HTTP, proxies y UI; reunir lecturas parciales; reconocer texto, razonamiento, herramientas, finalización y errores; conservar cancelación y uso final; y cerrar tras un evento terminal.

Mide fases distintas

Medida Significado
Conexión y autenticación Llegada a la pasarela y validación de la clave
Cabeceras upstream La ruta elegida empieza a responder
Primer resultado efectivo Primer texto, razonamiento o herramienta útil
Primer texto visible Primer contenido que ve la persona
Tiempo total Finalización, fallo o cancelación

Una llamada a herramienta puede ser efectiva antes de producir texto. Para operación conviene medir el primer resultado efectivo; para experiencia, también el primer texto visible.

Diseña timeouts por fase

Separa timeout de conexión, cabeceras o primer resultado, inactividad del stream y deadline global. Las tareas de razonamiento o herramientas pueden tardar más en mostrar texto. Ajusta los presupuestos con tráfico real, no con un único timeout corto.

Si el cliente, navegador o proxy cierra antes de terminar, Modelflare puede registrar 499. Indica una cancelación downstream, no demuestra por sí solo que el modelo o canal falló. Compara abortos, timeouts, primer resultado, modelo, grupo e instante de cancelación.

Si no aparece texto

  1. Repite con "stream": false.
  2. Confirma que el modelo admite el endpoint.
  3. Captura eventos crudos antes de la UI.
  4. Busca eventos de herramienta o razonamiento sin texto.
  5. Descarta buffering intermedio.
  6. Comprueba el evento terminal del parser.
  7. Revisa estado, tiempos y cancelación.

Si la petición normal funciona y llegan eventos, el problema suele estar en parsing o renderizado. Si no llega ningún evento, sigue la guía de errores. Para elegir formato, consulta Responses API frente a Chat Completions.

Compara los dos endpoints con peticiones sin búfer

Además del ejemplo de Responses anterior, prueba Chat Completions con su propio formato:

curl -N -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "Explica SSE en tres puntos."}],
    "stream": true
  }'

El analizador debe:

  • mantener sin búfer la biblioteca HTTP, el proxy y la interfaz;
  • acumular lecturas parciales hasta completar un evento;
  • interpretar el tipo de evento del endpoint seleccionado;
  • distinguir texto, razonamiento, herramientas, finalización y errores;
  • aceptar respuestas útiles que no contengan texto visible;
  • conservar cancelación y uso final;
  • cerrar al recibir el evento terminal.

Lista de control para transmisión en producción

  • Vincula explícitamente el analizador con Chat Completions o Responses.
  • Prueba texto, razonamiento, solo herramientas, errores y finalización normal.
  • Mide por separado primer evento, primer resultado efectivo y primer texto visible.
  • Define tiempos máximos de conexión, primera salida, inactividad y operación completa.
  • Usa una señal de cancelación intencionada.
  • Trata cada reintento como una petición nueva salvo que exista idempotencia segura.
  • Conserva ID, estado, modelo, grupo y tiempos para el diagnóstico.
  • Verifica que ningún intermediario vuelva a almacenar el flujo en búfer.

Preguntas frecuentes

¿La transmisión hace que el modelo genere más rápido?

No necesariamente. Permite mostrar antes lo que ya se está generando; el tiempo hasta el primer evento y la velocidad posterior siguen dependiendo del modelo, la ruta, el contexto, el razonamiento y las herramientas.

¿Por qué funciona con curl pero no en la aplicación?

La aplicación o un intermediario puede almacenar el cuerpo en búfer, o el analizador puede esperar fragmentos de Chat Completions mientras recibe eventos de Responses. Captura los eventos sin transformar antes de cambiar de modelo.

¿Debe reintentarse un flujo interrumpido?

Solo si repetir la operación es seguro. El trabajo upstream o una herramienta pueden haberse ejecutado aunque el cliente no recibiera el final; limita los intentos y exige idempotencia cuando haya efectos secundarios.