vss-deploy-detection-tracking-2d

目的

RTVI-CV 検出／追跡 2D マイクロサービスをデプロイ、デバッグ、運用し、その REST API を操作します。

前提条件

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

手順

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

例

一連の手順を通した実行例は evals/ に格納されています（各 *.json マニフェストには実行可能なシナリオが含まれます）。また、以下のワークフローごとの curl ブロックにもインラインで記載されています。Tier-3 評価を実行するには、nv-base validate <this-skill-dir> --agent-eval を実行して例を再生してください。

制限事項

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

トラブルシューティング

• エラー：REST 呼び出しで connection refused が返されます。原因：対象のマイクロサービスが実行されていません。解決策：/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 を解放してください。

RTVI-CV — 検出と追跡（統合スキル）

Real Time Video Intelligence CV（RTVI-CV） マイクロサービス向けの統合スキルです。1 つのスキルで 2 つの操作を実行できます。

• RTVI-CV コンテナーをローカルにデプロイ／運用／デバッグ／停止する → references/deploy-vss-detection-tracking-2d.md を参照
• 稼働中のインスタンスで RTVI-CV REST API（ストリーム、ヘルス、メトリクス、埋め込み）を呼び出す → references/usage-vss-detection-tracking-2d.md を参照

サービス：rtvi-cv（metropolis_perception_app） イメージ：nvcr.io/<org>/<repo>:<tag> — デプロイ時にユーザーが指定 REST ポート：9000（/api/v1 — /live、/ready、/startup、/metrics、/stream/add、/stream/remove、埋め込み） ハードウェア：x86/aarch64 dGPU（T4、A100、L40、H100、B200、RTX）、SBSA（Spark、Grace-Hopper）、Jetson（Thor、Orin、Xavier）

---

アクションの振り分け — 呼び出しごとに一度選択

ユーザーの意図（表現例）	フロー	読み込むリファレンス
deploy rtvi-cv warehouse 2d、run rtvicv warehouse-3d with 4 streams、start smartcity gdino、launch perception app、bring up sparse4d	デプロイ	references/deploy-vss-detection-tracking-2d.md
stop rtvi-cv、tear down、kill the perception container、cleanup rtvicv-perception-docker	停止（deploy doc →「モードの選択」で処理）	references/deploy-vss-detection-tracking-2d.md + references/teardown-flow.md
check rtvi-cv logs、diagnose rtvi-cv crashing、troubleshoot healthcheck failing、rtvi-cv won't start	デバッグ	references/deploy-vss-detection-tracking-2d.md + references/troubleshooting.md
add a stream、remove camera、list streams、health check、is rtvi-cv ready、get metrics、what's the FPS、check GPU usage、generate text embeddings、call rtvi-cv api	API の使用	references/usage-vss-detection-tracking-2d.md + references/api-reference.md

選択ルール： ユーザーの表現を上の表と照合し、該当するリファレンスファイルをすぐに読み込みます。フローを混在させないでください。デプロイではコンテナはまだ起動していないものとし、API の使用ではコンテナがすでに http://<host>:9000 で起動しているものとします。

意図が本当に曖昧な場合（例：「rtvi-cv を使いたい」とだけ言われた場合）は、AskQuestion を一度使い、新しいインスタンスをデプロイするのか、すでに起動中のインスタンスを呼び出すのかを尋ねます。

---

配置場所

vss-deploy-detection-tracking-2d/
├── SKILL.md          # this file (routing + contracts)
├── assets/           # data files (deploy-defaults.yml — single source of truth for tags / refs / paths / GPU)
├── evals/            # Tier-3 eval manifests (deploy-evals.json, usage-evals.json)
├── scripts/          # 23 bash + python helpers (see `scripts/` for the full inventory)
└── references/       # workflow runbooks (deploy / api-usage / teardown / troubleshooting / …)

ファイルごとの全一覧と各リファレンスの内容については、 references/workflow-reference.md を参照してください。

すべてのスクリプトはスキルのルートから $SKILL_DIR/scripts/<name> を使って実行します。deploy リファレンスドキュメント内のパスはそのまま保持されており、エージェントがスキルのルートから実行すると正しく解決されます。

---

利用可能なスクリプト

ヘルパーは scripts/ にあり、スキルのルートから名前を指定して実行します。 エージェントが適切なツール呼び出しを記録できるよう、それぞれ run_script("scripts/<name>") で呼び出してください。

スクリプト	用途	引数
load_defaults.sh	プラットフォーム（x86 dGPU / SBSA / Jetson）を検出し、assets/deploy-defaults.yml から YAML のデフォルト値を解決します。	--usecase <name>
fetch_resources.sh	NGC リソースをダウンロードして展開し、レイアウトをスキャンします。	--ngc-ref <ref>（任意）
apply_in_container.sh	ステップ 4 用のホスト側ラッパー（実行中のコンテナ内で apply_config.sh を実行）。	<container_name>
apply_config.sh	コンテナ内でパス置換、バッチ、シンク、ソース、エンジンキャッシュを設定します。	<usecase> <stream_count> <sink_type>
start_app_in_container.sh	ステップ 5 用のホスト側ラッパー（run_app_and_wait.sh を実行）。	<container_name>
run_app_and_wait.sh	コンテナ内でアプリを起動し、準備完了状態、メトリクス、ログを確認します。	<config_path>
add_streams.sh / update_stream_sources.sh	ステップ 6 用の REST ストリームのライフサイクル管理。	<rtsp_or_file_uri>...
collect_metrics.sh	/api/v1/metrics のスナップショットを取得します。	なし
discover_streams.sh	/stream/get-stream-info を使ってアクティブなストリームを列挙します。	なし
synthesize_docker_run.sh	解決済みの環境に対応するプラットフォーム別の docker run 行を表示します。	なし
render_box.sh	固定幅のステップレシートを表示します。	<step_label>
calibration_manager.py	キャリブレーション成果物とユースケースごとのエンジンキャッシュの無効化を管理します。	--usecase <name> --reset

ヘルパー（キャッシュ、GPU チェック、セットアップ）の全一覧は scripts/ を参照してください。各スクリプトの --help で引数を確認できます。

このスキルの使い方

1. まずこのファイルを読んでください。 これはルーティングのみを行い、ワークフローは記載していません。
2. ユーザーの意図を上記のルーティングテーブルと照合してください。
3. 参照ドキュメントは1つだけ（DEPLOY または API USAGE）読み込んでください。両方を先読みしないでください。各参照ドキュメントは大きく、独自の完全な仕様を含んでいます。
4. 読み込んだ参照ドキュメントに厳密に従ってください。 参照ドキュメントは、前身のスキル vss-deploy-detection-tracking-2d（デプロイ／ティアダウン／デバッグ）および rtvicv-api（REST API）から、バイト単位でそのまま保持された仕様です。手順の順序に関するすべての不変条件、bash のバッチ処理ルール、ボックス描画ルール、AskQuestion の仕様が維持されています。
5. DEPLOY の場合、参照ドキュメントでは独自の起動仕様が定められています。1行の確認 → 計画ツールの呼び出し（TodoWrite 配列で5件の todo、または新しい Claude Code では TaskCreate を5回連続で呼び出し）→ Step 1 の質問。この手順を語らず、事前確認を行わず、「loading TodoWrite/TaskCreate」や、遅延ツールの解決に関する説明を決して出力しないでください。計画ツールは黙って読み込まれます。

---

出力仕様 — DEPLOY フロー

DEPLOY／TEARDOWN／DEBUG フローを実行する場合、エージェントはデプロイが正常に完了するたびに、以下の4項目すべてを遵守しなければなりません。これらは手順間におけるユーザー唯一のフィードバック手段です。いずれかを省略すると、動作の後退となります。

1. 各ステップの終了時に、固定幅のボックスを表示する — Step 1 デプロイ対象、Step 2 パイプライン設定、Step 3 コンテナー、Step 4 設定の適用、Step 5 計画 ＋ 結果。最後の要約だけでは不十分です。このボックスは、ユーザーが各ステップを完了したことを確認するためのものです。ボックスの寸法は固定です（下記の「Universal box format」を参照）。各ボックス内に入れる行の内容に関するルールは、references/deploy-vss-detection-tracking-2d.md の「Step N box content rule」に記載されています。
2. Step 5 の結果ボックスの後に、references/next-steps.md §「11.c」にある Step 6 の AskUserQuestion を提示してください。自由形式の 次のステップ 箇条書きに置き換えてはいけません。このメニューはデプロイ終了時の操作手段です。ユーザーは curl URL を覚えておかなくても、ワンクリックでメトリクスの確認、ストリームの管理、ログの追跡、またはティアダウンを実行できます。
3. ユーザーが Step 6 の項目を選択した後、references/next-steps.md §「11.d」にあるフォローアップの AskUserQuestion を提示してください。説明文＋そのままコピーできる curl の例＋自由入力の「X を実行しましょうか？」という質問に置き換えてはいけません。各項目には具体的な操作メニューがあり、ユーザーが操作を選ぶと、スキルが API ボックスを表示して curl を実行します。項目ごとのフォローアップ：
   • ストリームを管理 → 追加／削除／一覧表示。削除の選択肢は /stream/get-stream-info から動的に構成します。アクティブなストリームごとに <camera_id> · <camera_url> というラベルの選択肢を1つ表示し、ACTIVE > 1 の場合は「すべて削除」も表示します（完全な仕様は §「remove_streams sub-flow」を参照）。
   • デプロイを停止 → アプリを停止／コンテナーを停止／完全なティアダウン。
   • メトリクスと FPS を確認 → フォローアップはありません。/api/v1/metrics の API ボックスを表示した直後に collect_metrics.sh を実行します。
   • ライブネス／レディネスを確認 → フォローアップはありません。各 API ボックスを表示した後、3つすべてのヘルスエンドポイントをプローブします。
4. 概要行ではなく、ステップごとの内容をすべて表示する — ボックスの表示は必要ですが、それだけでは不十分です。各ステップの行構成仕様は、references/deploy-vss-detection-tracking-2d.md の「Step N box content rule」に記載されています。最も内容が省略されやすいのは Step 4（設定の適用）です。用途別の標準キー一覧は、references/apply-config.md §「Per-use-case complete edit list」に記載されています。エージェントは、該当するユースケースと設定について、その表の各キーにつき ✔ [section] key=value — annotation の行を1行ずつ必ず出力しなければなりません。キーが5つのセクションなら5行、6つなら6行です。セクションごとに概要行を1行だけ出すことはできません。 禁止事項（これらはエージェントがプレッシャーを感じたときに頼りがちなショートカットであり、ユーザーの UX を損ないます）。

• ❌ 内部のツール読み込みに関する説明。「タスクウィジェットのためにスキルが呼び出す遅延ツールの TodoWrite を読み込む必要があります」「TaskCreate を読み込み中…」「計画用ツールについて ToolSearch を呼び出しています…」など、遅延ツールの解決・読み込み・取得についてのテキストは、決して出力しないでください。 エージェントはツールを無言で読み込みます。ユーザーに表示されるのは、✔ <pinned-values> の概要行と、その後のウィジェットだけです。ツール解決に関する前置きは一切表示されません。
• ❌ 5 つのデプロイ手順すべてを、1 回の TaskCreate の description フィールドにまとめること。TaskCreate が利用可能な計画ツールの場合は、5 つの手順それぞれに対して、TaskCreate を 5 回続けて呼び出してください。逐語的なテンプレートについては、references/task-list.md の「Initial TaskCreate calls」を参照してください。TodoWrite でも同じルールが適用されます。5 つすべての TODO を todos:[…] 配列にまとめた 1 回の呼び出しにしてください。複数行のリストを content に含む TODO を 1 つだけ作成してはいけません。
• ❌ dynamic ストリームモードを勝手に選ぶこと。スキルのデフォルトは stream_mode=static です。アプリの起動前に、自動検出された file:// URL を DS メイン設定の [source-list] ブロックに組み込みます。dynamic への切り替えは、ユーザーが明示的に希望した場合（「後から REST 経由でストリームを追加する」「dynamic ストリームモードを使う」など）、または Step 2 の AskQuestion でユーザーが dynamic を選んだ場合に限ります。「rtvi-cv を N 個のストリームでデプロイ」のような一般的な依頼に対して dynamic を選ぶと、デプロイの評価基準に反し、ユーザーが /metrics に期待する内容を損ないます。詳しい理由については、references/pipeline-config.md の「Defaults — the skill is static-mode by default」を参照してください。
• ❌ Step 5 の「結果」ボックスの代わりに、「✔ アプリの準備完了：N 秒、N ストリーム、合計 Y fps」のような 1 行だけを表示すること。
• ❌ 軽量の罫線文字（┌ ─ ┐ │ └ ┘）ではなく、ASCII の罫線文字（+、-、=、*）を使うこと。
• ❌ 「ユーザーは次に何をすべきかわかっている」という前提で Step 6 を省略すること。
• ❌ Step 6 の後に、文章と複数の curl ブロックを長々と並べ、最後に「どれか実行しましょうか？」と尋ねること。これはエージェントが頼りがちな形式であり、11.d のメニューと API 呼び出しごとのボックスの両方を迂回します。ユーザーはメニューから選び、スキルは解決済みの API ボックスを表示し、その API 呼び出しを実行します。自由形式の質問は禁止です。
• ❌ Step 4 の概要を省略すること。デプロイのドキュメントにある Step 4 の内容ルールで、次の形式は禁止されています。
  • ✔ Batch size 3 (tile grid: 1×3) → 必須：5 行に分けて記載（[streammux] batch-size=3、[primary-gie] batch-size=3、[source-list] max-batch-size=3、[tiled-display] rows=1、[tiled-display] columns=3）。
  • ✔ Output sink eglsink → 必須：シンクのキーごとに 1 行ずつ記載（eglsink の場合は 4 つのキー。例：[sink0] enable=1、type=2、sync=0、qos=0。正確な一覧は apply-config.md を参照してください）。
  • ✔ Sources static (3 streams, http-port=9000) → 必須：注釈付きの [source-list] を 6 行記載。
  • ✔ Tile grid 1 row × 3 cols（1 行だけ）→ 必須：[tiled-display] rows=1 と [tiled-display] columns=3 の 2 行を記載。

ユニバーサルボックス形式

すべてのステップ終了時ボックス（ステップ 1 からステップ 5 の結果まで）に適用されるジオメトリの仕様です。すべてのボックスで同じ形状を使用し、ステップごとに変わるのはタイトルと 本文の行だけです。

• 幅：角から角まで 128 文字 — ┌ は 1 列目、┐ は 128 列目です。幅の広いターミナルでもボックスは左端にそろえ、引き伸ばさないでください。内側のコンテンツ領域は 124 文字です（│ の内側に左右それぞれ 1 つのスペースを設けます）。
• 罫線にはライトボックス描画文字のみを使用：┌ ─ ┐ │ └ ┘。+、-、=、 * による ASCII 代替表記は使用しません。
• 上罫線 — タイトルを中央揃え：┌ + N₁ 個のダッシュ + ␣ + タイトル + ␣
  • N₂ 個のダッシュ + ┐。ここで N₁ + N₂ + len(title) + 2 = 126 です。パディングは 次のように配分します：N₁ = floor((126 − len(title) − 2) / 2)、 N₂ = 126 − len(title) − 2 − N₁。N₁ と N₂ の差は最大 1 です。
• 本文：各事実につき、│ <内側のコンテンツを 124 文字分にパディング> │ を 1 行出力します。 各事実の行には ✔ <13 文字にパディングしたキー> <値> の形式を使用します（先頭にスペース 2 つ、記号、右側を 13 文字分までスペースで埋めたキー、スペース 2 つ、値）。
• グループ間の空行：論理グループ間（例：ステップ 1 の Identity / Model / Videos）には │ <スペース 124 個> │ を出力し、 ユーザーがボックスをひと目で確認できるようにします。
• 下罫線：└ + ダッシュ 126 個 + ┘ — タイトルのない実線の罫線です。

各ステップのボックス上部に使用する標準ステップタイトル：

┌─────────────────────────────────────────────────────── Deploy targets ───────────────────────────────────────────────────────┐
┌─────────────────────────────────────────────────── Pipeline configuration ───────────────────────────────────────────────────┐
┌───────────────────────────────────────────────────────── Container ──────────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────────── Apply configuration ─────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────── Perception Application — Plan ───────────────────────────────────────────────┐
┌────────────────────────────────────────────── Perception Application — Results ──────────────────────────────────────────────┐

ステップごとのコンテンツルール（どの行をどのボックスに含めるか、モードに応じた行の非表示、apply-config のセクション分けされたレイアウト、ステップ 5 の PLAN の後に RESULT を示すパターン、ステップ 3 の docker run 合成要件）については、 references/deploy-vss-detection-tracking-2d.md の「Step N box content rule」を参照してください。該当するステップを表示する際に確認します。

クイックトリガー（覚えやすい定型句）

フレーズ	フロー
deploy rtvicv warehouse 2d with 4 streams and display	DEPLOY
run smartcity gdino on gpu 1	DEPLOY
stop the perception container	TEARDOWN（デプロイのドキュメント）
rtvi-cv healthcheck failing	DEBUG（デプロイのドキュメント + トラブルシューティング）
add a stream to rtvi-cv	API USAGE
is rtvi-cv ready on localhost:9000	API USAGE
get rtvi-cv metrics	API USAGE
generate text embeddings via rtvi-cv	API USAGE

bump:1