Migra una app Node.js con OpenAI SDK sin perder señales de incidentes

Define primero el alcance de la migración

Al migrar una aplicación Node.js, evita cambiar a la vez el SDK, el endpoint, el modelo y el código de streaming. Primero haz una solicitud sin streaming con la nueva configuración; después prueba el streaming y, por último, compara el tratamiento de errores. Así podrás determinar si el problema se debe a las credenciales, el enrutamiento, la compatibilidad de la solicitud o el consumo del flujo.

La guía de bibliotecas de OpenAI recomienda el SDK oficial de JavaScript/TypeScript para JavaScript en el servidor y muestra cómo leer la clave API desde el entorno. También incluye una solicitud básica mediante Responses API. Consulta la guía de SDK y CLI de OpenAI y el repositorio openai-node para ver las opciones y los detalles actuales del SDK.

Requisitos previos y configuración

Usa una versión de Node.js compatible con la versión instalada del SDK, instala el paquete y proporciona las credenciales mediante el entorno de despliegue:

npm install openai
export OPENAI_API_KEY="your_api_key_here"

El comando de variable de entorno es para un shell local similar a Unix. En producción, define el secreto equivalente en el entorno del host o del contenedor. No lo incluyas en el control de versiones, no lo imprimas en los registros ni lo expongas en el código del frontend.

Para la API estándar de OpenAI, inicializa el cliente con el endpoint predeterminado:

import OpenAI from "openai";

const client = new OpenAI({
  // The SDK reads OPENAI_API_KEY from the environment by default.
  timeout: 30_000,
  maxRetries: 2,
});

Los valores de timeout y reintentos anteriores son opciones ilustrativas de la aplicación, no recomendaciones universales. Consulta la documentación de la versión instalada del SDK antes de depender de opciones o valores predeterminados específicos.

Si vas a migrar a otro endpoint, configura baseURL solo después de confirmar la ruta de API documentada por el proveedor y los campos de solicitud compatibles. La compatibilidad es condicional: que una URL sea compatible con OpenAI no demuestra por sí solo que todos los modelos, parámetros, eventos de streaming o respuestas de error se comporten igual. Usa la clave adecuada para ese endpoint y prueba la forma exacta de la solicitud de producción.

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

Este es un patrón de configuración ilustrativo. Confirma la compatibilidad con baseURL y los requisitos específicos del endpoint en la documentación de la versión del SDK y del destino. No configures una URL personalizada solo para hacer desaparecer una solicitud fallida: determina primero a qué host debe conectarse la aplicación.

Prueba una solicitud de Responses API antes del streaming

Una solicitud mínima ayuda a separar los problemas de endpoint y autenticación de los relacionados con el manejo del flujo:

const response = await client.responses.create({
  model: process.env.OPENAI_MODEL,
  input: "Reply with the word ready.",
});

console.log(response.output_text);

Elige un modelo disponible para la cuenta y el endpoint. El ejemplo usa una variable de entorno para indicar explícitamente el modelo, en lugar de darlo por supuesto. Si esta solicitud falla, diagnostica el estado y la respuesta antes de añadir la lógica de streaming.

Transmite la salida y registra cuándo termina

Para Responses API, solicita un flujo y consume sus eventos. El siguiente patrón es ilustrativo; comprueba los tipos de evento en la versión del SDK que instales:

try {
  const stream = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Summarize the incident in one sentence.",
    stream: true,
  });

  let completed = false;

  for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.completed") {
      completed = true;
    } else if (event.type === "response.failed") {
      throw new Error("Response stream reported a failure");
    }
  }

  if (!completed) {
    throw new Error("Stream ended without a completion event");
  }
} catch (error) {
  console.error("OpenAI request failed", {
    name: error?.name,
    status: error?.status,
    requestId: error?.request_id,
    message: error?.message,
  });
  throw error;
}

No consideres que el texto ya enviado al usuario demuestra que la solicitud tuvo éxito. El flujo puede entregar una salida parcial y luego fallar o terminar de forma inesperada. Tu aplicación debe decidir si conserva el texto parcial, reintenta o marca la respuesta como incompleta. Reintentar una generación que ya se entregó parcialmente puede duplicar contenido visible para el usuario, salvo que la interfaz lo gestione de forma explícita.

Diagnostica los fallos a partir de señales observables

Registra un conjunto pequeño y coherente de campos para cada solicitud: marca temporal, host del endpoint (sin credenciales), identificador del modelo, tiempo transcurrido, estado HTTP cuando esté disponible, clase o nombre del error del SDK, ID de solicitud cuando esté disponible y si el flujo se completó. Oculta los prompts y el texto de respuesta si pueden contener datos sensibles.

Son puntos de partida para el diagnóstico, no causas definitivas. Un código de estado por sí solo no identifica el sistema responsable. Cuando sea posible, compara las marcas temporales y los ID de solicitud en los registros de la aplicación y del proveedor; evita reintentar a ciegas flujos de trabajo de aplicación no idempotentes.

Lista de comprobación para la migración

1. Fija y registra la versión del SDK; revisa los requisitos actuales de Node.js y configuración.
2. Confirma la URL de destino, el método de autenticación, el acceso al modelo y los parámetros de solicitud admitidos.
3. Ejecuta una solicitud sin streaming desde un entorno similar al de producción.
4. Prueba un flujo completo, uno interrumpido y una solicitud rechazada.
5. Verifica que los registros incluyan metadatos útiles para diagnosticar fallos, pero no credenciales ni contenido sensible.
6. Despliega mediante un cambio controlado y compara el estado, la latencia y las señales de finalización con la ruta anterior.

El resultado útil de una migración no es simplemente obtener una respuesta correcta. La aplicación debe poder distinguir una respuesta completada de una salida parcial y ayudar a quien opera el sistema a saber dónde investigar cuando falla una solicitud.