vss-deploy-detection-tracking-3d

目的

RTVI-CV-3D マイクロサービスを MV3DT（MODE=mv3dt）としてデプロイして運用します。キャリブレーション済みの複数カメラを使った、カメラごとの DeepStream 認識と BEV Fusion を、同梱のサンプルデータセット、カスタム動画、またはライブ RTSP で実行します。倉庫エージェント／LLM／VLM スタック全体は必要ありません。

手順

上から順に進めます。ルーティングの質問（Q0〜Q3）に回答してから、選択したパスのリファレンスに従ってください。詳細な手順は references/ にあります（デプロイ、キャリブレーションチェーン、カメラ設定、検証、ティアダウン、トラブルシューティング）。

使用例

• サンプルデータセットでマルチカメラトラッキングを有効にする。
• こちらの動画で RTVI-CV-3D をデプロイする：<path/to/videos>。
• キャリブレーション後に RTSP ストリームで MV3DT を実行する。

VSS 検出・トラッキングのデプロイ — 3D（RTVI-CV-3D / MV3DT）

倉庫ブループリントから RTVI-CV-3D マイクロサービスを MV3DT スタック（MODE=mv3dt）として起動します。構成は、カメラごとの DeepStream 認識（vss-rtvi-cv-mv3dt）＋ BEV Fusion（vss-rtvi-cv-bev-fusion）＋ mosquitto MQTT バス＋ブローカー＋VST センサースタックです。倉庫ブループリント全体に含まれるエージェント／LLM／VLM スタックは含みません。

実際の Compose 構成は deploy/docker/industry-profiles/warehouse-operations/warehouse-mv3dt-app/ にあります。このスキルでは、環境変数のオーバーライド、キャリブレーションチェーン、検証を行います。

ルーティング

質問は最大4つにしてから、該当する手順に進みます。

Q0 — プロファイルのサイズ（オーバーレイの有無）

ユーザーが最小構成を明示的に希望しない限り、拡張構成をデフォルトにします。拡張構成では MV3DT コアに加えて、ELK、vss-video-analytics-api-mv3dt、vss-kibana-init-mv3dt、vss-import-calibration-output-mv3dt がデプロイされます。これらは VST ビデオウォールでバウンディングボックスのオーバーレイを表示するために必要です。これらがなくてもビデオウォールは動作しますが、オーバーレイのない生ストリームが表示されます。

ユーザーの回答	MINIMAL_PROFILE	構成内容	選択する状況
extended（デフォルト）	""	MV3DT コア＋ELK＋分析 API＋Kibana。VST ビデオウォールでオーバーレイが機能します。 完全なエンドツーエンド体験におすすめです。	「完全なエンドツーエンド体験がほしい」、「バウンディングボックスを見たい」、または希望が示されていない場合
minimal	"true"	MV3DT コアのみ。コンテナ数は約5つ少なくなります。VST でオーバーレイは表示されません。 メタデータは引き続き Kafka／Redis に送られます。	「データだけ必要」、「エッジ／Thor ホスト」、「最小のフットプリント」

ELK の選択的な有効化について： 現在の Compose には「最小構成＋ELK のみ」という中間構成はありません。${MINIMAL_PROFILE:+_extended} で制御されるサービス（ES、Logstash、Kibana、video-analytics-api、kibana-init、import-calibration）はすべて一緒に起動します。bash の :+ パラメーター展開は、MINIMAL_PROFILE が設定されている場合に _extended サフィックスを生成します。拡張構成では、制御文字列がプレーンな bp_wh_kafka_mv3dt に戻り、これはアクティブな Compose プロファイルにすでに一致します。拡張構成の一式を受け入れるか、最小構成のままにするかのどちらかです。

Q1 — データソース

ユーザーの最初のメッセージでソースが明示されていない場合は、この質問をします。「rtvi-cv-3d をデプロイして」のような簡潔な依頼は、この MV3DT スキル（MODE=mv3dt）に振り分けますが、sample を意味するわけではありません。

• sample — 同梱の4台カメラの合成データセット（warehouse-4cams-20mx20m-synthetic）。キャリブレーションデータはツリー内にあり、AMC の実行は不要です。
• videos — ユーザーがローカル動画ファイルを持っている場合（カメラ名に対応した任意の *.mp4）。キャリブレーションがない場合は、スタンドアロン AMC（auto_calib プロファイル）が実行されます。
• rtsp — ユーザーがライブ RTSP URL を持っている場合。キャリブレーションは VIOS 駆動の AMC で行います。最終デプロイには、それらの RTSP URL を含むセンサー情報ファイル（camera_info.json）も必要です。

Q2 — キャリブレーションの適用状況（sample の場合はスキップ）

videos と rtsp では、認識コンテナが想定するマウントパスにキャリブレーションデータがすでに存在するか確認します。

DATASET="${SAMPLE_VIDEO_DATASET:?}"          # the user's dataset slug; see Q3
CAL_DIR="${VSS_APPS_DIR}/industry-profiles/warehouse-operations/warehouse-mv3dt-app/calibration/sample-data/${DATASET}"

# Look for ANY of: calibration.json, plus camInfo/*.yml or *.yaml with either
# 'cam_*' or 'Camera*' naming (the shipped sample uses Camera*.yml, AMC may
# produce cam_*.yaml — broaden accordingly)
test -f "${CAL_DIR}/calibration.json" \
  && ls "${CAL_DIR}/camInfo/"*.{yml,yaml} 2>/dev/null

ユーザーがキャリブレーションパスを指定した場合は、再計算せずにそのパスを検証します。カメラ名の正規化と、カメラ数の確定に使用する正式な方法（calibration.json を解析）については、configure-cameras.md を参照してください。

Q3 — 検出器 + データセットのスラッグ（Q2でAMCを使用する場合のみ）

• resnet（デフォルト、高速）または transformer（低速、遮蔽に強い） — Step BでAMCの /v1/calibrate/<id> APIに渡されます（vss-generate-video-calibration/SKILL.md:48-62を参照）。
• SAMPLE_VIDEO_DATASETとして使用する、短いケバブケースのデータセットスラッグ（例：customer-aisle-4cams）。これはキャリブレーションのマウントパスを決定し、.envに保存されます。

ルーティング表

Q1	Q2の結果	パス
sample	（calはリポジトリ内にあり、すでに正規化済み）	references/deploy-rtvi-cv-3d-stack.mdへ直接
videos	calあり	references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md
videos	calなし	references/calibration-workflow.md（videosモード） → references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md
rtsp	calあり	references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md
rtsp	calなし	references/calibration-workflow.md（rtspモード） → references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md

どのパスも、up -dの完了後にreferences/verify-and-view.mdに合流します。 references/troubleshooting.mdとreferences/teardown.mdへのリンクもありますが、通常の手順には含まれません。

用語の区別ルール。 このスキルで「RTVI-CV-3D」はMV3DTマイクロサービスのデプロイを意味し、MODE=mv3dtを使用します。フルの倉庫ブループリント、Sparse4D、MODE=3d、またはwarehouse-3d-appをユーザーが求めた場合に限り、../vss-deploy-profile/references/warehouse.mdに誘導してください。このスキルの対象は、エージェントスタック／LLM／VLMを含まないMV3DTのみです。

前提条件

1. リポジトリのパス

ディスク上でvideo-search-and-summarization/を探します。すべてのcomposeコマンドは<repo>/deploy/docker/から実行します。不明な場合はユーザーに確認してください。

2. NGC CLI + キー

$NGC_CLI_API_KEYが設定されており、nvidia/vss-core/*イメージへのアクセス権が必要です。未設定の場合は、セットアップ方法についてvss-deploy-profile/references/ngc.mdを参照してください。

ユーザーが以前にngc config setを実行していても、このシェルで$NGC_CLI_API_KEYがエクスポートされていない場合、キーはすでにディスク上にあります。

NGC_CLI_API_KEY=$(awk -F'= ' '/^apikey/{print $2}' ~/.ngc/config 2>/dev/null)
test -n "${NGC_CLI_API_KEY}" && echo "key sourced from ~/.ngc/config"

キーの値がindustry-profiles/warehouse-operations/.env:164（NGC_CLI_API_KEY=...）にも設定されていることを確認してください。composeはupの実行時にシェル環境変数からではなく、そこからのみ値を読み取ります。

3. HARDWARE_PROFILE スラッグ

公開されている MV3DT の対応ストリーム数は、Warehouse Quickstart Guide の「MV3DT Vision AI Profile Supported Deployment Options」に記載されています。以下から該当する HARDWARE_PROFILE スラッグを選択してください。

nvidia-smi --query-gpu=name --format=csv,noheader の出力から選択してください。

GPU 名	HARDWARE_PROFILE	MV3DT の対応ストリーム数
RTX PRO 6000 Blackwell	RTXPRO6000BW	18
H100 (NVL, SXM HBM3)	H100	13
L40S	L40S	7
IGX Thor	IGX-THOR	4
DGX Spark	DGX-SPARK	4

ユーザーの GPU がここに記載されていない場合は、industry-profiles/warehouse-operations/.env で利用可能な HARDWARE_PROFILE の値を確認し、使用する前に、該当するプロファイルが blueprint-configurator/blueprint_config.yml に存在することを確認してください。スラッグだけからストリーム数を推測しないでください。

GPU ごとの MV3DT 上限はデプロイ時に適用されます。 vss-configurator-mv3dt は final_stream_count = min(NUM_STREAMS, max_streams_supported) を計算し、${VSS_DATA_DIR}/videos/${SAMPLE_VIDEO_DATASET}/ に対して keep_count ファイル管理オペレーションを適用することで、final_stream_count 個の .mp4 ファイルのみを残します（辞書順に並べ、末尾の N 個を保持）。GPU の MV3DT 対応ストリーム数（上表）がカメラ数を下回る場合、perception、mdx-raw、mdx-bev は対応ストリーム数で実行されます。対応ストリーム数がより多い GPU を選ぶか、どのストリームが処理されるかユーザーが把握できるよう、上限を明示してください。

4. ディスク上のアプリデータ

VSS_DATA_DIR は、（リポジトリとは別の）展開済みの vss-warehouse-app-data ディレクトリを指している必要があります。リポジトリの deploy/docker/ を指定すると、デプロイが停止します。コンフィギュレーターがデータセットを見つけられず、redis がログファイルを開けず、perception は Created のままになります。デプロイ前にパスを確認してください。

デプロイ前のチェック：

DATA_DIR="${VSS_DATA_DIR:?VSS_DATA_DIR not set in .env}"
DATASET="${SAMPLE_VIDEO_DATASET:-warehouse-4cams-20mx20m-synthetic}"

for sub in videos models data_log; do
  test -d "${DATA_DIR}/${sub}" || { echo "ERROR: ${DATA_DIR}/${sub} missing"; exit 1; }
done

# For sample / videos modes — videos directory must exist
test -d "${DATA_DIR}/videos/${DATASET}" \
  || { echo "ERROR: ${DATA_DIR}/videos/${DATASET} missing — wrong slug or app-data not extracted"; exit 1; }

# Sanity: video count should match calibration count.
# Some published app-data tarballs are known to ship the sample dataset with
# fewer videos than the dataset name implies — verify and source any missing
# cams separately if your GPU's mv3dt cap is high enough to use them all.
ls "${DATA_DIR}/videos/${DATASET}/"*.mp4 2>/dev/null | wc -l

# Ensure every per-service subdir under data_log/ exists. kafka / elasticsearch /
# redis / postgres and the video-analytics API upload path (`/web-api-app/files`)
# run as non-root UIDs against these bind mounts. Without write access the daemons
# or calibration/image import can fail with permission errors.
mkdir -p \
  "${DATA_DIR}/data_log/analytics_cache" \
  "${DATA_DIR}/data_log/calibration_toolkit" \
  "${DATA_DIR}/data_log/elastic/data" \
  "${DATA_DIR}/data_log/elastic/logs" \
  "${DATA_DIR}/data_log/kafka" \
  "${DATA_DIR}/data_log/redis/data" \
  "${DATA_DIR}/data_log/redis/log" \
  "${DATA_DIR}/data_log/vss_video_analytics_api"

# Grant write access to the specific container UIDs only — scoped ACLs, NOT 777 and
# NOT chown. UIDs (per data-directory.md): postgres=70, redis=999, elasticsearch / VST /
# kafka=1000. The first call covers existing files; the second sets *default* ACLs so
# files/dirs the daemons create at runtime (e.g. postgres PGDATA) inherit the access.
ACL='u:70:rwx,u:999:rwx,u:1000:rwx'
setfacl -R    -m "$ACL" "${DATA_DIR}/data_log"
setfacl -R -d -m "$ACL" "${DATA_DIR}/data_log"

chmod 777 ではなく、対象を限定した ACL を使用してください。 既知のコンテナー UID のみがアクセスできるようにします。これにより data_log が誰でも書き込み可能になることはなく、chown も実行しません（初回起動時に postgres／Elasticsearch が各自のディレクトリの所有権を変更するため、chown は問題を引き起こします）。エージェント主導の実行や共有ホストでは、こちらを優先してください。標準の ../vss-deploy-profile/references/data-directory.md には、広範な chmod -R 777 とコンテナーごとの UID 表が記載されています。このスキルでは、代わりに対象を限定した ACL を使用します。ホストの権限を変更する前に、ユーザーに確認してください。

POSIX ACL 対応のファイルシステム（ext4／xfs。デフォルト）と、acl パッケージ（setfacl）が必要です。デプロイ後もデーモンが権限エラーをログに記録する場合は、その UID を確認し（docker inspect <container> --format '{{.Config.User}}'）、両方の呼び出しに -m u:<uid>:rwx を追加してください。

アプリデータがまだ展開されていない場合は、ngc registry resource download-version "nvidia/vss-warehouse/vss-warehouse-app-data:<version>" でダウンロードし、tar -xvf で展開してください（タグの確認方法と全手順については、references/deploy-rtvi-cv-3d-stack.md を参照してください）。

5. 事前チェック（システム）

nvidia-smi、NVIDIA Docker ランタイムの認識確認（docker info | grep -i runtimes）、および docker run --rm --gpus all ubuntu:24.04 nvidia-smi がすべて成功することを確認してください。ドライバー／カーネル／sysctl の全チェックについては、vss-deploy-profile/references/prerequisites.md を参照してください。

チェックに失敗した場合は、続行する前に修正してください。デプロイに進まないでください。

6. ブラウザーからの到達性（クラウド／社内 VPN ホストのみ）

デプロイ先ホストとは異なるネットワーク上のブラウザーからユーザーが VST ビデオウォールを表示する場合（クラウド VM、社内 VPN、SSH トンネル経由のセッションなど）、上流のファイアウォールルールによって VST WebRTC（stun.l.google.com:19302 への STUN、およびメディア用のランダムな UDP）がブロックされることがあります。症状と回避策については、references/verify-and-view.md#browser-reachability を参照してください。また、一部のホストでは AMC マイクロサービスのデフォルトポート（TCP/8010）がブロックされます。ユーザーから「:5000 の AMC UI は動作するが、データ呼び出しは失敗する」と報告された場合は、別の VSS_AUTO_CALIBRATION_PORT を指定して再試行してください。

トラブルシューティング

デプロイ、キャリブレーション、または検証の手順に失敗した場合は、再試行する前にいったん停止し、失敗の種類を特定してください。以下の簡易チェックでは、よくある MV3DT エラーを取り上げています。詳しい診断コマンドと修正方法については references/troubleshooting.md、AMC ワークフローの失敗については ../vss-generate-video-calibration/SKILL.md、より広範なウェアハウススタックの問題については ../vss-deploy-profile/references/warehouse-debug.md を参照してください。

症状	考えられる原因	最初に確認すること、または修正方法
vss-rtvi-cv-bev-fusion が正常でない、または /tmp/fusion_ready が見つからない	ブローカーの準備ができていない、MAX_EXPECTED_SENSORS が一致しない、または STREAM_TYPE が一致しない	broker-health-check、docker inspect --format '{{.State.Health.Status}}' vss-rtvi-cv-bev-fusion、および mdx-raw / mdx-bev を確認します。ストリーム数が異なる場合は references/configure-cameras.md を再実行してください
Perception に Active sources : 0 と表示される、FPS が表示されない、またはカメラの数が想定より少ない	VST センサー状態が古い、データセットのスラッグが間違っている、キャリブレーションがない、または GPU あたりのストリーム数の上限に達している	SAMPLE_VIDEO_DATASET、NUM_STREAMS、camInfo/、および VST センサーリストを確認します。古いセンサーが残っている場合は、再デプロイの前に references/teardown.md に従ってください
vss-rtvi-cv-mv3dt が MqttCommunicator の「invalid node」またはトラッカーの送信エラーで終了する	動画、calibration.json、および camInfo/ のカメラ名が Camera、Camera_01、... の命名規則に一致していない	references/configure-cameras.md の手順 0 に従って、すべてのカメラ名を揃えます。その後、古い VST 状態をクリアして再デプロイしてください
AMC プロジェクトの作成、アップロード、キャリブレーション、または MV3DT エクスポートに失敗する	この MV3DT デプロイ手順の範囲外にある AutoMagicCalib サービス／API の問題	../vss-generate-video-calibration/SKILL.md を使用して AMC のデプロイ／デバッグを行い、エクスポートに成功したら references/calibration-workflow.md に戻ってください
vss-behavior-analytics-mv3dt がキャリブレーションのスキーマ検証エラーで再起動する	AMC のエクスポートで group、region、または place のフィールドが空になっている	references/calibration-workflow.md の手順 4a にあるプレースホルダーパッチを適用するか、エクスポート前に AMC でこれらのフィールドを入力してください
拡張プロファイルでオーバーレイが表示されず、vss-import-calibration-output-mv3dt に imageMetadata.json not found と記録される	AMC の MV3DT エクスポートで images/Top.png と images/imageMetadata.json が生成されていない	references/calibration-workflow.md の手順 4b に従って両方のファイルを生成し、ワンショットインポーターを再起動してください
イメージのプル、モデルの読み込み、または初回起動時のエンジンビルドに失敗する	NGC_CLI_API_KEY がない／期限切れ、VSS_DATA_DIR が正しくない、BodyPose3DNet ファイルがない、または GPU の OOM	NGC 認証を再確認し、${VSS_DATA_DIR}/models/mv3dt/BodyPose3DNet/ があることを確認します。vss-rtvi-cv-mv3dt のログを確認し、GPU のメモリが不足している場合は空き容量を確保するか RT_CV_DEVICE_ID を変更してください

破壊的な復旧作業（docker compose down -v、data_log のクリア、VST センサー状態の削除、またはホスト ACL の変更）を行う前に、影響を説明してユーザーの確認を得てください。状態をリセットする変更を行う前に、失敗したコマンド、関連する .env の値、docker compose ps の出力、およびコンテナーの直近のログを記録してください。

全体の仕組み

SKILL.md (this file — Q0/Q1/Q2/Q3 routing)
  └─ if cal missing ─> calibration-workflow.md
  │                     └─ chains to vss-generate-video-calibration (deploy + drive API)
  │                     └─ fetches /v1/result/{project_id}/mv3dt_result?result_type=amc (plus vggt when refinement is enabled)
  │                     └─ lands calibration files at warehouse-mv3dt-app/calibration/sample-data/<slug>/
  ├─> configure-cameras.md (camera-name normalization, NUM_STREAMS sync, VST sensor trim)
  └─> deploy-rtvi-cv-3d-stack.md (compose up with bp_wh_kafka_mv3dt + extended/minimal)
        └─> verify-and-view.md (FPS, fusion_ready, mdx-bev, VST video wall + WebRTC checks)

関連スキル

• vss-generate-video-calibration — AMC スキルです。AMC のデプロイ、RTSP キャプチャ、キャリブレーション API、およびこのスキルが使用する /v1/result/.../mv3dt_result エクスポートフックを担当します。calibration-workflow.md からこのスキルへつながります。
• vss-deploy-profile — プロファイル横断の包括スキルです。MV3DT だけでなく、エージェント／LLM／VLM を含む倉庫の全体設計図が必要な場合は、代わりにこちらを使用してください。
• vss-manage-video-io-storage — VIOS／VST API スキルです。VST ビデオウォール（オーバーレイ表示）や、configure-cameras.md で参照されているセンサー管理に役立ちます。

リポジトリの正式な倉庫設計図リファレンスである ../vss-deploy-profile/references/warehouse.md では、倉庫スタック全体における 2D／3D／MV3DT を扱っています。このスキルは、エージェント／LLM／VLM レイヤーを省いたMV3DT 専用の補完スキルです。