Guía de GPT-6 Astra Streaming: Eventos de la API de Respuestas, Herramientas y Manejo de Errores

La transmisión en tiempo real mejora la latencia percibida al entregar eventos mientras GPT-6 Astra está trabajando. No hace que el cómputo subyacente sea gratuito ni elimina los casos de fallo. Un cliente de producción debe ensamblar la salida incremental, renderizar el progreso de las herramientas, distinguir los estados terminales y recuperarse cuando una conexión falla.

Comienza con eventos tipificados

Establece stream: true e itera sobre el flujo de eventos tipados del SDK.

const stream = await client.responses.create({
  model: "gpt-6-astra",
  input: "Explica el plan de migración en cinco pasos.",
  stream: true
});

para await (const event of stream) {
  switch (event.type) {
    .output_text.delta
      process.stdout.write(event.delta);
      break;
    ."respuesta.completada"
      console.log("\nCompleto");
      break;
    .caso "response.failed":
      console.error("Falló", event.response.error);
      break;
    case "error":
      console.error(event.message);
      break;
  }
}

Los eventos comunes del ciclo de vida del texto incluyen response.created, response.output_text.delta, response.completed y error. La unión completa de eventos también contiene eventos de elemento de salida, parte de contenido, anotación, rechazo, fallo y otros. Maneje los tipos de eventos desconocidos de manera segura para que un evento recién agregado no bloquee un cliente más antiguo.

Construye un ensamblador, no un bucle de añadido de texto

Una respuesta puede contener múltiples elementos de salida y partes de contenido. Indexa el estado por respuesta, elemento de salida y parte de contenido, en lugar de agregar cada delta a una cadena global. Deduplica utilizando identificadores documentados o datos de secuencia cuando estén disponibles, y renderiza solo el estado local confirmado.

Las anotaciones y citas pueden llegar por separado del texto. Preserva sus desplazamientos o asociaciones en lugar de eliminarlos durante la concatenación. Trata un objeto de respuesta final como autoritativo cuando esté disponible.

Los estados terminales no son intercambiables

.response.completed significa finalización exitosa. response.failed conlleva un fallo. response.incomplete puede reflejar límites de tokens u otra razón y puede contener una salida parcial útil. Un error a nivel de transporte puede ocurrir sin un evento terminal de respuesta normal.

Nunca marques una solicitud como exitosa solo porque el socket se cerró. Persiste el ID de respuesta tan pronto como llegue response.created, luego guarda el estado terminal por separado.

Transmite la actividad de la herramienta con honestidad

Las llamadas a herramientas introducen fases: planificación del modelo, generación de argumentos, ejecución del servidor o cliente, resultado de la herramienta y generación reanudada. Su interfaz de usuario debe mostrar "Buscando" o "Esperando aprobación" solo cuando exista el evento/estado correspondiente. No invente porcentajes de progreso.

Para funciones ejecutadas por el cliente, ensamble los argumentos completos antes de analizarlos a menos que el contrato de la API admita explícitamente el consumo incremental. Valídelos, ejecútelos una vez y devuelva el resultado usando el ID de la llamada. La transmisión de un evento duplicado no debe desencadenar un efecto secundario duplicado.

Contrapresión y rendimiento de la interfaz de usuario

Los deltas del tamaño de un token pueden llegar más rápido de lo que un navegador debería renderizar. Almacena en búfer brevemente y actualiza la interfaz de usuario a un ritmo controlado. Esto reduce el trabajo de diseño sin perjudicar materialmente la latencia percibida. Limita los búferes en memoria y pausa el procesamiento posterior si tu framework lo admite.

Separa el registro de eventos sin procesar del modelo de vista. El registro de eventos facilita la depuración; el modelo de vista combina los deltas en contenido estable visible para el usuario. Redacta las cargas útiles sensibles de las herramientas antes de registrarlas.

Desconexiones, tiempos de espera y cancelación

Al desconectar, clasifica la operación como desconocida hasta que recuperes el estado. Una respuesta del modelo puede haber continuado en el servidor, y una herramienta externa puede haber actuado ya. Evita reproducir automáticamente las escrituras.

Usa plazos de solicitud y temporizadores de flujo inactivo, pero distingue "sin delta de texto" de "sin actividad"; una llamada larga a una herramienta aún puede ser saludable. La cancelación debe propagarse a tus propias herramientas cancelables. No puede garantizar la reversión de efectos completados.

Si continúa a través del estado de respuesta, conserve la última respuesta confirmada y los resultados de la herramienta. La recuperación específica de WebSocket puede informar previous_response_not_found; la guía oficial de errores recomienda reintentar con el contexto de entrada completo y previous_response_id: null cuando no se pueda resolver el estado.

Observabilidad

Registra el tiempo hasta response.created, el primer delta de texto, el primer evento de herramienta y el evento terminal; duración total; recuentos de eventos; estado terminal; desconexiones; reintentos; y cancelación del usuario. Correlaciona todos los eventos con un ID de solicitud de aplicación y el ID de respuesta de OpenAI.

Prueba de orden mal formado, entrega duplicada, eventos desconocidos, un tiempo de espera de herramienta, un fallo tardío después de texto visible y pérdida de conexión después de una escritura. La corrección de transmisión es la corrección de máquina de estados.

Patrón de implementación del navegador y del servidor

En muchos productos, el servidor de aplicaciones debe mantener la conexión con OpenAI y retransmitir un flujo de eventos sanitizado al navegador. Esto mantiene las credenciales de la API fuera del cliente, centraliza la autorización y permite que el servidor oculte los argumentos internos de las herramientas. El navegador recibe solo los eventos necesarios para la representación: estado, deltas de texto seguros, citas, solicitudes de aprobación y resultado final.

Persistir puntos de control gruesos en lugar de cada carácter. Guardar cada delta genera escrituras excesivas; guardar solo al completarse pierde demasiado en una desconexión. Un intervalo corto o un límite de parte de contenido suele ser un mejor compromiso. Al reconectar, enviar la vista confirmada más reciente y continuar desde el siguiente evento conocido según el diseño de su transporte.

La moderación y la seguridad necesitan una política de transmisión. El texto parcial llega a los usuarios antes de que exista la respuesta final, por lo que una revisión posterior que se ejecute solo al finalizar puede ser demasiado tarde. Elija controles previos a la generación, salvaguardas incrementales, almacenamiento en búfer o transmisión restringida según el riesgo. Los flujos de trabajo de alto riesgo pueden intercambiar intencionalmente algo de inmediatez por revisión.

Finalmente, asegúrate de que los análisis no cuenten dos veces una respuesta reanudada después de una actualización del navegador. El ID de respuesta de OpenAI y tu ID de solicitud de aplicación estable deben unir cada segmento en una sola tarea lógica.

Preguntas Frecuentes

¿El streaming reduce el costo de tokens?

No. Cambia la entrega, no la cantidad de tokens generados.

¿Puedo mostrar resultados parciales de inmediato?

Sí, pero márcalo como en progreso y prepárate para resultados de rechazo, incompletos o fallos.

¿Debería reintentar cuando se cierra la conexión?

Recupera o concilia primero, especialmente si las herramientas pueden causar efectos secundarios. La reproducción ciega puede duplicar acciones.

¿Son idénticos el manejo de eventos SSE y WebSocket?

Comparten conceptos de Respuestas, pero el transporte y el comportamiento de continuación difieren. Siga la guía para el modo seleccionado.

Conclusión

La transmisión confiable de GPT-6 Astra requiere manejo de eventos tipados, un ensamblador estructurado, estados terminales explícitos, ejecución de herramientas idempotente, contrapresión y recuperación. Optimiza la percepción del usuario sobre el progreso sin convertir texto parcial o una conexión cerrada en una afirmación falsa de éxito.