Migrer une application Node.js utilisant le SDK OpenAI sans perdre les signaux d’incident

Délimiter la migration

Lors de la migration d’une application Node.js, évitez de modifier en même temps le SDK, le point de terminaison, le modèle et le code de streaming. Commencez par effectuer une requête sans streaming avec la nouvelle configuration, testez ensuite le streaming, puis comparez la gestion des échecs. Vous pourrez ainsi déterminer si le problème vient des identifiants, du routage, de la compatibilité de la requête ou du traitement du flux.

Le guide des bibliothèques d’OpenAI recommande le SDK officiel JavaScript/TypeScript pour JavaScript côté serveur et montre comment lire la clé API depuis l’environnement. Il présente également une requête de base avec l’API Responses. Consultez le guide des SDK et de la CLI d’OpenAI et le dépôt openai-node pour connaître les options et les détails actuels du SDK.

Prérequis et configuration

Utilisez une version de Node.js prise en charge par la version du SDK installée, installez le package et fournissez les identifiants via l’environnement de déploiement :

npm install openai
export OPENAI_API_KEY="your_api_key_here"

La commande de variable d’environnement est destinée à un shell local de type Unix. En production, définissez le secret équivalent dans l’environnement de votre hôte ou conteneur. Ne l’ajoutez pas au contrôle de version, ne l’affichez pas dans les journaux et ne l’exposez pas dans le code frontend.

Pour l’API OpenAI standard, initialisez le client avec son point de terminaison par défaut :

import OpenAI from "openai";

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

Les valeurs de délai d’expiration et de nouvelle tentative ci-dessus illustrent des choix possibles pour une application ; elles ne constituent pas des recommandations universelles. Consultez la documentation de la version du SDK installée avant de vous fier à des options ou valeurs par défaut spécifiques.

Si vous migrez vers un autre point de terminaison, configurez baseURL uniquement après avoir confirmé le chemin d’API documenté par le fournisseur et les champs de requête pris en charge. La compatibilité est conditionnelle : une URL compatible avec OpenAI ne garantit pas, à elle seule, que tous les modèles, paramètres, événements de streaming ou réponses d’erreur se comportent de la même façon. Utilisez la clé adaptée à ce point de terminaison et testez exactement la forme de requête prévue en production.

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

Il s’agit d’un exemple de configuration. Vérifiez la prise en charge de baseURL et les éventuelles exigences propres au point de terminaison dans la documentation de la version de votre SDK et de votre destination. Ne définissez pas une URL personnalisée simplement pour faire disparaître une requête qui échoue ; déterminez d’abord quel hôte l’application doit contacter.

Tester une requête à l’API Responses avant le streaming

Une requête minimale permet de distinguer les problèmes liés au point de terminaison et à l’authentification de ceux liés au traitement du flux :

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

console.log(response.output_text);

Choisissez un modèle auquel le compte et le point de terminaison ont accès. L’exemple utilise une variable d’environnement afin que le choix du modèle soit explicite, plutôt que supposé implicitement. Si cette requête échoue, examinez le statut et la réponse avant d’ajouter la logique de streaming.

Diffuser la sortie et consigner la fin du flux

Pour l’API Responses, demandez un flux et traitez ses événements. Voici un exemple de mise en œuvre ; vérifiez les types d’événements en fonction de la version du SDK que vous installez :

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;
}

Ne considérez pas le texte déjà transmis à un utilisateur comme une preuve de réussite de la requête. Un flux peut fournir une sortie partielle, puis échouer ou s’interrompre de façon inattendue. Votre application doit décider si elle conserve le texte partiel, réessaie ou marque la réponse comme incomplète. Relancer une génération dont une partie a déjà été transmise peut dupliquer le contenu visible par l’utilisateur, sauf si l’interface gère explicitement ce cas.

Diagnostiquer les échecs à partir de signaux observables

Pour chaque requête, consignez un ensemble réduit et cohérent de champs : horodatage, hôte du point de terminaison (sans identifiants), identifiant du modèle, temps écoulé, statut HTTP s’il est disponible, classe ou nom de l’erreur du SDK, identifiant de requête s’il est disponible et état de fin du flux. Masquez les prompts et le texte des réponses lorsqu’ils peuvent contenir des données sensibles.

Ces éléments sont des pistes de diagnostic, pas des causes certaines. Un code de statut ne permet pas, à lui seul, d’identifier le système responsable. Lorsque c’est possible, comparez les horodatages et les identifiants de requête entre les journaux de l’application et ceux du fournisseur, et évitez de relancer aveuglément des processus applicatifs non idempotents.

Liste de vérification pour la migration

1. Verrouillez et consignez la version du SDK ; consultez ses exigences actuelles concernant Node.js et la configuration.
2. Confirmez l’URL de destination, la méthode d’authentification, l’accès au modèle et les paramètres de requête pris en charge.
3. Exécutez une requête sans streaming depuis un environnement proche de la production.
4. Testez un flux complet, un flux interrompu et une requête rejetée.
5. Vérifiez que les journaux contiennent des métadonnées utiles au diagnostic des échecs, sans identifiants ni contenu sensible.
6. Déployez progressivement le changement et comparez les statuts, la latence et les signaux de fin avec le chemin précédent.

Une migration réussie ne se résume pas à obtenir une réponse. L’application doit pouvoir distinguer une réponse complète d’une sortie partielle et indiquer à l’équipe d’exploitation où chercher lorsqu’une requête échoue.