장애 신호를 놓치지 않고 Node.js OpenAI SDK 앱 마이그레이션하기

마이그레이션 범위부터 정하기

Node.js 애플리케이션을 이전할 때 SDK, 엔드포인트, 모델, 스트리밍 코드를 한꺼번에 바꾸지 마세요. 먼저 새 설정으로 스트리밍을 사용하지 않는 요청을 한 번 보내고, 그다음 스트리밍을 테스트한 뒤 마지막으로 오류 처리 방식을 비교하세요. 이렇게 하면 문제가 인증 정보, 라우팅, 요청 호환성, 스트림 소비 중 어디에서 비롯됐는지 분리해 파악할 수 있습니다.

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

이는 설정 패턴의 예시입니다. SDK 버전과 대상 서비스의 문서에서 baseURL 지원 여부와 엔드포인트별 요구사항을 확인하세요. 실패한 요청을 없애기 위해 무작정 사용자 지정 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 상태 코드(있는 경우), SDK 오류 클래스/이름, 요청 ID(있는 경우), 스트림 완료 여부를 포함합니다. 프롬프트나 응답 텍스트에 민감한 정보가 포함될 수 있다면 이를 마스킹하세요.

이 항목들은 진단의 출발점이지 확정적인 원인은 아닙니다. 상태 코드만으로는 어느 시스템에서 문제가 발생했는지 알 수 없습니다. 가능한 경우 애플리케이션 로그와 제공업체 로그에서 타임스탬프와 요청 ID를 비교하고, 멱등성이 보장되지 않는 애플리케이션 워크플로를 무턱대고 재시도하지 마세요.

마이그레이션 체크리스트

1. SDK 버전을 고정하고 기록한 뒤, 현재 Node.js 및 설정 요구사항을 확인하세요.
2. 대상 URL, 인증 방식, 모델 접근 권한, 지원되는 요청 매개변수를 확인하세요.
3. 프로덕션과 유사한 런타임에서 스트리밍을 사용하지 않는 요청을 한 번 실행하세요.
4. 스트림의 정상 완료, 중단, 요청 거부를 각각 테스트하세요.
5. 로그에 유용한 실패 메타데이터는 포함되지만 인증 정보나 민감한 콘텐츠는 포함되지 않는지 확인하세요.
6. 변경을 통제된 방식으로 배포하고 이전 경로와 상태, 지연 시간, 완료 신호를 비교하세요.

마이그레이션의 성공은 단순히 응답 하나를 받는 데 그치지 않습니다. 완료된 응답과 부분 출력을 구분하고, 요청이 실패했을 때 운영자가 조사할 지점을 파악할 수 있는 애플리케이션을 만드는 것이 중요합니다.