Guía de streaming de API de IA: SSE y tiempos de espera

Crea streaming confiable con los eventos correctos de Chat y Responses, análisis de SSE, métricas de primera salida efectiva, tiempos de espera por fase y diagnóstico de 499.

Guía de streaming de API de IA: SSE y tiempos de espera

El streaming de una API de IA envía la salida de forma incremental mientras el modelo genera, en lugar de esperar al cuerpo completo de la respuesta. Puede mejorar la sensación de rapidez, pero no reduce automáticamente la latencia del modelo y agrega un contrato de protocolo que el cliente debe analizar correctamente.

La primera regla es usar el analizador que corresponde al endpoint. Chat Completions envía fragmentos de completado en streaming, mientras que Responses usa eventos de respuesta tipados. Un cliente puede recibir HTTP 200 y aun así no mostrar nada si espera una estructura de eventos equivocada.

Empieza con una solicitud sin búfer

Para un modelo de Chat Completions, curl -N desactiva el almacenamiento en búfer de la salida de curl:

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": "Explain SSE in three points."}],
    "stream": true
  }'

Para un modelo compatible con Responses:

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 in three points.",
    "stream": true
  }'

Usa un ID de modelo exacto de Modelos y precios. Prueba primero la misma solicitud una vez con el streaming desactivado; así separas la validación de la solicitud del análisis del flujo.

Trata el flujo de eventos como un protocolo

Server-Sent Events son registros delimitados, no fragmentos arbitrarios de JSON. Un cliente en producción debe:

  • mantener el cuerpo de la respuesta sin búfer en su biblioteca HTTP, en el proxy y en la capa de interfaz;
  • acumular las lecturas parciales de red hasta tener un evento completo;
  • analizar el tipo de evento que usa el endpoint seleccionado;
  • manejar deltas de texto, eventos de razonamiento o de herramientas, eventos de finalización y eventos de error;
  • no suponer que toda respuesta útil contiene texto visible;
  • conservar la cancelación y la información final de uso;
  • cerrar el flujo después de un evento terminal en lugar de esperar indefinidamente.

Siempre que puedas, usa un SDK que admita de forma nativa el protocolo elegido. Un analizador propio debe probarse con tramas fragmentadas, varios eventos en una misma lectura, salidas formadas solo por herramientas y un evento terminal limpio.

Mide algo más que el tiempo hasta el primer token

El “tiempo hasta el primer token” suele ser demasiado impreciso para el tráfico de agentes. Separa estas mediciones:

Medición Qué significa
Conexión y autenticación El tiempo para llegar al gateway y validar la clave
Encabezados de respuesta del proveedor El tiempo hasta que la ruta seleccionada empieza a responder
Primera salida efectiva El primer texto, razonamiento o evento de herramienta útil
Primer texto visible El primer texto que el usuario puede ver realmente
Velocidad de salida La velocidad de generación visible después de que empieza la salida
Tiempo total de respuesta El tiempo hasta la finalización, la falla o la cancelación

Una llamada a herramienta puede producir una salida efectiva antes de cualquier texto visible. Por eso, la primera salida efectiva es la métrica operativa más segura, mientras que el primer texto visible es útil para la experiencia de usuario.

Los registros de uso de Modelflare conservan evidencia de tiempos por solicitud para que puedas comparar estas fases con el modelo, el grupo, el estado, los tokens y el costo.

Diseña los tiempos de espera por fase

Un único tiempo de espera global y corto genera fallas ambiguas. Un cliente de streaming debe considerar varios márgenes de tiempo:

  1. Tiempo de espera de conexión: no se pudo establecer la conexión HTTP.
  2. Tiempo de espera de encabezados o de primera salida: no hubo respuesta ni evento efectivo después de que se aceptó la solicitud.
  3. Tiempo de espera por inactividad: el flujo comenzó, pero no llegó ningún evento nuevo durante un período inesperadamente largo.
  4. Plazo límite total: la operación completa superó el límite de negocio de la carga de trabajo.

Las solicitudes con mucho razonamiento o basadas en herramientas pueden tardar legítimamente más en mostrar texto visible que un chat breve. Define los márgenes a partir del comportamiento observado de la carga de trabajo y cancela de forma intencional cuando el usuario ya no necesite el resultado.

Entiende la cancelación y los registros 499

Si el cliente, el proxy inverso, la pestaña del navegador o el plazo límite de quien hace la llamada cierra la conexión downstream, el gateway puede registrar la solicitud como cancelada por el cliente. Una etiqueta 499 en el registro de una solicitud indica que la conexión downstream terminó antes de completarse; por sí sola, no demuestra que haya fallado el modelo o el canal seleccionado.

Al investigar una cancelación, compara:

  • el plazo límite del cliente y la señal de cancelación;
  • el almacenamiento en búfer y los tiempos de espera por inactividad del proxy;
  • el tiempo hasta la primera salida efectiva;
  • si algún evento llegó al cliente;
  • el modelo y el grupo seleccionados;
  • el ID de la solicitud y la marca de tiempo de la cancelación.

Diagnostica un flujo que no devuelve texto visible

Sigue este orden:

  1. Repite la solicitud con "stream": false.
  2. Confirma que el modelo admite el endpoint seleccionado.
  3. Captura los eventos sin procesar antes de que la interfaz los transforme.
  4. Revisa si la respuesta contiene una llamada a herramienta o un evento de razonamiento en lugar de texto.
  5. Verifica que ningún intermediario esté almacenando el cuerpo en búfer.
  6. Confirma que el analizador maneja el evento terminal del endpoint.
  7. Revisa en los registros de uso el estado, la primera salida, el tiempo total y la cancelación.

Si la solicitud sin streaming funciona y llegan eventos de streaming sin procesar, la falla suele estar en el análisis o la visualización del cliente, no en la autenticación ni en el acceso al modelo. Si no llega ningún evento sin procesar, continúa con la guía de errores de API de IA.

Lista de verificación de streaming en producción

  • Asocia explícitamente el analizador a Chat Completions o a Responses.
  • Desactiva el almacenamiento en búfer en el cliente HTTP y en cada capa de proxy que controles.
  • Prueba los eventos de texto, razonamiento, solo herramientas y error que use la aplicación.
  • Distingue la primera salida efectiva del primer texto visible.
  • Usa tiempos de espera adecuados para cada fase y una señal de cancelación intencional.
  • Trata los reintentos como solicitudes nuevas, salvo que la operación tenga un diseño de idempotencia seguro.
  • Conserva el ID de la solicitud, el estado, el modelo y el grupo seleccionados y los tiempos para el diagnóstico.
  • Compara la decisión de endpoint en Responses API vs. Chat Completions.

Preguntas frecuentes

¿El streaming hace que el modelo genere más rápido?

No necesariamente. El streaming muestra la salida antes; la velocidad de generación y el tiempo previo al primer evento siguen dependiendo del modelo, la ruta, el contexto, el razonamiento y las herramientas.

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

Es posible que la aplicación o un intermediario esté almacenando el cuerpo en búfer, o que el analizador espere fragmentos de Chat Completions mientras recibe eventos de Responses. Captura las tramas sin procesar en el límite de la aplicación antes de cambiar el modelo o la ruta.

¿Un cliente debe reintentar después de que se desconecta un flujo?

Solo si repetir la operación es seguro. Es posible que un flujo desconectado ya haya generado trabajo en el proveedor o actividad de herramientas. Usa reintentos acotados e idempotencia a nivel de aplicación cuando los efectos secundarios duplicados sean un problema.