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 レジストリ認証情報。
• 単独構成の compose コピー用に、curl、jq、および書き込み可能な作業ディレクトリ。

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

• $BASE_URL からアクセスできる、実行中の RT-VLM サービス。
• サービスの設定に応じて、$RTVI_VLM_API_KEY または $NGC_CLI_API_KEY 内のベアラートークン。

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

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

手順

以下のルーティング表とステップごとのワークフローに従ってください。workflow、quick start、または flow で終わる各セクションは、上から順に実行してください。詳細なリファレンスは 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、.env ファイルを Git やログに含めないでください。認証情報の値をエコーしたり、最終回答に含めたりしないでください。
• Docker グループへのアクセスと sudo は、実質的に root レベルの権限です。デプロイのリファレンスにある非対話型の sudo -n ガードを使用してください。パスワードなしで sudo を実行できない場合は停止し、ホスト所有者に対応を依頼してください。

トラブルシューティング

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

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

RT-VLM は NVIDIA のリアルタイムビジョン言語マイクロサービスです。動画（ファイルまたは RTSP）をデコードしてチャンクに分割し、VLM（cosmos-reason1、cosmos-reason2、または OpenAI 互換モデル）で処理し、高密度キャプションを SSE/HTTP 経由でストリーミングし、 キャプション、インシデントアラート、エラーを Kafka に送信します。このスキルを使用すると、 VSS プロファイル全体がすでに実行されていない場合に、RT-VLM サービスを単独でデプロイしてから、 キャプション生成、ファイルアップロード、ライブストリームの管理、ヘルスチェック、NIM 互換の チャット補完、Prometheus メトリクスの取得に /v1/... API を呼び出せます。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 .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 .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 修正を適用してください。

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

ホスト環境変数	必要となる条件	用途
NGC_CLI_API_KEY	スタンドアロンのデプロイパス	NGC レジストリからのイメージの pull、および 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-reason2、リモート／同階層のエンドポイントには openai-compat を使用
RTVI_VLM_MODEL_PATH	ローカルのセルフホストモデル	ソースに基づく Cosmos Reason 2 のパス：ngc:nim/nvidia/cosmos-reason2-8b:hf-1208
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 のようなエイリアスはバックエンドのセレクターであり、リクエストのモデル ID ではありません。
• RTSP のライフサイクルには POST /v1/streams/add、GET /v1/streams/get-stream-info、DELETE /v1/streams/delete/{stream_id} を使用します。results[0].id からストリーム ID を解析してください。
• OpenAI 互換のテキストおよびマルチモーダル呼び出しには POST /v1/chat/completions を使用します。現在の 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 サンプルストリームガード を実行してください。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 を確認してください。