vss-deploy-profile

VSS のデプロイ

利用可能なスクリプト

スクリプト	用途	引数
scripts/normalize_resolved_yml.py	デプロイ前に、resolved.yml で除外されたサービスの省略可能な depends_on エントリーを削除します。	resolved.yml のパス
scripts/probe_remote_models.sh	OpenAI 互換のリモート LLM／VLM エンドポイントをプローブし、選択されたモデル ID を検証します。	ベース URL、任意の期待するモデル ID

プロファイルのルーティング

ユーザーのリクエストに合ったプロファイルを選び、サイズ、サービス、環境変数のレシピ、デバッグ方法について、そのプロファイルのリファレンスを読み込んでください。

ユーザーの発言	プロファイル	リファレンス
"deploy vss" ／ "deploy base"	base	references/base.md
"deploy alerts" ／ "alert verification" ／ "real-time alerts" ／ "deploy for incident report"	alerts	references/alerts.md
"deploy lvs" ／ "video summarization"	lvs	references/lvs-profile.md
"deploy search" ／ "video search"	search	references/search.md
"deploy warehouse" ／ "warehouse blueprint" ／ "vss warehouse"	warehouse	references/warehouse.md
"debug warehouse" ／ "warehouse not working" ／ "warehouse FPS low" ／ "warehouse BEV out of sync"	warehouse（デバッグ）	references/warehouse-debug.md

エッジハードウェアのルーティング（DGX Spark、AGX／IGX Thor）：references/edge.md を参照してください。DGX Spark ではポート 30081 の Spark Nano 9B スタンドアロンローカル LLM を使用し、AGX／IGX Thor では Edge 4B スタンドアロン vLLM フォールバックを使用します。

各プロファイルのリファレンスには、そのプロファイル固有のサイズ表があります。 このファイルからデプロイ構成を選ばないでください。プロファイルのリファレンスを開き、そこにある（モード × プラットフォーム）マトリックスで、ホストのハードウェアに必要な最小 GPU 数を確認してください。

手順

デプロイの流れは常に、.env を generated.env にコピーし、オーバーライドを適用し、compose をドライランして resolved.yml に出力し、内容を確認して正規化し、デプロイしてから、準備完了を待つ、という順序です。

# 1. cp dev-profile-<profile>/.env dev-profile-<profile>/generated.env  (clean copy)
# 2. Apply env overrides to generated.env  (source .env stays untouched)
# 3. docker compose --env-file generated.env config > resolved.yml      (dry-run)
# 4. Review resolved.yml
# 5. docker compose --env-file generated.env -f resolved.yml up -d

.env は読み取り専用のリポジトリ内デフォルト設定で、generated.env はデプロイごとの作業用コピーです。手順 1c で詳しく説明します。

前提条件

1. リポジトリのパス — ユーザーに尋ねる前に、video-search-and-summarization/ を自動検出します。以降のすべてのコマンドでは、検出したパスを $REPO として使用してください。
2. 認証情報の確認 — references/credentials.md を参照してください。ローカル／local_shared NIM のプルには NGC_CLI_API_KEY、リモート NIM エンドポイントには NVIDIA_API_KEY、ゲート付き HF モデルを使用するエッジレシピには HF_TOKEN が必要です。
3. システムの前提条件（GPU ドライバー、Docker、NVIDIA Container Toolkit、カーネル sysctl、および ufw が有効な場合は、ブリッジ NIM がホストモードの VST からクリップを取得するための Docker ブリッジからホストへのファイアウォール許可設定） — 詳細な確認方法は references/prerequisites.md にあります。ハードウェア／ドライバーの標準マトリックスは、VSS の前提条件ページを参照してください。

自動検出のスニペット（git ルートの確認後、deploy/docker/compose.yml ＋ dev-profile.sh ＋ skills/vss-deploy-profile を条件に共通パスを確認）は、references/prerequisites.md にあります。解決した $REPO をエクスポートしてください。検出に失敗した場合は、チェックアウトのパスをユーザーに尋ねてください。

デプロイ前チェック

デプロイのたびに実行してください。システム全体のチェックリストと対処手順は references/prerequisites.md にあります。 DGX Spark／IGX Thor／AGX Thor では、さらに references/edge.md のキャッシュクリーナーチェックも実行してください。

まず sudo モードを検出してください。 デプロイ前の対処手順のいくつかと エッジ向けキャッシュクリーナーのインストーラーは sudo を呼び出します。 ホストで sudo パスワードが必要な場合、これらの手順は sudo -n では 何も実行せず、デプロイの準備が不完全な状態になります。

if sudo -n true 2>/dev/null; then
  echo "passwordless sudo — pre-flight will auto-install missing pieces"
else
  echo "sudo requires password — pre-flight will NOT auto-install; hand commands to the user"
fi

sudo にパスワードが必要な場合、スキルは特権インストーラーを実行してはなりません。 references/prerequisites.md にあるコピー＆ペースト可能なコマンドブロックを ユーザーに提示し、「一度実行して確認してください」と引き継いでから、 ユーザーの返信後に再開してください。

最低限のスモークテスト（成功必須）：

nvidia-smi --query-gpu=index,name --format=csv,noheader
docker info 2>/dev/null | grep -qi runtimes \
  && docker run --rm --gpus all ubuntu:22.04 nvidia-smi >/dev/null 2>&1 \
  && echo "nvidia runtime OK"

スモークテストが失敗した場合は先に進まず、対処手順について references/prerequisites.md を確認してください。

モデルの選択

• ユーザーがリモートを希望する場合は $LLM_REMOTE_URL／$VLM_REMOTE_URL
• $NGC_CLI_API_KEY（ローカル NIM）または $NVIDIA_API_KEY（リモート）

エンドポイントの用途を確認してください。 環境変数が残っているだけでリモート配置だと推測してはいけません （LLM_ENDPOINT_URL、VLM_ENDPOINT_URL、LLM_BASE_URL、VLM_BASE_URL は 以前の設定が残っている可能性があります）。リモート LLM／VLM を使用するのは、（1）ユーザーが リモートエンドポイントを希望または提示した場合、（2）ローカルのサイズ要件では選択したモデルを実行できず、ユーザーが同意した場合、または（3）エッジレシピで、VSS が remote として扱う独立したローカルサービスが必要な場合（例：DGX Spark Nano 9B を localhost:30081 で実行する場合）のみです。エンドポイントの環境変数が設定されていても、 ユーザーがリモートを希望していない場合は、Step 1 でその設定を提示して確認してください。 変数が存在するというだけで、確認なくリモートをデプロイしてはいけません。

このホストでプロファイルのサイズ要件を満たす組み合わせがない場合は、停止して阻害要因を報告してください。別の構成を勝手に選んではいけません。

エッジ共有モードはプラットフォーム固有です。 完全なレシピは references/edge.md にあります。

デプロイの流れ

必ず次の順序に従ってください。ドライランを省略してはいけません。

Step 0 — 既存のデプロイをすべて停止し、データボリュームを消去する

すでにデプロイが存在する場合は、再デプロイの前に停止し、古いデータボリュームも消去してください。

完全な手順は references/teardown.md にあります。

Step 0a — 認証情報の確認（環境変数を変更する前に実行）

Step 1c で .env を generated.env にコピーする前に、選択したプロファイルに必要な すべての認証情報と、選択したリモートエンドポイントを検証してください。この段階での 401 エラーは 30 秒で解決できますが、NIM のコールドスタート中に同じ 401 エラーが発生すると 10～20 分かかります。references/credentials.md の 検出とプローブの手順に従い、generated.env に書き込む予定の LLM／VLM エンドポイントごとに scripts/probe_remote_models.sh を実行してください。結果を選択したモードと照合してください。 必須の認証情報／エンドポイントが不足または無効な場合は阻害要因となりますが、任意の認証情報は阻害要因ではありません。

Step 1 — コンテキストを収集する

環境変数のオーバーライドを作成する前に、次の内容を確認してください。

値	確認方法
プロファイル	ユーザーの意図を上記のルーティングテーブルと照合します。デフォルト：base
リポジトリのパス	前提条件で自動検出された $REPO の値を使用します。自動検出に失敗した場合は、続行する前にユーザーにチェックアウトパスを尋ねてください。
ハードウェア	nvidia-smi --query-gpu=name,memory.total --format=csv,noheader
LLM/VLM の配置	ローカル／local_shared／リモートのいずれかを明示的に決定します。利用可能な GPU を、選択したプロファイルの Minimum GPU count テーブルと照合してください。エンドポイント環境変数が設定されているものの、ユーザーがリモートを希望していない場合は、それらを使用するか無視するかを尋ねてください。
API キー	ローカル NIM には NGC_CLI_API_KEY、リモートには NVIDIA_API_KEY
HOST_IP	クラスター内から接続するアドレス：ip route get 1.1.1.1 の src（dev-profile.sh と同様。LAN とクラウドの両方で正しく機能します）。そのインターフェースが VPN／トンネルの場合は LAN の IP アドレスを使用し、ユーザーに確認してください — Network addressing。
EXTERNAL_IP	ブラウザーからアクセスするアドレス。デフォルトは ${HOST_IP} です。ブラウザーからのアクセス経路が異なる場合は上書きします — クラウドのパブリック IP、Brev のセキュアリンク（Step 1d）、またはトンネルです。不明な場合は、どこからブラウズするかをユーザーに尋ねてください。Network addressing。
HAPROXY_PORT	ブラウザー向けのイングレスポート。デフォルトは 7777 です。ポートが空いていることを確認してください。

docker compose up の前に、EXTERNAL_IP、HAPROXY_PORT、VSS_PUBLIC_HOST、VSS_PUBLIC_PORT にブラウザーから到達可能な値が設定されていることを確認してください。そうでない場合、スタックが正常に見えても、UI／API／VST のリンクが 404 になったり、Cloudflare Access を経由してループしたりすることがあります。

Step 1b — データディレクトリを準備する

レイアウト（アセットのパス、所有者、マウントポイント、プロファイル固有のサブディレクトリ）については、references/data-directory.md に記載されています。ホストに初めてデプロイする場合、またはプロファイルを変更する場合は、デプロイ前にこのファイルを読んでください。

Step 1c — generated.env を初期化する

デプロイごとの作業用コピーです。必ずソースの .env から新しいコピーを作成し、ソースを変更しないでください。

PROFILE=base
ENV_SRC=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/.env
ENV_GEN=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/generated.env

cp "$ENV_SRC" "$ENV_GEN"

以降の書き込み（Brev の EXTERNAL_IP、Step 2 の env_overrides dict）はすべて $ENV_GEN に行います。ここから先、$ENV_SRC は読み取り専用です。

Step 1d — Brev のみ：最初に検出し、その後 EXTERNAL_IP にセキュアリンクのドメインを設定する

何よりも先に Brev を検出してください — Brev でプロビジョニングされたインスタンスでは /etc/environment に BREV_ENV_ID が設定されます。それ以外では設定されません。

grep -qE '^BREV_ENV_ID=' /etc/environment && echo "on Brev" || echo "not Brev"

• Brev ではない → このステップの残りをスキップし、references/brev.md を読まないでください。通常どおり ${HOST_IP} を基準にした EXTERNAL_IP を使用します。
• Brev 上 → references/brev.md § Setup flow に記載された Brev のセキュアリンク用オーバーライドを generated.env（.env ではありません）に適用します。これにより EXTERNAL_IP／VSS_PUBLIC_HOST がセキュアリンクのドメインに設定され、さらに VSS_PUBLIC_HTTP_PROTOCOL=https／VSS_PUBLIC_WS_PROTOCOL=wss／VSS_PUBLIC_PORT=443 も設定されます。EXTERNAL_IP だけを設定すると、ブラウザーが混合コンテンツとしてブロックする http://…:7777 の UI／API／WS リンクが残ります。

Step 2 — env_overrides を作成する

ユーザーのリクエストと収集したコンテキストをもとに env_overrides dict を作成します。リモート／ローカルの LLM／VLM を明示的に選択し、認証情報を設定し、エンドポイントを指定し、プラットフォーム固有のフラグを設定してください。既存のシェル環境変数によって配置が暗黙的に選ばれないようにしてください。選択した LLM_MODE／VLM_MODE と、対応するエンドポイント／モデルのフィールドを generated.env に書き込みます。すべてのオーバーライドキー、適用条件、デフォルト値、プロファイル固有の違いを含む完全なマッピングは、references/env-overrides.md にあります。各プロファイルのリファレンスには、そのプロファイルで一般的なシナリオの具体例が記載されています。

Step 3 — オーバーライドを適用してドライランする

作業用 env ファイル： <repo>/deploy/docker/developer-profiles/dev-profile-<profile>/generated.env（Step 1c で作成）。

リマインダー（Step 1c を参照）： すべてのオーバーライド（Step 2 の dict と Brev の EXTERNAL_IP）を generated.env に適用してください。--env-file は常にこのファイルを指定し、デプロイ後の検証ツールは実際にデプロイされた値をこのファイルから読み取ります。

# (Step 1c already ran: cp $ENV_SRC $ENV_GEN)

# Apply the env_overrides dict from Step 2 to generated.env
# (read lines, update matching keys, append new keys, write)
# Example:
#   sed -i "s|^LLM_MODE=.*|LLM_MODE=remote|" "$ENV_GEN"
#   sed -i "s|^LLM_BASE_URL=.*|LLM_BASE_URL=http://localhost:30081|" "$ENV_GEN"

# Resolve compose
cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN config > resolved.yml

解決済みの YAML は <repo>/deploy/docker/resolved.yml に保存されます。

Step 3b — resolved.yml に未展開の ${...} トークンがないことを確認する

resolved.yml に未展開の ${VAR} トークンがある場合、compose がそれらの env 値を認識できていません。診断手順とよくある原因については、references/troubleshooting.md を参照してください。

Step 3c — 選択した NGC アーティファクトへのアクセスを確認する

resolved.yml の作成後、docker compose up の前に実施してください。Step 0a の NGC トークン検査で確認できるのはキーによる認証のみです。キーの org/team が、選択したイメージやモデルのリポジトリにアクセスできることまでは確認できません。

実際に選択したデプロイ構成から、アーティファクトの一覧を作成します。

• resolved.yml：Compose がプルする nvcr.io/... 配下のすべての image:。
• $ENV_GEN：RTVI_VLM_MODEL_PATH=ngc:nim/nvidia/cosmos3-nano-reasoner:bf16-final のような、NGC を参照するモデル／リソースのパス。none、git:...、ローカルパス、リモートエンドポイント URL は除外します。
• プロファイルのステージング手順：プロファイルのリファレンスに記載されている、アラート／検索の認識モデルのステージングなど、NGC モデル／リソースのダウンロード。

続行する前に、正規化済み NGC キーを使って、選択したアーティファクトをそれぞれ検査します。

• コンテナーイメージ：docker login nvcr.io の後に docker manifest inspect <nvcr.io/...> を実行します。アクセス制限のある nvcr.io リポジトリで 401／403 が返る場合、これは権限がないことを示す確定的なシグナルです（マニフェストの読み取りには、レイヤーのプルと同じ org/team の権限付与が必要です）。または、アーティファクトが NGC イメージパスに明確に対応する場合は、一致する ngc registry image info ... を実行します。
• NGC のモデル／リソースパス（実行時に RT-VLM がダウンロードする Cosmos チェックポイントなど）：プロファイルが読み込みまたはダウンロードする正確なリポジトリ／タグに対応する ngc registry model info ... または ngc registry resource info ... を実行します。これらは NGC のスコープ付き認証を使用します。モデルに対して docker manifest inspect を実行してはいけません（モデルは OCI イメージではないため、「no such manifest」が返ります）。また、Authorization: Bearer <key> を使った生の REST 呼び出しも実行してはいけません（これは NGC の認証フローではないため 403 が返ります）。いずれも予期される誤検知であり、権限不足を意味するものではありません。ngc CLI を利用できない場合は、NGC が画像とモデルの両方に対する org/team アクセスをまとめて付与するため、上記のコンテナーイメージ検査を権限の判断材料としてください。
• プロファイルでステージングする TAO／認識モデル：ステージングブロックでファイルをダウンロードする前に、各リポジトリ／タグに対応する ngc registry model info ...／resource info ... を実行します。

いずれかの検査で 401、403、permission、not being a member of the organization that owns the repo、org／repo が見つからないことを示すエラー、または同様のアクセスエラーが返った場合は、処理を中止し、該当アーティファクトへのアクセス権を持つ org/team の NGC キーをユーザーに求めてください。Compose を開始して、NIM のコールドスタート中に失敗を発見してはいけません。

Step 3d — resolved.yml から参照先のないオプションの depends_on を削除する

Step 3 の後、Step 5 の前に必ず実行してください。 省略するとデプロイは中断します。

正規化 — resolved.yml から除外されたサービスへのオプションの依存関係を削除します

# From the repo root
uv run skills/vss-deploy-profile/scripts/normalize_resolved_yml.py "$REPO/deploy/docker/resolved.yml"

ホストに uv がない場合は、curl -LsSf https://astral.sh/uv/install.sh | sh を使って一度だけインストールしてください（root 権限は不要です）。 up -d の前に再検証します。

docker compose -f "$REPO/deploy/docker/resolved.yml" config --quiet && echo "resolved.yml OK"

正規化ツールの実行後も検証に失敗する場合は、エラーを記録して調査してください。これは参照先のない depends_on の問題ではなく、別のバグ（オプションではない依存関係、または別のスキーマ違反）です。

ステップ 4 — レビュー

デプロイされる内容の概要をユーザーに表示します:

• プロファイル名とハードウェア
• LLM/VLM モデルとモード (local/remote/local_shared)
• 起動されるサービス
• GPU デバイスの割り当て
• 主要なエンドポイント (UI ポート、エージェントポート)

「この内容でよろしいですか — 今すぐデプロイしますか?」 と尋ね、ステップ 5 の前に確認を待ちます。

例外 — 自律モード。 ユーザーのリクエストがすでに自律的な実行を求めている場合 (例: 「X を自律的にデプロイして」「確認なしで実行して」「非対話で」)、確認プロンプトをスキップしてそのままステップ 5 に進みます。この経路は、自動評価や CI からの呼び出しが、決して返ってこない人間の応答を待ってハングしないようにするために存在します。それ以外のすべてのケースでは、人間が承認する必要があります。

ステップ 5 — デプロイ

cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN -f resolved.yml up -d

--env-file は必須です。 ステップ 3 で使用したものと同じ generated.env がないと、COMPOSE_PROFILES が未設定になり、up -d がサービスを 1 つも選択しないまま終了コード 0 で終了する可能性があります。

通常の再試行で広範な --force-recreate を避けてください — これはウォーム状態の NIM コンテナを破壊します (それぞれ torch.compile + CUDA グラフキャプチャにさらに 3〜5 分かかります)。 根本原因 (通常は権限か環境変数のタイポ) を修正し、単に up -d を再実行してください。 対象を絞った --force-recreate --no-deps <service...> は、プロファイルのリファレンスが 復旧手順として記載している場合にのみ使用してください。

docker compose up -d はコンテナを作成するだけで、内部サービスのウォームアップ完了を待ちません。レディネスゲートを通過するまで、デプロイ成功を宣言しないでください。

ステップ 5b — スタックが実際に正常になるまで待機する

ゲート 0 — コンテナ数が 0 より大きい必要があります。 起動済み数 (docker compose -f resolved.yml ps -q | wc -l) が非ゼロで、かつ期待数 (config --services | wc -l) 以上になるまで up -d の先へ進むことを拒否します。ゼロまたは不足している数は、ほとんどの場合ステップ 5 での --env-file の欠落を意味します。正確なゲートと完全なレディネス手順は references/readiness.md にあります。

コールドデプロイには 10〜20 分かかることがあり、各プロファイルのリファレンスに必須のエンドポイントが記載されています。up -d の後にデプロイ完了を宣言しないでください。文書化されたすべてのエンドポイントが成功した後にのみ宣言してください。

破棄

デプロイを破棄する場合 — ホスト全体の回収、またはキャッシュを保持した再デプロイ / プロファイル 切り替え — は、references/teardown.md に従ってください。常に mdx プロジェクト単位で -v --remove-orphans を付けて破棄してください。単なる docker compose down ではボリュームとネットワークが残ります。

デプロイのデバッグ

ユーザーが「デプロイをデバッグして」「動作しているか確認して」「なぜエージェントが応答しないのか」などと依頼した場合は、このワークフローを使用します。目的は、コンテナが「Up」であることだけでなく、動画の取り込みからエージェントの回答までの経路全体を確認することです。

各プロファイルのリファレンスには、そのプロファイルの正確なコマンドと障害モードの表を列挙した デバッグ セクションがあります。

クイックチェック (すべてのプロファイル)

# 1. All expected containers Up
docker ps --format 'table {{.Names}}\t{{.Status}}'

# 2. Agent API + UI responding
curl -sf http://localhost:8000/health >/dev/null && echo "agent OK"
curl -sf http://localhost:3000/ >/dev/null && echo "ui OK"

LLM/VLM NIM のプローブ — localhost:3008x をスキップし (ここでは接続拒否が想定されます)、scripts/probe_remote_models.sh を介して選択された *_BASE_URL/v1/models をプローブする *_MODE=remote の処理を含む — は references/troubleshooting.md にあります。

制限事項

• このスキルは compose ベースの VSS プロファイルのみをデプロイします。スタンドアロンのマイクロサービスデプロイは、対応する vss-deploy-* スキルに属します。
• ハードウェアのサイジング、モデルの配置、プロファイル固有のレディネスはプロファイルのリファレンスが担当します。記憶から推測しないでください。
• 特権的なホストの修復は、パスワードなしの sudo が利用できない場合、ユーザーの承認が必要です。

トラブルシューティング

よくあるエラーのクイックリファレンス、症状 → 原因 → 修正の完全な表、 展開されなかった ${...} の診断、および NIM エンドポイントのプローブは references/troubleshooting.md に統合されています — デプロイ、実行時、またはプローブの失敗についてはまずそこから始め、その後、対応する プロファイル別リファレンスのデバッグセクションに進んでください。