vss-deploy-video-embedding

VSS Video Embedding（RT-Embed）

次のような場合に、このスキルを使用します。

• Docker Compose ファイルから VSS Video Embedding マイクロサービスをデプロイする。
• Cosmos-Embed1-448p モデルを使用して、テキストまたは動画の埋め込みを生成する。
• アップロードしたファイル、HTTP/S3/file/data URL、またはライブ RTSP ストリームを埋め込む。
• Redis、Kafka、OpenTelemetry とともに、VSS デプロイにサービスを組み込む。
• 起動準備、モデルのダウンロード、GPU、またはストリーム再接続に関する問題をトリアージする。

トリガーフレーズ： vss-deploy-video-embedding、RT-Embed、rtvi-embed、video embedding service、Cosmos-Embed1、embed live stream、embed video file、generate video embeddings、text embedding for video search。

サービスの概要

• VSS 3.2 GA スキル： vss-deploy-video-embedding。
• レガシー 3.1 名称： RT-Embed。
• Compose サービス： rtvi-embed。
• コンテナー名： vss-rtvi-embed。
• イメージ： nvcr.io/nvidia/vss-core/vss-rt-embed（RTVI_EMBED_IMAGE で上書きできます）。
• デフォルトのタグ： 3.2.0（RTVI_EMBED_TAG で上書きできます）。
• プロファイル： bp_developer_search_2d。
• コンテナーポート： 8000（ホスト側は ${RTVI_EMBED_PORT}）。
• デフォルトモデル： nvidia/Cosmos-Embed1-448p の cosmos-embed1-448p。
• ヘルスエンドポイント： GET /v1/ready。
• ヘルスチェックの起動猶予時間： 初回起動時は 1200s（20 分）。

前提条件

サービスを起動する前に、以下を確認してください。

1. NVIDIA ドライバーと NVIDIA Container Toolkit がインストールされ、デフォルトのランタイムが nvidia に設定されていること。
2. Docker Engine と Docker Compose プラグインが、${VAR:+value} によるボリュームの条件付き置換に対応したバージョンであること。
3. 有効な NGC API キーを使用して、$oauthtoken で docker login nvcr.io が完了していること。
4. ホスト環境で、最低限 RTVI_EMBED_PORT、VSS_DATA_DIR、NGC_API_KEY が設定されていること。Cosmos-Embed1 の重みのダウンロード中に Hugging Face の 429 レート制限エラーを避けるには、任意で HF_TOKEN も設定します。
5. 永続キャッシュ rtvi-hf-cache、rtvi-ngc-model-cache、rtvi-triton-model-repo 用のディスク空き容量があること（数 GB）。

前提条件の全リストについては references/deploy-vss-deploy-video-embedding.md を、変数の一覧については references/environment.md を参照してください。

デプロイ

スタンドアロン RT-Embed の場合は、サービスディレクトリで作業します。

cd "{{repo_root}}/deploy/docker/services/rtvi/rtvi-embed"

このスタンドアロンデプロイでは、/vss-deploy-profile や scripts/dev-profile.sh を使用しないでください。

エージェント主導の検証では、sudo が対話形式で入力を求めないようにしてください。所有権の変更や Docker の操作に特権が必要な場合は、references/deploy-vss-deploy-video-embedding.md と references/troubleshooting.md に記載された非対話型のガードを使用してください。通常の docker を優先し、それが使えない場合は sudo -n docker を使用します。sudo -n が失敗した場合は、対話型の sudo を再試行したり権限を緩めたりせず、ホスト管理者が実行するための正確な手動コマンドを提示して停止してください。

docker compose up の前に、スタンドアロンに必要な最小限の環境を設定します。sudo -n chown が失敗した場合は、docker compose up を実行する前に停止し、表示されたコマンドをホスト管理者に実行してもらってください。

export RTVI_EMBED_PORT=8017
export VSS_DATA_DIR="${VSS_DATA_DIR:-$(pwd)/.standalone-data}"
export NGC_API_KEY="<your-ngc-api-key>"
export HOST_IP="$(hostname -I | awk '{print $1}')"
export HF_TOKEN="${HF_TOKEN:-}"  # optional, but recommended to avoid HF 429s
export RTVI_EMBED_KAFKA_ENABLED=false
export ENABLE_REDIS_ERROR_MESSAGES=false
# Prepare VST clip-storage host dir; use `sudo -n` for ownership fixes.
CLIP_STORAGE_DIR="${VSS_DATA_DIR}/data_log/vst/clip_storage"
mkdir -p "$CLIP_STORAGE_DIR"
if ! sudo -n chown -R 1001:1001 "$CLIP_STORAGE_DIR"; then
  echo "ERROR: passwordless sudo is unavailable for host-path ownership." >&2
  echo "Ask the host owner to run: sudo chown -R 1001:1001 \"$CLIP_STORAGE_DIR\"" >&2
  echo "Do not work around this with chmod 777 or world-writable permissions." >&2
  return 1 2>/dev/null || exit 1
fi

これにより、VSS_DATA_DIR が未設定の場合にファイルシステムのルートから /data_log/vst/clip_storage をマウントするのを防ぎ、スタンドアロンモードで Kafka／Redis の接続先が存在しないために起動が停止するのを防ぎます。

# Bring up the service under the required Compose profile.
docker compose -f rtvi-embed-docker-compose.yml \
  --profile bp_developer_search_2d up -d rtvi-embed

Docker の実行に昇格した権限が必要な場合は、sudo -n docker compose ... を使用し、sudo -n がパスワードを要求した場合は速やかに失敗として終了してください。

# Watch logs while the model downloads and Triton repo builds.
docker compose -f rtvi-embed-docker-compose.yml logs -f rtvi-embed

初回起動では、Cosmos-Embed1 のダウンロードと Triton モデルリポジトリのビルドに 20 分かかることがあります。初回起動時に start_period: 1200s のヘルスチェックを短縮しないでください。短縮すると、コンテナーはウォームアップ中にもかかわらず異常と判定されます。

確認

BASE_URL="http://localhost:${RTVI_EMBED_PORT}"

curl -fsS "$BASE_URL/v1/ready"               # 200 when warm.
curl -fsS "$BASE_URL/v1/ready?detailed=true" # Component-level status.
curl -fsS "$BASE_URL/v1/version"
MODELS_JSON=$(curl -fsS "$BASE_URL/v1/models")
echo "$MODELS_JSON"                          # Confirms cosmos-embed1-448p is loaded.

MODEL_ID="$(echo "$MODELS_JSON" | jq -r '.data[0].id // empty')"
test -n "$MODEL_ID" || { echo "ERROR: /v1/models has no model id — wait until /v1/ready is 200" >&2; exit 1; }

以下の API 操作の各セクションでは、このブロックで設定した $BASE_URL と $MODEL_ID を使用します。

よく使う操作

アップロードしたファイルから動画の埋め込みを生成する

FILE_ID=$(curl -fsS -X POST "$BASE_URL/v1/files" \
  -F purpose=vision \
  -F media_type=video \
  -F file=@/path/to/clip.mp4 | jq -r .id)

curl -fsS -X POST "$BASE_URL/v1/generate_video_embeddings" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 60,
    \"chunk_overlap_duration\": 10
  }"

テキストの埋め込みを生成する（テキストから動画を検索する場合）

curl -fsS -X POST "$BASE_URL/v1/generate_text_embeddings" \
  -H "Content-Type: application/json" \
  -d "{\"text_input\":\"a forklift moving pallets\",\"model\":\"${MODEL_ID}\"}"

ライブ RTSP ストリームを埋め込む

ライブストリームには、stream: true と chunk_duration > 0 が必須です。同期呼び出しでは 400 BadParameters: "Only streaming output is supported for live-streams" が返されます。また、streams/add が返す chunk_duration: 0 はプレースホルダーです。埋め込みリクエストで上書きしないと、400 BadParameter: "chunk_duration must be greater than 0" が返されます。

POST /v1/streams/add は liveStreamUrl による重複排除を行いません。同じ URL を 2 回送信すると、異なる stream_id が 2 つ発行されます。孤立したエントリを作らないよう、追加する前に GET /v1/streams/get-stream-info を呼び出し、その URL の登録がすでに存在する場合は再利用してください。

STREAM_ID=$(curl -fsS -X POST "$BASE_URL/v1/streams/add" \
  -H "Content-Type: application/json" \
  -d '{"streams":[{"liveStreamUrl":"rtsp://host:port/live/video","description":"camera-001"}]}' \
  | jq -r '.results[0].id')

curl -N -X POST "$BASE_URL/v1/generate_video_embeddings" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d "{
    \"id\": \"$STREAM_ID\",
    \"model\": \"$MODEL_ID\",
    \"stream\": true,
    \"chunk_duration\": 10,
    \"chunk_overlap_duration\": 2
  }"

# List registered live streams (use this to recover stream_ids across sessions).
curl -fsS "$BASE_URL/v1/streams/get-stream-info"

# Stop embedding for the stream when done (terminates SSE with data: [DONE]).
curl -fsS -X DELETE "$BASE_URL/v1/generate_video_embeddings/$STREAM_ID"

エンドポイントの全一覧、SSE ストリーミング、単一ストリームのコントロールプレーンパターンについては、references/rest-api.md を参照してください。

ログ、メトリクス、ステータス

docker compose -f rtvi-embed-docker-compose.yml ps
docker compose -f rtvi-embed-docker-compose.yml logs -f rtvi-embed
docker stats vss-rtvi-embed

curl -fsS "$BASE_URL/v1/metrics"          # Prometheus.
curl -fsS "$BASE_URL/v1/assets/stats"     # Asset storage counts and TTL.

RTVI_EMBED_LOG_DIR がホストディレクトリにバインドされている場合、ログファイルはホスト上の /opt/nvidia/rtvi/log/rtvi/ からも利用できます。

インテグレーションサーフェス

• 入力： :${RTVI_EMBED_PORT} の REST API（POST /v1/files、POST /v1/generate_text_embeddings、POST /v1/generate_video_embeddings、ライブストリームの制御エンドポイント）。
• 出力： 同期 REST レスポンス、チャンク化された動画埋め込み用のオプションの SSE、Kafka が有効な場合に RTVI_EMBED_KAFKA_TOPIC（コンテナー内では KAFKA_TOPIC）および RTVI_EMBED_ERROR_MESSAGE_TOPIC（コンテナー内では ERROR_MESSAGE_TOPIC）で指定されたトピックに送信されるオプションの Kafka メッセージ（ホスト側の RTVI_EMBED_KAFKA_ENABLED=true は Compose によりコンテナー内の KAFKA_ENABLED にマッピングされます）。
• オプションの接続先： Redis（ENABLE_REDIS_ERROR_MESSAGES=true）、Kafka（ホスト側の RTVI_EMBED_KAFKA_ENABLED=true → コンテナー内の KAFKA_ENABLED）、OpenTelemetry コレクター（ホスト側の RTVI_EMBED_ENABLE_OTEL_MONITORING=true → コンテナー内の ENABLE_OTEL_MONITORING）。

インテグレーション契約の全容については、references/integrate-vss-deploy-video-embedding.md を参照してください。

エラー処理

API の失敗時には、code フィールドと message フィールドを含む JSON が返されます。

{
  "code": "BadParameter",
  "message": "chunk_duration must be greater than 0"
}

Pydantic / OpenAPI の検証失敗時には HTTP 422 が返され、code: "InvalidParameters" とフィールド単位の message が含まれます。

コード	意味	よくある原因
400	不正なリクエスト	text_input がない、未知の file_id / stream_id / model、ライブストリームが stream: true なしで呼び出された、ライブストリームの埋め込みリクエストで chunk_duration: 0 が指定された、chunk_overlap_duration >= chunk_duration
401	認証されていません	デプロイ環境で認証が必須の場合に Authorization: Bearer <token> がない、または無効
403	禁止されています	file:// URL が無効（FILE_URL_ALLOWED_DIRS が未設定）、または解決されたパスが許可リスト外（code: "Forbidden"）
409	競合	ファイル使用中に DELETE /v1/files/{file_id} を実行した（ResourceInUse）、別のクライアントが同じライブストリームにすでに接続している（Conflict）
413	ペイロードが大きすぎます	アップロードされたファイルまたはデコードされた data: URI がサーバーのサイズ制限を超えている
422	処理できないエンティティ	スキーマ検証の失敗 — UUID の形式が不正、multipart フィールドの型が不正、列挙値が無効、サポート対象のスキームで URL 形式が無効
429	レート制限超過	リクエストレートが上限を超過 — 指数バックオフで再試行してください
500	内部サーバーエラー	予期しない推論または I/O の失敗 — docker compose -f rtvi-embed-docker-compose.yml logs -f rtvi-embed を確認してください
503	サービスを利用できません	/v1/ready がまだ起動中（モデルのダウンロード / Triton リポジトリのビルド中）、埋め込みエンドポイントが別のファイルまたはテキストクエリで使用中、ライブストリーム数が上限に達した、推論中に CUDA OOM が発生した

初回起動時に /v1/ready が返す 503 は、Cosmos-Embed1 のダウンロードと Triton モデルリポジトリのビルドが完了するまで想定どおりです（最大約 20 分）。ヘルスチェックの start_period: 1200s が経過するまでは、アプリケーションエラーとして扱わないでください。

埋め込みエンドポイントが "Server is busy processing another file or text" または "Server is busy processing another file / live-stream." というメッセージとともに 503 を返す場合、サービスは一度に 1 件の同期埋め込みジョブを処理します — バックオフして再試行するか、インスタンス間で作業を分割してください。

エンドポイント固有の制約（ライブストリームの SSE 要件、URL スキーム、レスポンススキーマ）については、references/rest-api.md を参照してください。Compose の起動、キャッシュ、権限に関する失敗については、references/troubleshooting.md を参照してください。

トラブルシューティング

よくある失敗パターンと解決方法については、references/troubleshooting.md を参照してください。よくある問題：

• /v1/ready が 503 のまま → NGC_API_KEY の設定漏れ、初回起動時のモデルダウンロード中に Hugging Face が 429 レート制限を返していないか（回避するには HF_TOKEN を設定）、または該当するフラグが有効な場合に Redis / Kafka の接続先に到達できるかを確認してください。
• 最初の 20 分間にヘルスチェックが unhealthy に変わる → start_period: 1200s に戻してください。
• バインドマウントされたキャッシュディレクトリで権限エラーが発生する → ホスト上のパスに対して sudo -n chown -R 1001:1001 を実行してください。パスワードなしの sudo が使用できない場合は、ホストの所有者に表示されたコマンドの実行を依頼してください（chmod 777 は使用しないでください）。
• デプロイ中に sudo がパスワードを要求する → sudo -n を使い、すぐに失敗させてください。references/troubleshooting.md を参照してください。エージェントのセッションで対話形式の sudo を再試行しないでください。

アップグレードとロールバック

RTVI_EMBED_IMAGE / RTVI_EMBED_TAG を固定し、イメージを取得して、--profile bp_developer_search_2d で再作成した後、切り替え前に /v1/ready を待ちます。名前付きボリュームはイメージの切り替え後も保持されます。

手順の全容：アップグレードとロールバック。

削除

docker compose -f rtvi-embed-docker-compose.yml down でスタンドアロンのスタックを停止します。名前付きモデルキャッシュを削除する場合に限り、down -v を使用してください。

手順の全容とキャッシュに関する注意事項：削除。

参照資料

ファイル	参照するタイミング
references/README.md	すべての参照ファイルの目次です。
references/deploy-vss-deploy-video-embedding.md	Vision Agent のデプロイ構築に関するリファレンスです。イメージ、GPU、ストレージ、起動、前提条件、既知の問題を扱います。
references/integrate-vss-deploy-video-embedding.md	Vision Agent の統合構築に関するリファレンスです。ピア、入力／出力、環境変数、ネットワーク、Compose の例を扱います。
references/rest-api.md	ファイルのアップロード、動画／テキストの埋め込み、ライブストリーム、ヘルス／メトリクスに関する、実行例付きの curl を含む REST エンドポイントの完全な一覧です。
references/environment.md	ホストからコンテナーへの名称変更や、シークレットに関わる環境変数を含む、環境変数の完全な一覧です。
references/troubleshooting.md	起動、モデル／キャッシュ、ランタイム、可観測性に関する問題の運用診断です。