vss-manage-alerts

目的

VSS アラートパイプライン（モード検出、Alert-Bridge サブスクリプション、Slack 通知、クエリ、カメラのオンボーディング、検証プロンプトのカスタマイズ）を運用します。

前提条件

• $HOST_IP からアクセス可能なアクティブな VSS デプロイメント（vss-deploy-profile と references/ を参照）。
• イメージをプルする場合は、$NGC_CLI_API_KEY と $NVIDIA_API_KEY に NGC 認証情報が設定されていること。
• 呼び出し元で curl、jq、Docker を利用できること。

手順

以下のルーティング表とステップごとのワークフローに従ってください。workflow、quick start、または flow で終わる各セクションは、上から順に実行することを意図しています。詳細なリファレンス資料は references/ にあり、ヘルパースクリプトは scripts/ にあります。スキルでスクリプト名が指定されている場合は、run_script を使って実行してください。

例

実行可能なエンドツーエンドのシナリオは evals/ 以下にあります（各 *.json マニフェスト）。各ワークフローにはインラインの curl ブロックがあります。nv-base validate <this-skill-dir> --agent-eval で再生してください。

制限事項

一致する VSS プロファイル／マイクロサービスがデプロイされ、アクセス可能である必要があります。NGC ホストのモデル／NIM には、レート制限、GPU メモリ要件、ライセンス条項が適用されます。同時実行数とストレージの制限は、ホストのハードウェアとプロファイルの compose ファイルによって異なります。

トラブルシューティング

• Connection refused → マイクロサービスが実行されていません。/docs または /health を確認し、vss-deploy-profile で再デプロイしてください。
• NGC pulls で HTTP 401/403 → NGC_CLI_API_KEY が未設定または期限切れです。docker login nvcr.io を実行し、キーを再度エクスポートしてください。
• OOM / モデル読み込みエラー → GPU メモリが不足しています。より小さいバリアントを使用するか、docker compose down を実行して GPU を解放してください。

VSS アラート管理

alerts プロファイルは 2 つのモードのいずれかで動作します（/vss-deploy-profile -p alerts -m {verification,real-time} で選択）。詳しくは、以下の2 つのモードの表を参照してください。このスキルは、デプロイ済みモードとユーザーの意図（監視、サブスクリプションの CRUD、Slack Webhook）に基づいてルーティングします。

使用する場面

• センサーでリアルタイムアラートを開始／停止する（「warehouse_sample で箱が落下した場合のリアルタイムアラートを開始」）
• Alert Bridge でリアルタイムのサブスクリプションルールを作成／一覧表示／停止する
• Slack のインシデント通知を設定または管理する
• 検出されたインシデント／アラートを一覧表示またはクエリする。判定（確認済み／却下／未検証）を確認する
• アラートパイプラインに新しいカメラを追加する。VLM 検証プロンプトをカスタマイズする（CV モード）

---

デプロイの前提条件

verification（CV）または real-time（VLM）モードのいずれかで、$HOST_IP に VSS alerts プロファイルが必要です。

# Either vss-rtvi-cv (CV mode) OR vss-rtvi-vlm (VLM mode) must be present.
curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
  && docker ps --format '{{.Names}}' \
     | grep -qE '^(vss-rtvi-cv|vss-rtvi-vlm)$'

プローブに失敗した場合は、どちらのモードをデプロイするかを尋ね、/vss-deploy-profile -p alerts -m <mode> に引き継いでください（拒否された場合 → 停止。自律デプロイが事前承認されている場合 → 既定で verification を指定して直接実行）。成功した場合は、ステップ 1 に従ってモードを検出してください。

---

2 つのモード（デプロイ時に選択）

モード	デプロイフラグ	環境変数（.env）	実行されるもの	利用できるもの
CV（verification）	-m verification	MODE=2d_cv	RT-CV（Grounding DINO）+ Behavior Analytics + alert-bridge VLM verifier + rtvi-vlm	静的 CV パイプライン（ワークフロー A）と動的 VLM リアルタイムアラート（ワークフロー B/D）の両方
VLM（real-time）	-m real-time	MODE=2d_vlm	alert-bridge + rtvi-vlm	動的 VLM リアルタイムアラート（ワークフロー B/D）と alert-bridge バックエンドのみ。静的 CV パイプラインはありません。

モードの切り替えには、vss-deploy-profile のティアダウン＋デプロイのフローを使用し、もう一方の -m フラグを指定します（VLM → CV では CV パイプラインが追加され、CV → VLM では CV パイプラインがティアダウンされます）。rtvi-vlm はどちらのモードでも実行されます。

---

ステップ 1 — 現在デプロイされているモードを検出する

アラートのワークフローを実行する前に、稼働中のモードを確認します。モードの判断には CV 専用のコンテナを使用してください。vss-rtvi-vlm は両方のモードで実行されるため、モードを判断する信頼できるシグナルではありません。

# CV verification mode (vss-behavior-analytics + vss-rtvi-cv are CV-only)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics && echo "mode=CV"

# VLM real-time mode (no CV pipeline; vss-rtvi-vlm still runs)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics || \
  docker ps --format '{{.Names}}' | grep -qx vss-rtvi-vlm && echo "mode=VLM"

vss-behavior-analytics が存在する場合 → CV モード（vss-rtvi-vlm も実行されています）。 vss-rtvi-vlm のみが存在する場合（CV パイプラインがない場合）→ VLM モード。 どちらにも該当しない場合、アラートプロファイルはデプロイされていません。ユーザーに vss-deploy-profile スキルを案内してください。

代替シグナル（docker ps にアクセスできない場合はこちらを推奨）：プロファイルの generated.env を確認します。

grep -E '^MODE=' deploy/docker/developer-profiles/dev-profile-alerts/generated.env
# MODE=2d_cv   → CV mode (full superset)
# MODE=2d_vlm  → VLM real-time mode (vss-rtvi-vlm only; no vss-rtvi-cv)

---

ステップ 2 — デプロイ済みのモードに応じて振り分ける

デプロイ済みモード	ユーザーの依頼内容	対応
VLM リアルタイム	Slack webhook の設定／状態確認／テスト／停止	ワークフロー E — references/alert-notify.md
VLM リアルタイム	ルールの CRUD、検知条件付きのセンサーでリアルタイムアラートを設定する、または名前付きアラートを停止／削除する（alert_type／条件またはルール ID を指定）	ワークフロー D — references/alert-subscriptions.md（2 段階の停止／確認を含む）
CV 検証	サブスクリプション／ルールの CRUD、または Slack／通知の設定	拒否してください。以下の正式な拒否文を参照してください
CV または VLM	検知条件を指定せずにモニタリングを一般的に開始／停止する	ワークフロー B（VLM） — VSS Agent を呼び出します。rtvi-vlm は両方のモードで実行されます
CV または VLM	インシデントの照会／何が起きたか（最近のアラート、期間指定、「今日、アラートはあった？」といった簡単な質問）	ワークフロー C（照会） — どちらのモードでも動作します。必ず照会を実行し、記憶をもとに回答しないでください
CV	静的 CV アラートのオンボーディング／判定プロンプトのカスタマイズ	ワークフロー A（CV） — vss-manage-video-io-storage を使って RTSP をオンボードします。パイプラインが自動的に取り込みます
VLM	静的 CV パイプラインを必要とする CV／行動分析／PPE ルールのアラート	再デプロイが必要です — 先に確認してから、vss-deploy-profile -m verification を実行します

再デプロイを実行する前に、必ず確認してください。 モードを切り替えると、現在実行中のモニタリングがすべて停止し、サービスが再起動します。

意図の優先順位（一致した最初の項目を適用）

1. ワークフロー E（Slack） — Slack 固有のキーワード（slack、webhook + slack、bot token、slack channel）。notify だけでは不十分です。
2. ワークフロー D（サブスクリプション） — センサー と検出条件、ルールの CRUD キーワード（rule、subscription、ルール ID）、または種類／条件を指定したアラートの停止／削除（「PPE アラートを停止して」「衝突ルールを削除して」）。名前付きの alert_type／条件は既存の ルール です → D の 2 段階停止プロトコル（GET /api/v1/realtime → はい／いいえの確認 → 削除）を使い、ワークフロー B は使いません。
3. ワークフロー B（VLM モニタリング） — 検出条件 もアラートの種類を示す修飾語 もない、センサーでの一般的な開始／停止（「センサー X のリアルタイムアラートを開始／停止して」）。種類を指定した停止（「PPE アラートを停止して」）はルールの停止です → ワークフロー D。
4. ワークフロー C（クエリ） — インシデントの検索／何が起きたか（「インシデントを表示／一覧表示して」「最近のアラート」「期間を指定したクエリ」、および「アラートはある？」「今日これまでにアラートはあった？」「何がトリガーされた？」といったくだけた表現）。rule／subscription／active rules を伴わない alerts 単独の表現は インシデント を意味します → ワークフロー C であり、ワークフロー D ではありません。
5. ワークフロー A（CV） — 上記のいずれにも該当しない場合の CV デプロイメント処理です。

alerts と alert rules（C と D）の区別 — 必ずどちらか一方を選び、両方を選ばないでください： 何が起きたか／何がトリガーされたか（インシデント）→ ワークフロー C （POST /generate）。どのルール／サブスクリプションが設定済み、または有効か → ワークフロー D（/incidents を含まない 単独の GET /api/v1/realtime）。alerts 単独の表現 = インシデント（C）。alert rules／subscriptions／active rules = 一覧（D）。記憶に頼って回答せず、正しい呼び出しを 1 つ実行してください — エンドポイントの詳細は以下のワークフロー C に記載されています。

判別（B と D）： センサー名が指定され、開始／監視を示す表現があるものの、検出条件が不明な場合は、次のように質問してください：

「（a）削除するまで実行され続ける永続的なアラートルールを Alert Bridge に作成しますか。それとも（b）VSS Agent 経由で一度限りのモニタリングセッションを開始しますか？」

停止時の振り分け（B と D）： 「<type> アラートを停止して」（PPE、衝突、火災などの alert_type／条件を指定）= サブスクリプションルールを停止 → ワークフロー D（GET /api/v1/realtime で検索し、references/alert-subscriptions.md にある 2 段階の停止／確認プロトコルを実行してください。POST /generate は呼び出さないでください）。種類を指定せずに「リアルタイムアラートを停止して／<sensor> のモニタリングを停止して」とだけ言う場合 = ワークフロー B です。

プロンプトに複数のワークフローが混在している場合（「モニタリングを開始して、Slack に送信して」など）は、実行順序を分けるために確認の質問を 1 つしてください。

D および E の意図に対する CV モードでの拒否メッセージ

デプロイ済みのモードが CV 検証で、ユーザーがアラートサブスクリプションまたは Slack／通知を求めた場合は、次のメッセージをそのまま返して拒否してください：

"Alert subscriptions and Slack notifications are only supported in VLM real-time mode. Your current deployment is <CV verification | not deployed>. To use these features, redeploy with /vss-deploy-profile -p alerts -m real-time (note: switching tears down current CV monitoring)."

自動的に再デプロイしてはいけません。モードを切り替えるかどうかはユーザーが決めます。

---

どちらのモードでも必要な前提条件：センサーが VIOS に登録されていること

どちらのモードでも、まずカメラを VIOS に登録する必要があります（vss-manage-video-io-storage スキル経由）。

• RTSP URL／IP カメラ → POST /sensor/add で追加します（そのスキルのセクション 6）。sensorId／名前を記録します。
• 名前付きの既存センサー → 先に進む前に、GET /sensor/list に表示されることを確認します。

CV では、RTSP の追加がオンボーディングの 全ステップ です（パイプラインが自動的に取得します）。VLM では、ワークフロー B の前提条件です。

---

エージェントの /generate エンドポイント

すべての VLM フローアクションとクエリアクションは、VSS エージェントの自然言語エンドポイントを経由します。

AGENT="http://<AGENT_ENDPOINT>"   # default http://localhost:8000 on the alerts profile

curl -s -X POST "$AGENT/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "<natural-language request>"}' | jq .

エンドポイントの解決： アクティブな VSS デプロイメントコンテキストからエージェントのエンドポイントを使用してください。利用できない場合は、ユーザーに確認してください。ファイルシステム経由で検出しないでください。

可用性チェック： curl -sf --connect-timeout 5 "$AGENT/docs"。

rtvi-vlm マイクロサービスのエンドポイントを直接呼び出さないでください。必ずエージェントを経由してください。エージェントは内部で rtvi_vlm_alert、rtvi_prompt_gen、video_analytics_mcp.get_incidents に振り分けます。

---

ワークフロー A — CV モード（-m verification / MODE=2d_cv）

CV アラートはリクエスト駆動ではなく、デプロイメント駆動です。アラートを「作成」するためのエージェント呼び出しはありません。

1. vss-manage-video-io-storage の GET /sensor/list を使って、センサーが VIOS に登録されているか確認します（冪等です。むやみに POST /sensor/add を実行しないでください）。
2. 登録されていない場合は、そのスキルの POST /sensor/add でオンボーディングします。登録され、オンラインになると、CV パイプラインがストリームを自動的に取り込みます。
3. オンラインであることを確認します：curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/status" | jq .
4. アラートは Elasticsearch に記録されます（Behavior Analytics → alert_type_config.json に従った alert-bridge 検証）。ワークフロー C でクエリします。

VLM のみのデプロイメントで静的 CV パイプラインのアラートが発生する場合は、モードの不一致です。上記のルーティング表を参照してください。

---

ワークフロー B — VLM リアルタイム監視（CV モードまたは VLM モード）

検知条件を指定せず、名前を指定したセンサーに対する一般的な開始／停止インテントは、VSS エージェントを経由します（条件が指定されている場合はワークフロー D に振り分けます）。rtvi-vlm はどちらのモードでも動作します。

# start: input_message = "Start real-time alert for sensor <id>"
# stop:  input_message = "Stop real-time alert for sensor <id>"
curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "<start|stop> real-time alert for sensor <id>"}' | jq .

内部処理：rtvi_prompt_gen → rtvi_vlm_alert action="start"。 すべてのチャンクにキャプションが付けられ、VLM の応答に yes／true（大文字と小文字を区別しない）が含まれるチャンクは、インシデントを mdx-vlm-incidents に送信します。プロンプトでは、回答を Yes／No に限定する必要があります。 VLM のみのデプロイメントで静的 CV パイプラインのリクエストがあった場合は、モードの不一致です。ルーティング表を参照してください。

---

ワークフロー D — アラートのサブスクリプション（VLM リアルタイムモードのみ）

Alert Bridge 上で、永続的なリアルタイムアラートルールを作成／一覧表示／削除します。プロンプトにルール関連のキーワード（rule、subscription、ルール ID）が含まれる場合、または特定のセンサーと特定の検知条件が組み合わされている場合は、ここに振り分けます（例：「warehouse-dock-1 で PPE 違反のリアルタイムアラートを設定して」「センサー entrance-1 で追従侵入を監視して」「ルール 496aebd1-… を停止して」）。

対象外： 条件を指定しない一般的な開始／停止（→ ワークフロー B）、または Slack 操作（→ ワークフロー E）。

サブスクリプションの CRUD については、references/alert-subscriptions.md を読み込み、正規の手順書として従ってください。VLM リアルタイムモードのみが対象です。CV モードでは、規定の拒否文で対応してください。

---

ワークフロー E — Slack 通知（VLM リアルタイムモードのみ）

ユーザーがSlack または webhook relay に明示的に言及した場合に使用します（webhook サーバーの開始／停止、ステータス／ヘルスチェック、テストメッセージの送信、Slack のチャンネル／トークンの設定）。notify という語だけでは不十分です。

alert-notify（ポート 9090）≠ vss-alert-bridge（/api/v1/realtime）。 Slack 操作で vss-alert-bridge に触れないでください。

対象となる依頼：「Slack 通知を設定して」「alert-notify が動作中か確認して」「Slack にテストアラートを送信して」。対象外となる依頼：「誰かがゾーンに入ったら通知して」（→ D／B）、「アラートを出して、スマートフォンにも通知して」（曖昧なため、確認してください）。

references/alert-notify.md を読み込み、その手順に従ってください。コードは scripts/alert-notify/ にあります。VLM リアルタイムモードのみが対象です。

ワークフロー C — アラートの照会／一覧表示（どちらのモードでも動作）

CV と VLM のどちらが生成したアラートも Elasticsearch に保存され、エージェントの video_analytics_mcp.get_incidents ツールから照会できます。自然言語のリクエストを $AGENT/generate に POST します。「センサー X の最近のアラートを表示して」「直近 1 時間の確認済みアラートを一覧表示して」「<ISO> から <ISO> までの Camera_02 の衝突インシデントを表示して」などです。

くだけた言い回しも、こちらに振り分けます。「今日は今のところアラートはある？」「今日アラートはあった？」「何がトリガーされた？」「最近何か検出された？」のような質問はインシデントの照会です。POST /generate を実行し（例：{"input_message": "List alerts from today"}）、結果を要約してください。 記憶を頼りに回答してはならず、照会を実行せずに「アラートはありません」と答えてはいけません。 単に「アラートは？」と尋ねられた場合も、必ずインシデントの照会（ワークフロー C）として扱い、サブスクリプションルールの一覧表示（ワークフロー D）として扱ってはいけません。

インシデントの照会に対して、サブスクリプションルールを一覧表示してはいけません。 単独の GET /api/v1/realtime（/incidents なし）はルールを一覧表示するものであり（ワークフロー D）、 「何が起きたか」という質問には不適切です。インシデントの照会では、これを呼び出したり、動作確認したり、 ワークフロー D のプレイブックを読み込んだりしてはいけません。

結果が空でも、有効な回答です。 該当するインシデントがない場合（例：導入したばかりで、まだアクティビティがないシステム）は、リクエストされた期間について見つからなかったこと／件数が 0 件であることを報告し、そこで終了してください。ルール一覧の表示や、ほかのエンドポイントの検索に切り替えてはいけません。

より詳細なフィルタリング（センサー単位、時系列、件数）や自然言語以外でのフィルタリングには、vss-query-analytics スキル（ポート 9901 の VA-MCP）を使用してください。

判定結果の解釈と CV 検証プロンプト（CV モードのみ）

CV アラートには VLM 検証結果（confirmed／rejected／unverified）が含まれます。VLM リアルタイムインシデントには個別の判定結果はありません（トリガーそのものが VLM による Yes／No の回答です）。CV 経路の検証プロンプトは alert_type_config.json でカスタマイズできます（反映するには alert-bridge を再起動してください）。判定結果の表、フィールドの意味、プロンプトのカスタマイズ規則については、references/cv-verifier-prompts.md を参照してください。

---

スキル間リンク

タスク	スキル
アラートモードのデプロイ、再デプロイ、切り替え	vss-deploy-profile — -p alerts -m {verification,real-time}
RTSP/IP カメラの追加、センサー一覧の表示、スナップショット、クリップ	vss-manage-video-io-storage（センサー追加についてはセクション 6）
Elasticsearch からの期間指定インシデント／占有状況／PPE メトリクス	vss-query-analytics（VA-MCP :9901）
アラートからの詳細なインシデントレポート	vss-generate-video-report
サブスクリプション／Slack サブワークフロー	references/alert-subscriptions.md、references/alert-notify.md（コードは scripts/alert-notify/）

---

注意点

• alert-notify（ポート 9090）≠ vss-alert-bridge。 Slack 運用はワークフロー E（alert-notify）を使用してください。Slack を vss-alert-bridge の /api/v1/realtime に振り分けてはいけません。
• ワークフローの適用範囲はモードによって異なります： A は CV 専用、B と C はどちらのモードでも動作し、D と E は VLM リアルタイム専用です（CV では所定の文言で対応できないことを伝えてください）。
• モードの判定に vss-rtvi-vlm を使用してはいけません — どちらのモードでも実行されます。vss-behavior-analytics（CV 専用）または MODE 環境変数を使用してください。
• モードを切り替えると、現在のデプロイメントは停止されます — 実行中の VLM ストリームと、永続化されていない CV アラートの状態は失われます。
• 必ず $AGENT/generate を経由してください — rtvi-vlm を直接呼び出してはいけません。VLM トリガーは "yes"／"true" トークンとの一致（大文字・小文字を区別しない）です。rtvi_prompt_gen が Yes／No 形式を強制するため、それを崩すようなプロンプトを独自に作成しないでください。
• どちらのモードでも、センサーはあらかじめ VIOS に登録されている必要があります（RTSP のみの入力には vss-manage-video-io-storage を使用してください）。

bump:1