メインコンテンツまでスキップ

動画の非同期処理を変更する

文字起こしや索引作成は時間がかかるため、APIの応答を待たせずにPython workerで実行します。APIは「この動画を処理してほしい」というジョブをキューへ送り、workerが受け取ります。

処理の入口​

変更したいこと主な場所
ジョブの種類・データ形式apps/worker/worker_python/contracts.py
ジョブ名と処理関数の対応worker_python/tasks/registry.py
状態更新・次のジョブへの受け渡しworker_python/tasks/
文字起こし・検索用データの処理本体worker_python/pipeline/
重複実行の制御worker_python/job_execution.py
AWS Lambdaの入口worker_python/lambda_handler.py

ファイルの実体はすべて apps/worker/ 配下にあります。API側のメッセージ形式は job-message.tsも確認します。

メッセージの形​

{
"type": "transcribe_video",
"job_id": "ジョブを識別するUUID",
"payload": {"video_id": 123}
}

上記は形式の例です。通常はAPIの操作でジョブを作り、手でキューへ投入する必要はありません。

アップロード動画では、transcribe_video が区間の計画を作り、transcribe_video_chunk が区間ごとに保存し、finish_video_transcription がそれらを結合してから index_video_transcript と画像キャッシュのジョブ(build_video_visual_chunk → finish_video_visuals)を開始します。YouTube取り込みに区間ジョブはありません。動画の状態も参照してください。

開始できる状態は各タスクで検証し、DBの条件付き更新でも保存済みの状態を確認します。 文字起こしは pending/error から開始し、processing は再開、indexing は索引タスクへ 引き継ぎ、completed の重複配送はスキップします。uploading や未知の状態では、 DB更新や外部API呼び出しの前に拒否します。

再試行を前提にする​

SQSは同じメッセージを複数回届ける可能性があります。workerは job_id の実行記録と期限付きの実行権を使い、完了した処理の重複を避けます。後続ジョブのIDも親ジョブから決定します。

処理を追加するときは「途中で失敗して再実行されても、データや後続ジョブが重複しないか」を確認します。これを冪等性と呼びます。例外を握り潰すと再試行されず、状態だけが途中で残ることがあります。

タスクは結果データを返しません。dispatcherはタスクが正常に戻った後に完了を記録し、 例外が出た場合は既存の再試行処理へ渡します。SQS利用時の全動画の再索引は動画ごとの ジョブへ分割し、各動画の失敗を個別に再試行します。SQS未設定のローカル実行では 件数をログへ記録し、失敗した動画があれば例外を送出します。

DBトランザクションの区切り​

DB処理の単位を with db_connection() as conn で囲みます。正常終了時はコミット、 例外時はロールバックし、コミット自体が失敗しても接続を閉じます。文字起こし・埋め込み・ 評価の外部API呼び出しはブロックの外で行い、待機中にDB接続やトランザクションを 保持しないようにします。 接続を受け取るヘルパーは呼び出し元のトランザクション内でSQLを実行し、確定時点は 呼び出し元が管理します。

一つの接続で複数のトランザクションを扱う場合は、途中の明示的なコミットが必要です。 アカウント削除では完了した段階ごとに確定し、動画ごとにもトランザクションを区切ります。 ストレージ削除の失敗後も、残っている処理を再試行できます。

ローカルで追う​

Pythonのコードを編集したら、起動中のworkerを再起動して読み直します。依存パッケージを変更した場合はイメージの再ビルドも必要です。

docker compose restart worker
docker compose logs --tail=100 worker
docker compose logs -f worker

画面から短い動画を登録し、対象の動画IDでログを追います。Ctrl+C でログ表示を止めてもworkerは動き続けます。文字起こし・埋め込みを実行すると、設定した外部APIが呼ばれます。

Pythonのテスト環境とコマンドはテストの使い分けを参照してください。接続先やモデル設定は worker READMEにあります。

関連: ジョブの配送と回復。

ホスト環境の実行系統​

AWS環境では、メディア処理・検索処理・アカウント削除を別々のSQSキューと Lambda関数へ配送します。各系統は独立したDLQ、同時実行数、監視アラームを持ちます。 既存のキューと関数はメディア用として維持し、移行前の混在メッセージも処理します。 APIとPythonの送信元はジョブ種別に応じて SQS_MEDIA_QUEUE_URL、 SQS_SEARCH_QUEUE_URL、SQS_ACCOUNT_QUEUE_URL を選択します。 未設定の系統は SQS_QUEUE_URL へ送信するため、ローカル・オンプレの単一キュー構成も使えます。 コード、コンテナイメージ、IAMロールは共有します。

SQS利用時の全件再インデックスは、1回につき最大25動画のIDを個別ジョブへ配り、 残りを継続ジョブへ引き継ぎます。各ページは対象動画があれば配送前に埋め込みの スキーマを検証し、不整合時は子・継続ジョブを送らず親を再試行対象にします。 子ジョブのIDは親から決定し、配送に失敗した親を 再試行しても完了済みの子を繰り返し実行しません。各動画の失敗は個別に再試行されます。 親の成功は配送受付を意味するため、完了確認には検索系統のエラー、滞留、DLQを確認します。 全体の再構築中にグローバルロックは保持しません。モデル・スキーマ変更時は別途移行を調整してください。 設定値と移行順序は worker README とインフラのデプロイ手順を参照してください。