障害の兆候を見失わずにNode.js OpenAI SDKアプリを移行する方法

まず移行の範囲を絞る

Node.jsアプリを移行する際は、SDK、エンドポイント、モデル、ストリーミングコードを一度に変更しないようにしましょう。まず新しい設定でストリーミングを使わないリクエストを1件実行し、次にストリーミングをテストして、最後に障害処理を比較します。こうすることで、問題の原因が認証情報、ルーティング、リクエストの互換性、ストリームの処理のどこにあるかを切り分けられます。

OpenAIのライブラリーガイドでは、サーバーサイドJavaScriptに公式JavaScript/TypeScript SDKを推奨し、環境変数からAPIキーを読み込む方法を示しています。また、Responses APIを使った基本的なリクエストも紹介しています。現在のSDKのオプションや詳細は、OpenAIのSDKとCLIガイドおよびopenai-nodeリポジトリーを参照してください。

前提条件と設定

インストールするSDKのバージョンに対応したNode.jsランタイムを使い、パッケージをインストールして、デプロイ環境から認証情報を渡します。

npm install openai
export OPENAI_API_KEY="your_api_key_here"

環境変数を設定するこのコマンドは、ローカルのUnix系シェル向けです。本番環境では、ホストまたはコンテナーの環境に同等のシークレットを設定してください。ソース管理にコミットしたり、ログに出力したり、フロントエンドのコードから公開したりしないでください。

標準のOpenAI APIを使う場合は、デフォルトのエンドポイントでクライアントを初期化します。

import OpenAI from "openai";

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

上記のタイムアウト値と再試行値は、アプリケーション設定の例であり、あらゆる環境に適した推奨値ではありません。特定のオプションやデフォルト値に依存する前に、インストールしたSDKバージョンのドキュメントを確認してください。

別のエンドポイントに移行する場合は、そのプロバイダーが文書化しているAPIパスと、対応するリクエストフィールドを確認してからbaseURLを設定します。互換性は条件付きです。OpenAI互換のURLだからといって、すべてのモデル、パラメーター、ストリーミングイベント、エラーレスポンスが同じように動作するとは限りません。そのエンドポイントに適したキーを使用し、本番環境と同じリクエスト形式でテストしてください。

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

これは設定方法の例です。baseURLへの対応状況とエンドポイント固有の要件について、使用するSDKバージョンおよび接続先のドキュメントを確認してください。リクエストの失敗を解消するためだけにカスタムURLを設定してはいけません。まず、アプリケーションが接続すべきホストを特定してください。

ストリーミングの前にResponses APIのリクエストをテストする

最小限のリクエストを実行すると、エンドポイントや認証の問題をストリーム処理の問題から切り分けやすくなります。

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

console.log(response.output_text);

アカウントとエンドポイントで利用可能なモデルを選んでください。この例では環境変数を使い、モデルの選択を明示しています。暗黙の前提にはしていません。このリクエストが失敗した場合は、ストリーム処理を追加する前にステータスとレスポンスを調べてください。

出力をストリーミングし、完了を記録する

Responses APIではストリームをリクエストし、イベントを処理します。以下は実装例です。インストールするSDKバージョンに合わせてイベントタイプを確認してください。

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

ユーザーにすでに表示したテキストを、リクエスト成功の証拠として扱わないでください。ストリームは部分的な出力を返した後に失敗したり、予期せず終了したりすることがあります。部分テキストを保持するか、再試行するか、応答を未完了とするかは、アプリケーション側で決めてください。UIで明示的に処理しない限り、部分的に配信した生成を再試行すると、ユーザーに見える内容が重複する可能性があります。

観測可能なシグナルから障害を診断する

各リクエストについて、共通の項目を少数記録します。タイムスタンプ、エンドポイントのホスト（認証情報は含めない）、モデル識別子、経過時間、取得できる場合はHTTPステータスとリクエストID、SDKのエラークラスまたは名前、ストリームが完了したかどうかです。プロンプトやレスポンステキストに機密データが含まれる可能性がある場合は、必ず秘匿化してください。

これらは診断の出発点であり、原因を断定するものではありません。ステータスコードだけでは、どのシステムに原因があるかは特定できません。利用可能な場合は、アプリケーションとプロバイダーのログでタイムスタンプやリクエストIDを照合してください。また、冪等でないアプリケーションの処理を、安易に再試行しないでください。

移行チェックリスト

1. SDKのバージョンを固定して記録し、Node.jsと設定に関する最新要件を確認する。
2. 接続先URL、認証方式、モデルへのアクセス、対応するリクエストパラメーターを確認する。
3. 本番環境に近いランタイムから、ストリーミングを使わないリクエストを1件実行する。
4. ストリームの正常完了、中断、リクエスト拒否をテストする。
5. ログに役立つ障害メタデータが含まれ、認証情報や機密データが含まれていないことを確認する。
6. 変更範囲を制御してリリースし、以前の経路とステータス、レイテンシ、完了シグナルを比較する。

移行の成果は、レスポンスが成功することだけではありません。回答が完了したのか、出力が途中なのかをアプリケーションが判別でき、リクエストの失敗時に運用担当者が調査箇所を判断できることも重要です。