Budowanie kolejki zadań AI Video w TypeScript

Generowanie wideo przez AI nie jest standardowym żądaniem HTTP. Użytkownik wysyła prompt i ustawienia. Na otrzymanie wyniku trzeba czekać kilka minut.

Twój backend musi obsługiwać kilka kroków:

  • Walidacja danych wejściowych.
  • Utworzenie rekordu zadania.
  • Przesłanie zadania do dostawcy.
  • Odpytywanie o wyniki (polling).
  • Obsługa błędów.
  • Wyświetlanie statusu użytkownikowi.

Powinieneś użyć kolejki oraz warstwy adaptera. Zapobiega to sytuacji, w której kod specyficzny dla danego dostawcy psuje całą aplikację.

Zdefiniuj podstawowy typ zadania, który będzie służył jako kontrakt Twojego produktu.

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

Użyj interfejsu dla swoich dostawców. Dzięki temu logika workerów pozostanie przejrzysta.

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

Stosuj się do tych dobrych praktyk w swoim procesie (workflow):

  1. Najpierw wykonuj tanie sprawdzenia. Waliduj prompty i czas trwania przed wywoływaniem kosztownych API.

  2. Zastosuj strategię odpytywania (polling). Zaimplementuj pętlę z rosnącymi opóźnieniami.

  3. Obsługuj opóźnienia. Jeśli zadanie trwa zbyt długo, zmień jego status na "delayed". Użyj osobnego workera do późniejszego sprawdzania opóźnionych zadań.

  4. Normalizuj błędy. Nigdy nie pokazuj użytkownikom surowych błędów od dostawcy. Mapuj błędy techniczne na komunikaty zrozumiałe dla człowieka.

Przykładowe komunikaty użytkownika:

  • "queued": Twoje wideo czeka na rozpoczęcie.
  • "running": Twoje wideo jest generowane.
  • "delayed": To zajmuje więcej czasu niż zwykle.
  • "moderation_rejected": Nie można było przetworzyć tego żądania.

Traktuj generowanie wideo przez AI jako system zadań. Stabilna kolejka i jasna taksonomia błędów sprawiają, że produkt jest łatwiejszy w utrzymaniu i skalowaniu.

Źródło: https://dev.to/miao_cunhui_587ccddb6acc1/building-an-ai-video-job-queue-in-typescript-1349