Eine Node.js-App mit dem OpenAI SDK migrieren, ohne Vorfallsignale zu verlieren

Zunächst den Umfang der Migration festlegen

Ändern Sie beim Umstieg einer Node.js-Anwendung nicht SDK, Endpunkt, Modell und Streaming-Code gleichzeitig. Senden Sie zunächst mit der neuen Konfiguration eine Anfrage ohne Streaming, testen Sie dann das Streaming und vergleichen Sie zuletzt die Fehlerbehandlung. So lässt sich eingrenzen, ob ein Problem von Zugangsdaten, Routing, Anfragekompatibilität oder der Verarbeitung des Streams herrührt.

Der Bibliotheksleitfaden von OpenAI empfiehlt für serverseitiges JavaScript das offizielle JavaScript-/TypeScript-SDK und zeigt, wie der API-Schlüssel aus der Umgebung gelesen wird. Außerdem veranschaulicht er eine einfache Anfrage über die Responses API. Aktuelle SDK-Optionen und Details finden Sie im SDK- und CLI-Leitfaden von OpenAI und im openai-node-Repository.

Voraussetzungen und Konfiguration

Verwenden Sie eine von Ihrer installierten SDK-Version unterstützte Node.js-Laufzeitumgebung, installieren Sie das Paket und stellen Sie die Zugangsdaten über Ihre Bereitstellungsumgebung bereit:

npm install openai
export OPENAI_API_KEY="your_api_key_here"

Der Befehl für die Umgebungsvariable ist für eine lokale Unix-ähnliche Shell gedacht. Legen Sie das entsprechende Secret in der Produktionsumgebung Ihres Hosts oder Containers fest. Nehmen Sie es nicht in die Versionsverwaltung auf, geben Sie es nicht in Logs aus und legen Sie es nicht im Frontend-Code offen.

Initialisieren Sie den Client für die standardmäßige OpenAI API mit dem Standardendpunkt:

import OpenAI from "openai";

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

Die oben angegebenen Timeout- und Wiederholungswerte sind beispielhafte Entscheidungen für eine Anwendung und keine allgemeinen Empfehlungen. Prüfen Sie die Dokumentation der installierten SDK-Version, bevor Sie sich auf bestimmte Optionen oder Standardwerte verlassen.

Wenn Sie zu einem anderen Endpunkt migrieren, konfigurieren Sie baseURL erst, nachdem Sie den dokumentierten API-Pfad und die unterstützten Anfragefelder des Anbieters überprüft haben. Kompatibilität ist nicht selbstverständlich: Eine OpenAI-kompatible URL belegt für sich genommen nicht, dass sich jedes Modell, jeder Parameter, jedes Streaming-Ereignis und jede Fehlerantwort identisch verhält. Verwenden Sie den für diesen Endpunkt passenden Schlüssel und testen Sie genau die Anfrageform, die in der Produktion zum Einsatz kommt.

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

Dies ist ein beispielhaftes Konfigurationsmuster. Prüfen Sie in der Dokumentation Ihrer SDK-Version und des Zielendpunkts, ob baseURL unterstützt wird und welche besonderen Anforderungen für den Endpunkt gelten. Legen Sie nicht einfach eine benutzerdefinierte URL fest, nur damit eine fehlgeschlagene Anfrage verschwindet. Ermitteln Sie zuerst, welchen Host die Anwendung erreichen soll.

Eine Anfrage an die Responses API vor dem Streaming testen

Mit einer minimalen Anfrage lassen sich Probleme mit Endpunkt und Authentifizierung von Problemen bei der Stream-Verarbeitung trennen:

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

console.log(response.output_text);

Wählen Sie ein Modell, das für das Konto und den Endpunkt verfügbar ist. Im Beispiel wird eine Umgebungsvariable verwendet, damit die Modellauswahl ausdrücklich festgelegt und nicht stillschweigend vorausgesetzt wird. Schlägt diese Anfrage fehl, untersuchen Sie Status und Antwort, bevor Sie Streaming-Logik hinzufügen.

Ausgaben streamen und den Abschluss erfassen

Fordern Sie für die Responses API einen Stream an und verarbeiten Sie dessen Ereignisse. Das folgende Muster dient als Beispiel. Prüfen Sie die Ereignistypen anhand der von Ihnen installierten SDK-Version:

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

Behandeln Sie Text, der bereits an Nutzende ausgegeben wurde, nicht als Beleg dafür, dass die Anfrage erfolgreich war. Ein Stream kann zunächst Teilausgaben liefern und anschließend fehlschlagen oder unerwartet enden. Ihre Anwendung sollte festlegen, ob sie den bisherigen Text beibehält, einen neuen Versuch startet oder die Antwort als unvollständig kennzeichnet. Wird eine teilweise ausgegebene Generierung wiederholt, kann nutzerseitig sichtbarer Inhalt doppelt erscheinen, sofern die Benutzeroberfläche dies nicht ausdrücklich berücksichtigt.

Fehler anhand beobachtbarer Signale diagnostizieren

Erfassen Sie für jede Anfrage ein kleines, einheitliches Set an Feldern: Zeitstempel, Endpunkt-Host (ohne Zugangsdaten), Modellkennung, verstrichene Zeit, sofern vorhanden HTTP-Status und Request-ID, Klasse bzw. Name des SDK-Fehlers sowie den Status des Streams. Entfernen oder maskieren Sie Prompts und Antworttexte, wenn sie sensible Daten enthalten können.

Diese Hinweise sind erste Ansatzpunkte für die Diagnose, keine eindeutigen Ursachen. Ein Statuscode allein zeigt nicht, welches System verantwortlich ist. Vergleichen Sie, sofern verfügbar, Zeitstempel und Request-IDs in den Anwendungs- und Anbieter-Logs. Wiederholen Sie nicht blind nicht-idempotente Anwendungsabläufe.

Migrations-Checkliste

1. Fixieren und dokumentieren Sie die SDK-Version. Prüfen Sie die aktuellen Anforderungen an Node.js und die Konfiguration.
2. Bestätigen Sie Ziel-URL, Authentifizierungsmethode, Modellzugriff und unterstützte Anfrageparameter.
3. Senden Sie eine Anfrage ohne Streaming aus einer produktionsähnlichen Laufzeitumgebung.
4. Testen Sie einen vollständigen Stream, einen unterbrochenen Stream und eine abgewiesene Anfrage.
5. Prüfen Sie, ob die Logs nützliche Metadaten zu Fehlern enthalten, aber keine Zugangsdaten oder sensiblen Inhalte.
6. Führen Sie die Änderung kontrolliert ein und vergleichen Sie Status, Latenz und Abschlusssignale mit dem bisherigen Ablauf.

Eine erfolgreiche Antwort allein ist kein ausreichendes Migrationsergebnis. Die Anwendung sollte eine abgeschlossene Antwort von einer Teilausgabe unterscheiden und Verantwortlichen zeigen können, wo sie bei einer fehlgeschlagenen Anfrage nachsehen müssen.