vss-setup-behavior-analytics

目的

ユーザーが選択したエントリーポイント、設定、キャリブレーションを使用して、行動分析サービスを単独でデプロイします。

手順

以下のルーティングテーブルとステップごとのワークフローに従ってください。workflow、quick start、または flow で終わる各セクションは、上から順に実行することを想定しています。詳細なリファレンス資料は references/ にあります。

例

エンドツーエンドの実行例は evals/ にあります（各 *.json マニフェストには、実行可能なシナリオが含まれています）。Tier-3 評価を実行して、これらを再生します。

nv-base validate skills/vss-setup-behavior-analytics --agent-eval

最小限の単独起動は次のようになります。

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
docker compose -f services/analytics/behavior-analytics/compose.yml up -d vss-behavior-analytics-base

完全なワークフロー（エントリーポイントの選択、設定ソース、動的更新）については、references/deploy-behavior-analytics-service.md に従ってください。

制限事項

• 対応する VSS プロファイル／マイクロサービスがデプロイされており、呼び出し元から到達可能である必要があります。
• NGC でホストされるモデルと NIM は、レート制限、GPU メモリ要件、ライセンス制限の対象となる場合があります。
• 同時実行数、GPU メモリ、ストレージの制限は、ホストのハードウェアとプロファイルの compose ファイルによって異なります。

トラブルシューティング

• エラー：REST 呼び出しで接続拒否が返されます。原因：対象のマイクロサービスが実行されていません。解決策：/docs または /health を確認するか、vss-deploy-profile または対応する vss-deploy-* スキルを使って再デプロイしてください。
• エラー：NGC からの取得で HTTP 401/403 が返されます。原因：NGC_CLI_API_KEY が設定されていないか、有効期限が切れています。解決策：docker login nvcr.io を実行し、キーを再度エクスポートしてから再試行してください。
• エラー：コンテナで OOM が発生するか、モデルの読み込みに失敗します。原因：選択したプロファイルに対して GPU メモリが不足しています。解決策：より小さいバリアントに切り替えるか、docker compose down を使って GPU を解放してください。

VSS セットアップ：行動分析 — 単独実行

フルの倉庫ブループリントスタックの一部としてではなく、vss-behavior-analytics コンテナだけをデプロイします（アップストリームの behavior-analytics リポジトリにある空間 AI 分析パイプライン）。

エントリーポイントのテーブル、設定ソースのオプション、キャリブレーションの種類、動的更新のワイヤーコントラクト、トラブルシューティングを含む、運用手順の全体については、references/deploy-behavior-analytics-service.md を参照してください。この SKILL.md では、ルーティングと前提条件のみを扱います。

使用するタイミング

• 「行動分析をデプロイして」／「behavior-analytics を単独で実行して」
• 「フルスタックではなく、分析だけを実行したい」
• 「エントリーポイントを fusion_search / dev_example / analytics 3D / mv3dt に変更して」
• 「独自の behavior-analytics 設定／キャリブレーション JSON を使って」
• 「倉庫プロファイルの残りを起動せずに、behavior-analytics を warehouse-3d（または mv3dt）の設定に接続して」
• 「実行中の behavior-analytics に動的設定／動的キャリブレーションを適用して」

前提条件

1. リポジトリのチェックアウト：$VSS_APPS_DIR が <repo>/deploy/docker/ を指している必要があります。サービスの compose によるボリュームバインドで必要です。
2. NGC 認証情報：Docker でイメージを取得できるように、$NGC_CLI_API_KEY を設定してください。references/ngc-api-key-registry-login.md を参照してください。
3. Docker ランタイム：Docker Compose プラグイン v2.39.1+ を備えた Docker Engine 28.3.3。docker --version と docker compose version で確認してください。
4. 任意のブローカー（Kafka / Redis Streams / MQTT）。ブローカーがなくてもコンテナは問題なく起動しますが、Kafka クライアントは上限付きで再試行した後、アプリが終了し、restart: always によってコンテナが再起動を繰り返します。ブローカーに到達できるようになるまで、docker ps のステータスには Restarting (N) と表示されます。ブローカーがある場合は、mdx-notification を介した動的設定／動的キャリブレーションが利用可能になります。
5. 任意の設定／キャリブレーションファイル：ユーザーが独自のファイルを使用する場合は、ディスク上に用意してください。

必須の前提条件を満たしていない場合は、先に不足している点を伝えてください。

ワークフロー

references/deploy-behavior-analytics-service.md をユーザーに案内し、次の手順に沿って進めます。

1. エントリーポイントを選びます（analytics 2D ／ 3D ／ mv3dt、dev_example、fusion_search）。
2. 設定を選びます。プロファイル同梱またはカスタムです。
3. キャリブレーションを選びます。これは任意です。プロファイル同梱またはカスタムを選びます。どちらも選ばない場合、アプリは動的キャリブレーションの通知を待ちます。
4. ブローカーに接続できるか確認します。接続できる場合は、動的更新のフローを案内します。

compose ファイルの編集、YAML の差分、デプロイと検証のコマンド、トラブルシューティングの表は、すべてこのリファレンスに記載されています。ここでは重複して記載しないでください。

動的更新（ランタイム、再起動不要）

コンテナが起動し、ブローカーに接続できる場合は、2 つのランタイム更新フローを利用できます。どちらも再デプロイは不要です。

動的設定

Kafka キー behavior-analytics-config と次のヘッダーを指定し、mdx-notification トピックに upsert（キーごとのパッチ）または upsert-all（全体のスナップショット）メッセージをパブリッシュします。

• event.type: upsert | upsert-all | request-config | ack
• reference-id: video-analytics-api-<uuid>（web-api 起点）、behavior-analytics-<uuid>（ブートストラップの返信）、または直接パブリッシャーによる upsert の場合はソースタイプのリテラル（kafka / redis / mqtt）。

本文：{"status": ..., "config": <patch>, "error": ...}。

リスナーは、エンベロープ層（不明なキー、config の欠落、不正な status ／ error を拒否）とペイロードごとの層（禁止されたセクション、不正な項目の形式を拒否）の両方で各メッセージを検証します。upsert が成功すると、ディスクに保存され、すべてのワーカーに適用され、トピック経由で ACK が返されます。

ワイヤー形式の完全な仕様と ACK のセマンティクスについては、references/dynamic-config.md を参照してください。

動的キャリブレーション

同じトピックに、Kafka キー calibration と次のヘッダーを指定してパブリッシュします。

• event.type: upsert-all（全体のスナップショット） | upsert（センサーごとのマージ） | delete（センサーごとの削除）
• timestamp: ISO-8601 UTC（YYYY-MM-DDTHH:MM:SS.fffZ）。

本文：センサーの JSON リスト（upsert-all の場合は ROI ／トリップワイヤー／ホモグラフィーも含む）。

リスナーは、保存前に同梱の AJV スキーマに照らして検証します。スキーマ違反は calibration schema violation の警告をログに記録して破棄されます。以前に正常だったキャリブレーションは読み込まれたままです。

ワイヤー形式の完全な仕様とアクションごとの検証ポリシーについては、references/dynamic-calibration.md を参照してください。

どちらのフローもブローカー上で完結します。プロデューサーには video-analytics-api、独自のスクリプト、またはワイヤー形式を再現する任意の Kafka クライアントを使用できます。コンテナの起動後に設定を変更する際に推奨される方法であり、オペレーターは再デプロイする必要がありません。

ルーティングルール

• ユーザーが「フルスタック」（UI ／エージェント／認識機能）を求めている場合は、プロファイル warehouse（または alerts）を指定して vss-deploy-profile に引き継ぎます。このスキルを並行して実行しないでください。
• すでに稼働中のコンテナにランタイム設定またはキャリブレーションの更新をパブリッシュしたい場合は、動的更新のセクションに沿って案内します。どちらのフローにも、接続可能なブローカーが必要です。
• 検証したい behavior-analytics の動作変更（新しいインシデントタイプ、新しい ROI ルール、新しいセンサーなど）についてユーザーが説明している場合は、JSON を編集する前に references/configuration.md、references/dynamic-config.md、または references/dynamic-calibration.md を案内します。

bump:1