vss-setup-video-analytics-api

目的

ユーザーが選択した設定、データログのバインド、Elasticsearch／Kafka への接続を使用して、video-analytics-api REST サービスを単独でデプロイします。

手順

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

例

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

nv-base validate skills/vss-setup-video-analytics-api --agent-eval

最小構成で単独起動する場合は、次のようになります。

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data}
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

完全なワークフロー（設定ソース、データログのバインド、インフラストラクチャの依存関係、REST エンドポイント）については、references/deploy-video-analytics-api-service.md に従ってください。 JSON 設定の各フィールドのリファレンスについては、references/configuration.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 Setup Video Analytics API — Standalone

フルの warehouse blueprint スタックの一部としてではなく、vss-video-analytics-api コンテナ（上流の video-analytics-api リポジトリにある Node.js REST API）のみをデプロイします。

運用手順の全体（設定ソースのオプション、データログボリュームの動作、インフラストラクチャの依存関係、REST API エンドポイント、デプロイと検証、トラブルシューティング）は、references/deploy-video-analytics-api-service.md にあります。JSON 設定の各フィールドのリファレンスは、references/configuration.md にあります。この SKILL.md では、ルーティングと前提条件のみを扱います。

使用する場面

• 「Deploy video analytics api」／「video-analytics-api を単独で実行したい」
• 「フルスタックではなく、REST API だけを実行したい」
• 「独自の video-analytics-api 設定を使いたい」
• 「API の接続先を別の Elasticsearch／Kafka にしたい」
• 「Kafka なしで API を起動したい」／「ブローカーなしで API を実行したい」
• 「利用可能な REST エンドポイントを確認したい」

前提条件

1. リポジトリのチェックアウト。$VSS_APPS_DIR が <repo>/deploy/docker/ を指している必要があります。サービスの Compose ファイルでボリュームをバインドするために必要です。

2. NGC 認証情報。Docker がイメージをプルできるよう、$NGC_CLI_API_KEY を設定してください。references/ngc-api-key-registry-login.md を参照してください。

   NGC_CLI_API_KEY の安全な取り扱いに関する注意：このキーは長期間有効な認証情報であり、NGC 組織で利用可能な NVIDIA のプライベートイメージをすべてプルできます。このキーを絶対にコミットしたり、チャットに貼り付けたり、/tmp に保存したりしないでください。対話的に読み込む（read -rs NGC_CLI_API_KEY）か、デプロイ時にシークレットマネージャー（Vault、AWS Secrets Manager、sealed-secrets）から読み込んでください。派生した .env ファイルを書き込む場合は、umask 077 と chmod 600 を設定し、.gitignore に追加してください。また、定めた周期およびホストの廃止後には必ずキーをローテーションしてください。ホストのスナップショット、画面共有、チケットへの添付などにより、一度でも公開された可能性がある場合は、直ちにローテーションしてください。

3. Docker ランタイム。Docker Engine 28.3.3 と Docker Compose プラグイン v2.39.1+ が必要です。docker --version と docker compose version で確認してください。

4. Elasticsearch。elasticsearch.node で設定した URL から到達可能である必要があります。サーバーは起動時に ES に ping を送信し、到達できない場合は終了します（その後、restart: always により再起動します）。ES も起動する必要がある場合は、インフラ用 Compose ファイルを使用してください：docker compose -f services/infra/compose.yml up -d elasticsearch。

5. 任意の Kafka ブローカー。API は Kafka なしでも実行できます。ブローカーを使用しない静かなデプロイを行う場合は、イメージに組み込み済みの設定、または kafka.brokers: [] を指定したカスタム設定を使用してください。サービスに同梱された Compose 設定は localhost:9092 を参照するため、Kafka に依存する機能（動的設定、動的キャリブレーション、RTLS/AMR）は、ブローカーに到達できるようになるまで失敗します。

6. デフォルトの Compose 用の $VSS_DATA_DIR。ベース Compose ファイルでは、マルチパートアップロード処理と、キャリブレーション画像などのファイルベースのアセットのために、$VSS_DATA_DIR/data_log/vss_video_analytics_api をバインドマウントします。このディレクトリをホスト上の書き込み可能なパスに設定して事前に作成するか、画像のアップロードが不要な場合はこのマウントを削除してください。

必須の前提条件を満たせない場合は、先に進む前に不足している点を明らかにしてください。

ワークフロー

ユーザーに references/deploy-video-analytics-api-service.md を提示し、記載された手順を順番に案内してください。

1. 設定を選択します。イメージに組み込み済みのデフォルト設定、サービスに同梱された設定、またはカスタム設定から選びます。
2. ファイルアップロード用のデータログボリュームが必要かどうかを決定します。
3. インフラストラクチャの依存関係を確認します。Elasticsearch（必須）、Kafka（任意）。
4. docker compose up とヘルスチェックでデプロイして検証します。

Compose ファイルの編集、設定オプション、デプロイおよび検証用コマンド、REST API エンドポイントの表、トラブルシューティングの表はすべて、このリファレンスに記載されています。ここで重複して記載しないでください。

エンドポイントのリファレンス

REST エンドポイントの表と実行時の依存関係に関する注意事項については、references/deploy-video-analytics-api-service.md を参照してください。

Kafka 依存機能（実行時にブローカーが必要）

コンテナが起動し、Kafka ブローカーに到達できる状態になると、3 つの機能が追加で利用可能になります。

動的設定

API は動的設定更新のプロデューサーとして動作します。オペレーターが /config に POST すると、API は Kafka キー behavior-analytics-config を指定して、mdx-notification トピックに upsert メッセージを発行します。下流の behavior-analytics コンテナはこれを受信して ACK を返します。また、API はブートストラップフローも処理します。behavior-analytics の起動時に request-config メッセージを発行し、API は Elasticsearch から取得した最新の検証済み設定を含む upsert-all を返信します。

コンシューマー側の検証、ACK のセマンティクス、完全なワイヤーコントラクトについては、vss-setup-behavior-analytics の動的設定リファレンスに記載されています。

動的キャリブレーション

API は Kafka キー calibration を使用して、mdx-notification 上にキャリブレーション更新通知を生成します。upsert-all（完全スナップショット）、upsert（センサーごとのマージ）、delete（センサーごとの削除）をサポートしています。ダウンストリームの behavior-analytics コンテナはこれらを消費し、ライブキャリブレーションに適用します。

コンシューマー側の検証とアクションごとのポリシーは、vss-setup-behavior-analytics の動的キャリブレーションリファレンスに記載されています。

RTLS / AMR

API は Kafka からリアルタイム位置情報（mdx-rtls）と AMR（mdx-amr）のメッセージを消費し、REST エンドポイント経由で公開します。

ルーティングルール

• ユーザーが「フルスタック」（UI / エージェント / 知覚）を希望する場合: プロファイル warehouse（または alerts）を指定して vss-deploy-profile にハンドオフします。このスキルを並行して実行しないでください。
• ユーザーが分析パイプライン（行動作成、インシデント検出）をデプロイしたい場合: vss-setup-behavior-analytics にハンドオフします。
• ユーザーが REST API 経由でランタイム設定 / キャリブレーション更新を公開したい場合: Kafka に到達可能であることを確認し、/config またはキャリブレーションエンドポイントを使用して、コンシューマーのワイヤー契約については behavior-analytics の動的更新リファレンスを参照するよう案内します。
• ユーザーがコンシューマー（behavior-analytics）側から動的設定 / 動的キャリブレーションのワイヤー契約を理解したい場合: vss-setup-behavior-analytics の動的設定および動的キャリブレーションのリファレンスを案内します。
• ユーザーが REST API エンドポイントを照会または操作したい場合: デプロイリファレンスのエンドポイント表に利用可能な内容が記載されています。完全な OpenAPI 仕様については、video-analytics-api リポジトリの src/app/specification/openapi.json を参照してください。

bump:1