vss-deploy

VSS のデプロイ

setup.sh を使って VSS をデプロイ、切り替え、調査、削除します。このスキルは sample-applications/video-search-and-summarization に対してのみ使用してください。回答はすべて リポジトリ内のファイル、特に setup.sh と docker/compose.*.yaml に基づいてください。 フラグ、サービス、ポート、変数を作り出してはいけません。コマンドを自分で実行し、その出力を伝えてください。 デプロイコマンドをユーザーに渡してはいけません（以下の --setenv のみ例外です）。

環境のセットアップ（最初に実行）

このスキルは、実際のソースファイルを通じて Video Search & Summarization アプリを操作するため、 VSS アプリが存在している必要があり、アプリのルートディレクトリからコマンドを実行する必要があります。 何よりも先にこれを実行してください。 VSS のソースがすでにワークスペースにあるかどうかにかかわらず動作します。

同梱のブートストラップを実行してください。まず、現在のディレクトリから上位へたどり、 そのディレクトリを含む git リポジトリを調べて、既存の VSS チェックアウトを探します。 見つかった場合は再クローンせずにそれを再利用します。チェックアウトが見つからない場合に限り、 main から sample-applications/video-search-and-summarization のみを 浅い単一ブランチのスパースチェックアウトで取得します。解決されたアプリのルートを標準出力に表示します。

# SKILL_DIR is THIS skill's own directory (shown to you when the skill loads);
# in-repo it is .github/skills/vss-deploy. Works the same if the skill is installed standalone.
SKILL_DIR=".github/skills/vss-deploy"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

以下のすべてのコマンドは、作業ディレクトリがこの APP_ROOT であることを前提としています。 フォークやブランチから取得する場合、または特定のチェックアウトディレクトリを再利用する場合は、 実行前に VSS_REPO_URL、VSS_REPO_BRANCH、または VSS_CLONE_DIR を上書きしてください。

モードの選択

ユーザーの発言	モードフラグ	UI URL
"summary" / "summarize videos" / "summary only"	--summary	http://<host-ip>:12345/
"search" / "search my videos" / "search only"	--search	http://<host-ip>:12345/
"both" / "dual" / "side by side" / "two UIs"	--summary --search（エイリアス --dual）	…/summary/ および …/search/
"unified" / "one UI" / "search over summaries" / "all"	--summary-and-search（エイリアス --unified、--all）	http://<host-ip>:12345/

ユーザーの意図が曖昧な場合は、どのモードかを尋ねてください。黙ってデフォルトを選んではいけません。

クイックデプロイの流れ

1. アプリのルートディレクトリで作業します：

   cd sample-applications/video-search-and-summarization
   

2. 設定と認証情報を指定します。 setup.sh はシェル環境からすべての値を読み込み、必須変数が不足している場合は最初の時点で処理を中断します。リポジトリには汎用アプリケーションテンプレートとして .env.example が用意されていますが、このスキルでは認証情報がコミット済みファイルに入らないよう、設定と生成されるシークレットを分離しています：

   • シークレットではない設定 - モデル、ポート、チューニング設定 - はコミット済みの vss.config.env にあります。
   • 認証情報は、scripts/gen-secrets.sh によって実行時にGit の追跡対象外 の vss.secrets.env に生成されます（強力なランダム値を一度だけ作成して再利用するため、データボリュームの有効性が保たれます）。

   シークレットを一度生成し、同じシェルで両方のファイルを読み込みます：

   ./.github/skills/vss-deploy/scripts/gen-secrets.sh     # makes vss.secrets.env if absent
   source .github/skills/vss-deploy/vss.config.env
   source .github/skills/vss-deploy/vss.secrets.env
   

   すべてのモードで共通の項目：MINIO_ROOT_USER、MINIO_ROOT_PASSWORD、 POSTGRES_USER、POSTGRES_PASSWORD、RABBITMQ_USER、RABBITMQ_PASSWORD。 モード固有のモデル変数（summary 用の VLM_MODEL_NAME、ENABLED_WHISPER_MODELS、 OD_MODEL_NAME、search/dual 用の MULTIMODAL_EMBEDDING_MODEL、 unified 用の TEXT_EMBEDDING_MODEL）には vss.config.env でデフォルト値が設定されています。 全項目の一覧は references/env-vars.md を参照してください。 ランダム値の代わりに独自の認証情報（vault/CI）を指定するには、gen-secrets.sh の実行前にエクスポートします。すでに設定されている認証情報は再利用されます。

3. 不明な点がある場合は、まずドライランを実行します - config を追加して、コンテナを起動せずに解決済みの .env/compose を出力し、実際にデプロイする前に内容を確認します：

   source setup.sh --summary config     # or --search / --summary --search / --summary-and-search
   

4. デプロイします - 実行するのはユーザー自身です。 setup.sh は Compose コマンドの作成時に return と環境変数のエクスポートを使うため、source で読み込む必要があります。ただし、ユーザーの対話型シェルで実行する必要はありません。デプロイには docker compose up -d（デタッチモード）を使うため、サブシェルの終了後もコンテナは実行され続けます。古い、または誤ったモードのデプロイと競合しないよう、まず以前のスタックを停止してからデプロイします。コマンド全体を 1 回の bash -c 呼び出しで実行します：

   bash -c '
     source setup.sh --stop                                  # clear any running stack first
     ./.github/skills/vss-deploy/scripts/gen-secrets.sh       # secrets if absent
     source .github/skills/vss-deploy/vss.config.env
     source .github/skills/vss-deploy/vss.secrets.env
     source setup.sh --summary                                # the chosen mode
   '
   

   バックグラウンドで実行する（run_in_background: true）か、長めのタイムアウトを指定してください。Compose の起動前に、選択された OD アーティファクト、または OVMS の VLM／分割 LLM アーティファクトが存在しない場合、setup.sh はループバックポート 8640 で一時的な vss-model-download コンテナを起動します。REST ジョブを送信し、ジョブごとに最大 MODEL_DOWNLOAD_JOB_TIMEOUT（デフォルトは 5400 秒）まで待機し、失敗したサービスのログを ov_models/model-download-*.log に書き込み、一時コンテナを削除してから、docker compose up -d を実行します。

   唯一の例外： --setenv は、後で手動で使えるようにユーザーの 対話型 シェルに環境変数を残すためだけのものです。サブシェルではそれができないため、この動詞の場合に限り、ユーザー自身が実行する ! 付きコマンドを提示してください。

5. ヘルスチェックが完了するまで待ち、その後 URL を表示します（scripts/wait-health.sh を参照）：

   ./.github/skills/vss-deploy/scripts/wait-health.sh "${HOST_IP:-localhost}" "${APP_HOST_PORT:-12345}"
   

モードのエイリアスと設定のみの確認

setup.sh は --summary --search と --search --summary を --dual に、 --summary-and-search、--search-and-summary、--all を --unified に、 config を --dual config に、config --summary を --summary config に、 また --down を --stop に正規化します。コンテナを起動せずに解決済みの Compose を確認するには、config モードを使います：

source setup.sh --summary config
source setup.sh --search config
source setup.sh --summary --search config
source setup.sh --summary-and-search config

OVMS、vLLM、CPU、GPU の選択

デフォルトの要約バックエンドは、docker/compose.summary.yaml の OVMS（ovms-service、プロファイル ovms）です。

source setup.sh --summary                                                # OVMS CPU default
VLM_TARGET_DEVICE=GPU source setup.sh --summary                          # OVMS GPU for VLM
LLM_TARGET_DEVICE=GPU OVMS_LLM_MODEL_NAME=<llm> source setup.sh --summary # OVMS GPU for LLM
ENABLE_VLLM=true source setup.sh --summary                               # vLLM CPU backend
ENABLE_VLLM_GPU=true source setup.sh --summary                           # experimental vLLM XPU/GPU backend
ENABLE_EMBEDDING_GPU=true source setup.sh --search                       # GPU for search embeddings

vLLM の場合、setup.sh は docker/compose.vllm.yaml を追加し、ホストのポート 8200 で vllm-cpu-service（プロファイル vllm）を起動します。また、キャプション生成と最終要約の両方に VLM_MODEL_NAME を使用します。実験用の ENABLE_VLLM_GPU=true を指定すると、代わりに docker/compose.vllm.xpu.yaml を追加し、プロファイル vllm-xpu を選択して、OVMS を無効にします。OVMS GPU の場合、setup.sh は docker/compose.gpu_ovms.yaml を追加し、ovms-service を openvino/model_server:2026.1-gpu に切り替えます。

スキルの新しい bash -c デプロイフローでは、派生した OVMS ストレージ名が実行間で引き継がれることはありません。同じ対話型シェルで OVMS から vLLM に手動で切り替える場合は、最初に unset VLM_STORAGE_MODEL_NAME LLM_STORAGE_MODEL_NAME を実行してください。そうしないと、Compose が vLLM では提供されない OVMS のストレージエイリアスを再利用する可能性があります。

ライフサイクル：停止またはリセット

bash -c 'source setup.sh …' を使って、これらのコマンドをご自身で実行してください。--stop／--down／ --clean-data はモードに依存せず、環境変数も不要です。

source setup.sh --stop       # stop/remove containers across all VSS overlays/profiles
source setup.sh --down       # alias for --stop
source setup.sh --clean-data # also removes the VSS application data volumes
source setup.sh --help       # full help

--clean-data は docker_minio_data、docker_pg_data、docker_vdms-db、 docker_audio_analyzer_data、docker_data-prep、docker_collector_signals を削除します。 ホスト側の ov_models/ モデルキャッシュは削除しません。

デフォルトのポートと URL

HOST_IP は setup.sh によって自動検出されます。APP_HOST_PORT のデフォルト値は 12345 です。

サーフェス	URL
UI（要約／検索／統合）	http://<HOST_IP>:<APP_HOST_PORT>/
UI（デュアルモード）	…/summary/ および …/search/
Pipeline Manager API とドキュメント	…/manager/docs、ヘルスチェック …/manager/health
Data Prep のドキュメント（検索モード）	http://<HOST_IP>:7890/docs
埋め込みサーバーのドキュメント（検索モード）	http://<HOST_IP>:9777/docs

トラブルシューティング（「vss が起動しない」場合）

1. ERROR: <VAR> is not set → シェル環境変数がありません。vss.config.env と vss.secrets.env を再度読み込んでください（手順 2）。
2. Invalid VECTORDB_BACKEND → VECTORDB_BACKEND を vdms または milvus に設定してください。
3. ヘルスチェックが正常にならない → docker compose ps でクラッシュしたコンテナーを確認し、その後 docker compose logs <service> を実行してください。負荷の高いコンポーネントはモデルサーバー（ovms、 vlm-ov／vllm、埋め込みサーバー）です。
4. 間違ったスタック、または不完全なスタックがすでに起動している → source setup.sh --stop を実行してから再デプロイしてください。
5. Compose の起動前にセットアップが失敗する → 報告された ov_models/model-download-*.log を確認してください。ループバックポート 8640 が使用中の場合は、 MODEL_DOWNLOAD_HOST_PORT を空いているポートに設定して再実行してください。

基本的な内容を超える問題（モデルサーバーのクラッシュ、OVMS のトークン／キャッシュ／GPU エラー、ホストのモデルキャッシュやモデルダウンロードに関する権限エラー、検索結果が返らない問題、NPU／OpenGL の問題）については、.github/skills/vss-troubleshoot/SKILL.md の vss-troubleshoot スキルと、正式なガイド docs/user-guide/troubleshooting.md を参照してください。

参考資料

• モードとオーバーレイ／プロファイル／サービス／URL の正確な対応： references/modes-and-overlays.md。
• 必須および任意の環境変数： references/env-vars.md。