TypeScriptによるAIビデオジョブキューの構築

AIビデオ生成は、標準的なHTTPリクエストではありません。ユーザーがプロンプトと設定を送信してから、結果が届くまでには数分かかります。

バックエンドでは、以下のいくつかのステップを処理する必要があります：

  • 入力のバリデーション。
  • ジョブレコードの作成。
  • プロバイダーへのジョブの送信。
  • 結果のポーリング。
  • 失敗のハンドリング。
  • ユーザーへのステータス表示。

キューとアダプター層を使用すべきです。これにより、プロバイダー固有のコードがアプリケーション全体を壊してしまうのを防ぐことができます。

プロダクトのコントラクト（契約）として機能する、コアなジョブ型を定義します。

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

プロバイダーにはインターフェースを使用します。これにより、ワーカーのロジックをクリーンに保つことができます。

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ビデオをジョブシステムとして扱ってください。安定したキューと明確なエラーの分類体系（taxonomy）があれば、プロダクトのメンテナンスとスケールが容易になります。

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