TypeScript로 AI 비디오 작업 큐(Job Queue) 구축하기

AI 비디오 생성은 일반적인 HTTP 요청이 아닙니다. 사용자가 프롬프트와 설정을 보내면, 결과가 도착하기까지 몇 분이 소요됩니다.

백엔드는 다음과 같은 여러 단계를 처리해야 합니다:

  • 입력값 검증.
  • 작업 레코드 생성.
  • 제공업체(provider)에 작업 제출.
  • 결과 폴링(poll).
  • 실패 처리.
  • 사용자에게 상태 표시.

큐(queue)와 어댑터 레이어(adapter layer)를 사용해야 합니다. 이렇게 하면 특정 제공업체 전용 코드가 전체 애플리케이션을 망가뜨리는 것을 방지할 수 있습니다.

제품의 규약(contract) 역할을 할 핵심 작업 타입을 정의합니다.

type JobStatus = "queued" | "validating" | "running" | "delayed" | "succeeded" | "failed";

type VideoJob = {
  id: string;
  userId: string;
  model: string;
  prompt: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  status: JobStatus;
  providerTaskId?: string;
  outputUrl?: string;
  errorCode?: VideoJobErrorCode;
};

제공업체를 위한 인터페이스를 사용하세요. 이렇게 하면 워커(worker) 로직을 깔끔하게 유지할 수 있습니다.

interface VideoProvider {
  submit(job: VideoJob): Promise<{ providerTaskId: string }>;
  poll(providerTaskId: string): Promise<
    | { status: "running" }
    | { status: "succeeded"; outputUrl: string }
    | { status: "failed"; error: unknown }
  >;
  normalizeError(error: unknown): VideoJobErrorCode;
}

워크플로우를 위해 다음의 베스트 프랙티스를 따르세요:

  1. 비용이 적게 드는 검증을 먼저 수행하세요. 값비싼 API를 호출하기 전에 프롬프트와 재생 시간을 검증하세요.

  2. 폴링 전략을 사용하세요. 지연 시간을 점진적으로 늘리는 루프를 구현하세요.

  3. 지연을 처리하세요. 작업이 너무 오래 걸리면 "delayed" 상태로 이동시키세요. 나중에 지연된 작업을 확인하기 위해 별도의 워커를 사용하세요.

  4. 에러를 정규화하세요. 제공업체의 원시(raw) 에러를 사용자에게 그대로 보여주지 마세요. 기술적인 에러를 사람이 읽을 수 있는 메시지로 매핑하세요.

사용자 메시지 예시:

  • "queued": 비디오가 시작되기를 기다리고 있습니다.
  • "running": 비디오를 생성 중입니다.
  • "delayed": 평소보다 시간이 더 걸리고 있습니다.
  • "moderation_rejected": 이 요청을 처리할 수 없습니다.

AI 비디오를 하나의 작업 시스템(job system)으로 취급하세요. 안정적인 큐와 명확한 에러 분류 체계(taxonomy)는 제품을 더 쉽게 유지 관리하고 확장할 수 있게 해줍니다.

Source: https://dev.to/miao_cunhui_587ccddb6acc1/building-an-ai-video-job-queue-in-typescript-1349