vss-deploy-dense-captioning

目的

RT-VLM 高密度キャプション生成マイクロサービスを単独で起動し、公開されているすべてのエンドポイント（ファイルアップロード、generate_captions、ストリームの追加／削除、chat-completions、Kafka トピック）を試します。

前提条件

RT-VLM を単独でデプロイする場合：

• Docker、Docker Compose、NVIDIA Container Toolkit、および認識可能な GPU。
• docker login nvcr.io、イメージのプル、ローカルでの NGC モデル／アーティファクトのダウンロードに使用する、$NGC_CLI_API_KEY の NGC レジストリ認証情報。
• curl、jq、および単独構成のコピー先として書き込み可能な任意の作業ディレクトリ。

既存のサービスに対して API を呼び出す場合：

• $BASE_URL から到達可能な、稼働中の RT-VLM サービス。
• サービスの設定に応じて、$RTVI_VLM_API_KEY または $NGC_CLI_API_KEY のベアラートークン。

VSS プロファイル全体をデプロイする場合：

• ../vss-deploy-profile/SKILL.md を使用してください。このスキルでは VSS プロファイル全体はデプロイしません。

手順

以下のルーティングテーブルとステップごとのワークフローに従ってください。ワークフロー、クイックスタート、またはフローで終わる各セクションは、上から順に実行することを想定しています。詳細なリファレンス資料は references/ にあります。将来の改訂で具体的なヘルパーが指定されない限り、記載されているワークフローを直接実行してください。

例

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

制限事項

• このスキルを使ってデプロイした単独の RT-VLM サービス、または呼び出し元から到達可能な既存の RT-VLM サービスが必要です。
• NGC ホストモデルと NIM には、レート制限、GPU メモリ要件、ライセンス制限が適用される場合があります。
• 同時実行数、GPU メモリ、ストレージの上限は、ホストのハードウェアとプロファイルの compose ファイルによって異なります。
• NGC_CLI_API_KEY、RTVI_VLM_API_KEY、rtvi-vlm.env ファイルを Git やログに含めないでください。認証情報の値を表示したり、最終回答に含めたりしないでください。
• Docker グループへのアクセスと sudo は、実質的に root レベルの権限です。デプロイのリファレンスでは対話なしの sudo -n ガードを使用し、パスワードなしの sudo が利用できない場合は、ホスト所有者の対応を求めて作業を中止してください。

トラブルシューティング

• エラー：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 を解放してください。

RT-VLM 高密度キャプション生成のデプロイと使用（VSS 3.2）

RT-VLM は NVIDIA のリアルタイム視覚言語マイクロサービスです。動画（ファイルまたは RTSP）をデコードし、チャンクに分割して、VLM（cosmos-reason1、cosmos-reason2、cosmos-reason3、または OpenAI 互換モデル）を実行し、高密度キャプションを SSE/HTTP 経由でストリーミング配信するとともに、キャプション、インシデントアラート、エラーを Kafka に配信します。VSS プロファイル全体がまだ稼働していない場合は、このスキルを使って RT-VLM サービスを単独でデプロイし、その後 /v1/... API を呼び出して、キャプション生成、ファイルアップロード、ライブストリーム管理、ヘルスチェック、NIM 互換のチャット補完、または Prometheus メトリクスを利用してください。API リファレンス： https://docs.nvidia.com/vss/latest/real-time-vlm-api.html.

デプロイルーティング

ユーザーが VSS プロファイル全体のデプロイを依頼した場合は、 ../vss-deploy-profile/SKILL.md を使用してください。このスキルが、プロファイルのルーティング、generated.env、resolved.yml、複数サービスのサイジング、フルスタックのデプロイ／ティアダウンを担当します。

ユーザーがスタンドアロンの RT-VLM による高密度キャプション生成を依頼した場合、または VSS プロファイルがまだ実行されていない場合は、API を呼び出す前に references/deploy-rt-vlm-service.md に記載されたスタンドアロン RT-VLM の手順を使用してください。これは vss-deploy-profile と同じ Compose 中心のパターンに従います。コンテキストを収集し、事前チェックを実行し、ローカルコピーを使って作業し、docker compose config でドライランを行い、レビューしてからデプロイし、ヘルスチェックを待ちます。

スタンドアロンのデプロイ手順

必ず次の手順に従ってください。ドライランを省略してはいけません。

# 1. Copy deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml
#    into any writable standalone working directory.
# 2. Derive RTVI_VLM_IMAGE_TAG from that compose copy.
# 3. Strip the standalone-only dangling depends_on block from the copy.
# 4. Create a gitignored rtvi-vlm.env with the required RT-VLM values.
# 5. Prepare host bind paths such as $VSS_DATA_DIR/data_log/vst/clip_storage.
#    Use `sudo -n` for ownership fixes; if passwordless sudo is unavailable,
#    stop and ask the host owner to run the printed command manually.
# 6. docker compose --env-file rtvi-vlm.env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. docker pull the exact RT-VLM image tag.
# 8. docker compose ... up -d rtvi-vlm, wait for ready, then smoke test.

pull または up の前に事前チェックを実行してください。失敗した場合は、RT-VLM 自体のデバッグに進む前に、ここで停止して問題を修正してください。

nvidia-smi --query-gpu=index,name --format=csv,noheader
nvidia-container-cli info
docker compose version
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

スタンドアロンの単一ファイルデプロイでは、deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml をそのまま実行しないでください。このファイルには、フル VSS／met-blueprints Compose プロジェクトでのみ定義される、関連する VLM／NIM サービスへの depends_on 参照が含まれています。スタンドアロンのリファレンスでは、Compose ファイルのコピー方法、現在のイメージタグの取得方法、depends_on ブロックの削除方法、up の前に結果を検証する方法を説明しています。

エージェント主導で検証する場合、sudo が対話的にプロンプトを表示することがないようにしてください。権限が必要な所有権変更や Docker 操作の前に、 references/deploy-rt-vlm-service.md に記載された非対話型ガードを使用してください。まず通常の docker を使用し、それが使えない場合は sudo -n docker を使用してください。sudo -n が失敗した場合は、対話型の sudo で再試行したり、権限を弱めたりせず、ホストの所有者が実行するための正確な手動コマンドを提示して停止してください。

Docker 28 以降で docker pull が containerd スナップショッター／展開エラーにより失敗した場合は、再試行する前にスタンドアロンのリファレンスに記載された /etc/docker/daemon.json の containerd-snapshotter=false の修正を適用してください。

スタンドアロンの rtvi-vlm.env に必要な最小限の値：

ホスト環境変数	必要な条件	用途
NGC_CLI_API_KEY	スタンドアロンのデプロイパス	NGC レジストリからのイメージ取得、および NGC からのモデル／アーティファクトのダウンロード
RTVI_VLM_API_KEY または NGC_CLI_API_KEY	認証が必要な API 呼び出し	サービス起動後の RT-VLM ベアラー認証
RTVI_VLM_PORT	常に必要	コンテナの 8000 にマッピングするホスト API ポート
HOST_IP	常に必要	Kafka のブートストラップホスト（${HOST_IP}:9092）
VSS_DATA_DIR	常に必要	必須のクリップストレージ用バインドマウント
RTVI_VLM_MODEL_TO_USE	スタンドアロンでは常に必要	バックエンドの選択子。デフォルトのローカルモデルには cosmos-reason3、リモート／関連エンドポイントには openai-compat を使用
RTVI_VLM_MODEL_PATH	ローカルのセルフホストモデル	ソースで指定された Cosmos Reason3 Nano BF16 のパス：ngc:nim/nvidia/cosmos3-nano-reasoner:bf16-final
RTVI_VLM_ENDPOINT	RTVI_VLM_MODEL_TO_USE=openai-compat の場合	リモート／関連する OpenAI 互換 VLM エンドポイント
VLM_NAME	RTVI_VLM_MODEL_TO_USE=openai-compat の場合	そのエンドポイントが公開するモデル／デプロイ名

セットアップ

export BASE_URL="http://localhost:${RTVI_VLM_PORT:-8018}"  # host-side RT-VLM port
export API_KEY="${NGC_CLI_API_KEY:-${RTVI_VLM_API_KEY:-}}" # bearer token used by host-side curl commands
: "${API_KEY:?Set NGC_CLI_API_KEY or RTVI_VLM_API_KEY before calling authenticated endpoints}"

以下の各リクエストでは Authorization: Bearer $API_KEY を使用します。ヘルスエンドポイント（/v1/health/*、/v1/ready、/v1/live、/v1/startup）は通常、認証なしで利用できます。

使用前のスモークテスト：

curl -fsS "$BASE_URL/v1/health/ready"
MODEL_ID="$(curl -fsS "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id // .id')"
curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

RTSP サンプルストリームのガード

タスクまたは評価で RTSP_SAMPLE_URL が指定されている場合、その環境変数を必須入力として扱ってください。ストリームのプローブや登録を行う前に、変数が設定され、空でないことを確認してください。設定されていない場合は、明確なエラーメッセージを出して停止してください。呼び出し元が指定したものとは異なるストリームを検証することになるため、NvStreamer、VIOS、サンプルデータバンドル、その他の代替手段から代わりの値を導出してはいけません。

: "${RTSP_SAMPLE_URL:?Set RTSP_SAMPLE_URL to a reachable RTSP sample stream before RTSP validation}"
case "$RTSP_SAMPLE_URL" in
  rtsp://*) ;;
  *) echo "RTSP_SAMPLE_URL must be an rtsp:// URL, got: $RTSP_SAMPLE_URL" >&2; exit 1 ;;
esac

if command -v ffprobe >/dev/null 2>&1; then
  ffprobe -v error -rtsp_transport tcp \
    -select_streams v:0 -show_entries stream=codec_type \
    -of csv=p=0 "$RTSP_SAMPLE_URL" | grep -qx video
elif command -v gst-discoverer-1.0 >/dev/null 2>&1; then
  gst-discoverer-1.0 "$RTSP_SAMPLE_URL" | grep -qi 'video'
else
  echo "Install ffprobe or gst-discoverer-1.0 before RTSP validation." >&2
  exit 1
fi

クイックスタート — ローカル動画から高密度キャプションを生成

# 1. Upload the video, capture its file id
FILE_ID=$(curl -fsS -X POST "$BASE_URL/v1/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/warehouse.mp4" \
  -F "purpose=vision" \
  -F "media_type=video" | jq -r '.id')

# 2. Generate captions + alerts (SSE stream of chunked responses)
curl -N -X POST "$BASE_URL/v1/generate_captions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"prompt\": \"Write a concise dense caption for each 10-second segment of this warehouse video.\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 10,
    \"stream\": true
  }"

API サーフェス

省略可能なエンドポイントを呼び出す前に、最新の OpenAPI を信頼できる情報源として確認してください。

curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

VSS 3.2 の主要なパスは次のとおりです。

• POST /v1/files は、マルチパート形式でメディアをアップロードします。返されたファイルの id をキャプション生成に渡し、完了後にファイルを削除してください。
• POST /v1/generate_captions は、ファイルまたはストリームのキャプション生成に使用します。GET /v1/models が返す正確なモデル ID を使用してください。cosmos-reason2 や cosmos-reason3 などのエイリアスはバックエンドのセレクターであり、リクエストに指定するモデル ID ではありません。
• POST /v1/streams/add、GET /v1/streams/get-stream-info、DELETE /v1/streams/delete/{stream_id} は、RTSP のライフサイクルに使用します。results[0].id からストリーム ID を解析してください。
• POST /v1/chat/completions は、OpenAI 互換のテキストおよびマルチモーダル呼び出しに使用します。現在の 26.05 ビルドでは、テキストのみの /v1/completions に対して HTTP 400 が返されます。従来の動作を検証する際は、これを想定された動作として扱ってください。
• GET /v1/health/ready、/v1/models、/v1/assets/stats、/v1/metrics は、サービスのプローブに使用します。OpenAPI に記載されていない限り、/v1/license が存在すると想定しないでください。

詳細なエンドポイントスキーマ、レスポンス形式、CV スタイルの単一ストリームエンドポイント、26.05 の互換性に関する注意事項は、references/api-surface-26.05.md に記載されています。

よくあるワークフロー

• 保存済みファイルのキャプション生成：POST /v1/files でアップロードし、返されたファイル ID を指定して /v1/generate_captions を呼び出します。SSE を使用する場合は stream=true を指定し、ストレージを解放するためにその後ファイルを削除してください。
• RTSP ライブキャプション生成：呼び出し元から RTSP_SAMPLE_URL が提供された場合は、その正確な URL を使用し、登録前に RTSP Sample Stream Guard を実行してください。RTSP_SAMPLE_URL が空の場合は、NvStreamer または VIOS から代替ストリームを導出せず、即座に失敗させてください。登録前に実際のビデオストリームまたは caps エントリーが存在することを確認します。ストリームを追加してキャプションを生成した後、登録を解除してください。
• アラートプロンプト：決定論的な Anomaly Detected: Yes/No の行を含めてください。Kafka へのパブリッシュはサーバー側の設定で行われ、HTTP レスポンスに追加されます。詳細は references/kafka-workflows.md に記載されています。
• Kafka の検証：トピック名については、稼働中の vss-rtvi-vlm 環境を信頼してください。完全な VSS アラート・リアルタイムプロファイルでは、CLI による確認と最終的なインシデントコンシューマーのコマンドに、既存の VSS Kafka コンテナー mdx-kafka を使用してください。スタンドアロンで検証する場合は、${HOST_IP}:9092 をアドバタイズするブローカーを使用してください。事前に存在するブローカーを、ユーザーの確認なしに停止または置き換えないでください。

エラーリファレンス

よくある原因：リクエスト形式またはモデル ID が無効な場合は 400、Bearer トークンがない、または誤っている場合は 401/403、削除済みのファイルやストリーム、またはサポート対象外のエンドポイントの場合は 404、アップロードサイズが大きすぎる場合は 413、スキーマ検証エラーの場合は 422、同時実行数が多すぎる場合は 429、推論またはランタイムの障害の場合は 500、起動処理中は 503 です。サービス側の障害を確認するには、docker logs vss-rtvi-vlm を調べてください。