Skip to content

Repository navigation

Local WhisperX Setup

Jump to bottom
284_vd0w0bv edited this page Jul 30, 2026 · 4 revisions

ローカルWhisperXセットアップ（Docker実行）

対象読者：管理者・上級者（AWSを使わず、手元のGPUマシンで書きおこししたい人） 目的：このPCのGPUで WhisperX を動かし、書きおこしをローカル完結させる。

WhisperX が書きおこしで何をしているか（単語・文字レベルのタイムスタンプ等）は 動作原理 §2 を参照してください。本記事はその「ローカル実行」だけを扱います。

仕組み

書きおこしノードは、環境変数で指定されたバックエンドに従って WhisperX を起動します。常駐サーバーは不要で、書きおこしのたびに docker run で都度実行されます。

  • WHISPERX_EXECUTION_BACKEND=docker のとき：jim60105/docker-whisperX イメージを docker run --gpus all --rm で都度起動し、--output_format json ＋ --return_char_alignments（文字レベルのタイムスタンプ）で結果を受け取る。VADは silero。
  • WHISPERX_EXECUTION_BACKEND=embedded（inprocess / native）のとき：同一プロセス内で WhisperX を直接実行。
アプリ → バックエンド（パイプライン） → 書きおこしノード(TranscribeNode)
                                 └─ docker run --gpus all ghcr.io/jim60105/whisperx:large-v3-ja ...
                                      → JSON（segments[].words[].start/end/score）

📎 コード参照: backend/pipeline/nodes/transcribe.py の TranscribeNode.run()（バックエンド選択）・_run_docker_whisperx()（docker run コマンド組み立て）。

前提条件

要件 最小 推奨
GPU NVIDIA 8GB VRAM NVIDIA 12GB+ VRAM
VRAM 8GB（compute_type=int8） 12GB+（float16）
Docker Docker Desktop 4.x 以上 最新版
NVIDIA Container Toolkit 必須 —
ストレージ（初回） 12GB（イメージ ~10GB + キャッシュ） 20GB+

GPU認識の確認：

docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

エラーが出る場合は NVIDIA Container Toolkit のインストール を行ってください。

設定（環境変数）

バックエンドプロセスに以下の環境変数を渡します。最低限 WHISPERX_EXECUTION_BACKEND=docker を設定すればローカルDocker実行になります。

環境変数 既定値 説明
WHISPERX_EXECUTION_BACKEND （未設定） docker または embedded。ローカルDocker実行は docker
WHISPERX_DOCKER_IMAGE ghcr.io/jim60105/whisperx:large-v3-ja 使用イメージ。タグは {モデル}-{言語}（例 large-v3-en）
WHISPERX_MODEL large-v3 モデルサイズ（no_model/latest タグ時のみ明示渡し）
WHISPERX_LANGUAGE ja 言語コード
WHISPERX_BATCH_SIZE 8 バッチサイズ。VRAM不足時は下げる
WHISPERX_COMPUTE_TYPE float16 VRAM 8GB なら int8
WHISPERX_DEVICE cuda CPUのみなら cpu（非常に遅い）
WHISPERX_CACHE_VOLUME whisperx_hf_cache モデルキャッシュ用Dockerボリューム
WHISPERX_TIMEOUT 3600 1書きおこしのタイムアウト秒
HF_TOKEN （未設定） HuggingFace Token（必要なモデル取得時）

初回は ghcr.io/jim60105/whisperx:large-v3-ja（約10GB）をダウンロードします。モデルキャッシュは WHISPERX_CACHE_VOLUME のDockerボリュームに保持されるため、2回目以降は再ダウンロードされません。

📎 コード参照: いずれも backend/pipeline/nodes/transcribe.py で os.getenv 経由で読み取られます。runtime_settings 経由でも whisperx_execution_backend / whisperx_docker_image / hf_token を渡せます。

チューニング

VRAMが少ない（8GB）

WHISPERX_COMPUTE_TYPE=int8
WHISPERX_BATCH_SIZE=4

英語コンテンツを処理する

WHISPERX_DOCKER_IMAGE=ghcr.io/jim60105/whisperx:large-v3-en
WHISPERX_LANGUAGE=en

対応タグ一覧：{モデル名}-{言語コード}（例 large-v3-ja, base-en, distil-large-v3-en）。

⚠️ WHISPERX_CACHE_VOLUME を名前付きDockerボリュームのまま使い回して言語だけ切り替えると、 最初にシードされたキャッシュが以後もマウントされ続け、別言語のアライメントモデルが 見つからない場合があります。言語を切り替えるときはキャッシュボリュームも再作成するか、 言語ごとに別のボリューム名を使ってください。

デスクトップアプリで書きおこし言語を選ぶ

⚠️ この選択はローカル実行（実行先＝「このPCで実行」）専用です。 実行先を 「AWS / リモート実行」にしている場合、このセレクトは設定タブに表示されず、書きおこし言語は アプリ側からは変更できません。詳細は次節「AWS / リモート実行のときの書きおこし言語」を参照。

デスクトップアプリ（Tauri）のローカルWhisperX転写では、この環境変数を直接編集する代わりに 設定タブ → 上級者向け設定 → 言語ラベル グループの「書きおこし音声の言語（WhisperX）」 セレクトから言語を選べます。モデルサイズは large-v3 に固定で、言語のみ変更できます。

  • 選べるのは WhisperXのアライメントモデルがある41言語のみ（自由入力不可）。辞書に無い言語を 指定すると WhisperX が No default align-model for language: xx で失敗するため、対応外の言語は 最初から選択肢に出ません。
  • 言語を変更すると、初回の転写時にその言語用のDockerイメージ（約10GB）が新たにダウンロード されます（既存の日本語イメージ等とは別イメージ）。
  • 書きおこし言語を変えたら、「書き起こし言語ラベル」も同じ言語に変更してください （ラベルはAIプロンプト用の表示名で、書きおこし言語コードとは別設定です。両方を揃えないと プロンプトと実際の音声言語が食い違います）。
  • デスクトップアプリはローカルDocker実行専用の言語別イメージタグを組み立てるだけで、 WHISPERX_LANGUAGE 環境変数は使いません（言語別タグのENTRYPOINTが自動で付与するため）。

AWS / リモート実行のときの書きおこし言語

実行先を「AWS / リモート実行」にしている場合、デスクトップアプリは音声をアップロードして ジョブを投げるだけです。上記のローカル用セレクトは効かず、設定タブにも表示されません。

  • 書きおこし言語は AWS Batch ジョブ定義の環境変数 WHISPERX_LANGUAGE（Terraformの 変数 whisperx_language、既定 ja）で決まります。これはデプロイ単位の設定で、 ジョブ（動画）ごとに変えることはできません。同じデプロイに投げるジョブは全て同じ言語で 書きおこしされます。
  • AWSワーカーは embedded バックエンド（WHISPERX_EXECUTION_BACKEND=embedded）で動きます。 ワーカーイメージ（infra/docker/aws_batch_worker/Dockerfile）のベースイメージが ghcr.io/jim60105/whisperx:large-v3-ja のため、日本語のアライメントモデルだけが イメージに焼き込まれています（Whisper本体の large-v3 は多言語モデルなので、 言語ごとに差し替える必要があるのはアライメントモデルだけです）。
  • したがって whisperx_language を ja 以外にすると、その言語のアライメントモデルは 実行時にダウンロードされます。Batchのサブネットから外向き通信（HuggingFace / torchaudio）が到達できる必要があり、到達できない構成では失敗します。
  • 恒久的に別言語で運用するなら、infra/docker/aws_batch_worker/Dockerfile のベース イメージを対象言語のタグ（例 ghcr.io/jim60105/whisperx:large-v3-en）に変更して 再ビルド・再プッシュし、Terraformの whisperx_language も合わせて変更するのが確実です。 詳細は infra/terraform/aws_dev/README.md を参照してください。

トラブルシューティング

症状 対処
CUDA out of memory WHISPERX_BATCH_SIZE を下げる（8→4→2）、WHISPERX_COMPUTE_TYPE=int8
could not select device driver "nvidia" NVIDIA Container Toolkit が未インストール（上記の確認コマンド参照）
WhisperX の JSON 出力が見つからない docker run は成功したが出力未生成。イメージタグ・マウントを確認
モデルが毎回再ダウンロードされる キャッシュボリューム（WHISPERX_CACHE_VOLUME）を消さない。docker volume を削除しない
書きおこしが失敗するとエラーになる WhisperX が失敗するとその実行はエラーで終了します（書きおこしが取れないまま字幕が作られることはありません）。原因は上のメッセージ別対処を参照

関連

Clone this wiki locally