vss-summarize-video

手順

以下のルーティング表とステップごとのワークフローに従ってください。ワークフロー、クイックスタート、またはフローで終わる各セクションは、上から順に実行することを想定しています。詳細なリファレンス資料は references/ にあります。

例

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

VLM NIM または動画要約マイクロサービスを直接呼び出してください。 curl コマンドは必ず自分で実行してください。ユーザーに実行を指示しないでください。

主要な動画ワークフローのクエリタイプ：「この動画を要約してください。」 動画の直接要約 API およびサービス運用に関するリクエストには、以下のリファレンスに基づくセクションで対応します。

目的

録画された単一の動画クリップについて、洗練されたナラティブ形式の要約を 1 つ作成します。LVS マイクロサービスの経路に到達できる場合は、タイムスタンプ付きのイベントも含めます。

このスキルは、次の用途には使用しないでください。

• ライブ RTSP キャプション生成 — vss-deploy-dense-captioning を使用してください。
• インシデントやアラートの時間帯を含むレポート生成 — Mode B の vss-generate-video-report を使用してください。
• アーカイブ全体のセマンティック検索 — vss-search-archive を使用してください。

前提条件

• VSS の lvs プロファイルが $HOST_IP（ポート 38111）で実行中、またはフォールバックとして到達可能な VLM／RT-VLM エンドポイントがあること。これらは vss-deploy-profile スキルで起動できます。
• エージェントホストから両方のエンドポイントにネットワーク経由で到達できること。また、VIOS からのクリップ URL を 選択したバックエンドで取得できること。
• エージェントホストで jq と curl を利用できること。

制限事項

• 直接 VLM にフォールバックする場合、固定のプロンプトを 1 つだけ使用し、シナリオやイベントを指定できません。そのため、出力品質は LVS 経路より低くなります。
• リモート VLM エンドポイントからは、通常 localhost やプライベートなクリップ URL に到達できません。
• リクエストごとにバックエンド呼び出しは 1 回のみです。並列でのヘッジや複数回の要約生成は行いません。

トラブルシューティング

症状	原因	対処方法
/v1/ready が繰り返し 503 を返す	LVS サービスの起動処理がまだ完了していません	セットアップに示すとおり、最大約 30 秒間再試行してください。それでも 200 が返らない場合は、サービスがデプロイされていない可能性があります
video_summary と events が空	クリップに、指定したイベントが含まれていません	より広い scenario を指定するか、別の events で再実行してください
VLM が `` までの内容をすべて削除してください
curl /v1/ready の標準出力が空	サービスが正常に、本文なしで 200 を返しています	-o /dev/null -w '%{http_code}' を使用して、必ず HTTP ステータスを確認してください。本文は確認しないでください

詳しい診断については、references/video-summarization-debugging.md を参照してください。

参照マップ

以下の参照資料は、ユーザーが該当する詳細を求めた場合、または 以下の基本ワークフローで動画要約についてより詳しい情報が必要な場合にのみ使用してください。

• 動画要約 API の詳細：/v1/summarize、/summarize、/v1/generate_captions、 /v1/stream_summarize、ヘルスプローブ、/models、/recommended_config、 /metrics、リクエストフィールド、レスポンス形式、API の注意点については references/video-summarization-api.md を参照してください。
• 動画要約サービスの設定と運用： VSS の lvs プロファイル、ポート、必須の環境変数、ログ、ステータス、ドライラン、 停止、モデル／バックエンドの切り替え、Elasticsearch／Neo4j／ArangoDB バックエンドの 選択、サービスレベルのトラブルシューティングについては references/video-summarization-deployment.md を参照してください。
• 動画要約の拡張運用リファレンス： references/video-summarization-environment-variables.md、 references/video-summarization-debugging.md、および assets/video-summarization.env.example を参照してください。

以下のステップ 2 の LVS またはフォールバック VLM の例でカバーされていないリクエストフィールド、レスポンス形式、エンドポイントが必要な場合、または動画要約 API への直接的なリクエストに対応する場合にのみ、video-summarization-api.md を読み込んでください。デプロイ、設定、サービス運用については、video-summarization-deployment.md のみを読み込んでください。

動画要約 API とサービス運用に関するリクエスト

ユーザーが動画要約エンドポイントへの直接の呼び出しやデバッグを求めた場合は、エンドツーエンドの動画要約ワークフローを実行せず、 references/video-summarization-api.md を参照して回答してください。例：動画要約モデルの一覧表示、準備状態の確認、推奨チャンク設定の取得、メトリクスの確認、422 レスポンスの説明、/v1/summarize リクエストボディの作成。

ユーザーが動画要約サービスの設定、デプロイ、再起動、停止、またはトラブルシューティングを求めた場合は、完全な VSS プロファイルのデプロイには vss-deploy-profile スキルを優先して使用し、動画要約サービス固有の詳細については references/video-summarization-deployment.md を参照してください。

ルーティング

動画要約サービスが利用可能かどうかだけで判断してください（以下の セットアップ → 可用性チェックで確認します）。動画の長さはルーティングの判断に影響しません。

/v1/ready	バックエンド	エンドポイント
HTTP 200	HITL を備えた LVS マイクロサービス	POST ${LVS_BACKEND_URL}/v1/summarize
その他すべて	デフォルトのプロンプトとフォールバック注記を使用する VLM／RT-VLM	POST ${VLM_BASE_URL}/v1/chat/completions

LVS サービスに到達できない場合のフォールバックメッセージ — 要約の上にそのまま記載してください：

⚠ 注記： 入力動画 <name> の長さは <N> 秒です。 動画要約サービスがデプロイされていないため、この要約は汎用のデフォルトプロンプトを 使用して VLM のみで生成されました。シナリオ／イベントを対象としたより高品質な要約を得るには、 lvs プロファイルをデプロイしてください。

デプロイの前提条件

$HOST_IP 上の VSS lvs プロファイルが主要なバックエンドです。 ウォームアップ後の再試行後も /v1/ready プローブ（セットアップ → 可用性チェックを参照）が 200 以外を返す場合は、ユーザーに尋ねてください。

「$HOST_IP 上で VSS の lvs プロファイルが実行されていません。-p lvs を指定して /vss-deploy-profile スキルを使い、今すぐデプロイしますか？代わりに no と返信すると、VLM のみを使うフォールバック（品質は低く、シナリオ／イベントのターゲティングはなし）で要約します。」

• はい → /vss-deploy-profile に引き継ぎ、その後プローブを再実行してステップ 2（LVS + HITL）に進みます。
• いいえ → **ステップ 2 のフォールバック（デフォルトプロンプトを使った VLM）**に直接進み、ルーティングのフォールバック注記を先頭に追加します。再度尋ねず、シナリオ／イベントの HITL は実行しません。
• 自律的なデプロイが事前承認されている（呼び出し元が明示している）→ 確認を省略し、/vss-deploy-profile を直接実行します。
• VLM フォールバックの使用が事前承認されている（「lvs はスキップして、VLM を使ってください」）→ プロンプトを表示せず、ステップ 2 のフォールバックに直接進みます。

---

セットアップ

エンドポイント（ローカル VSS lvs デプロイのデフォルト）：

• VLM / RT-VLM：${VLM_BASE_URL} — デフォルトは ${RTVI_VLM_BASE_URL:-http://${HOST_IP:-localhost}:8018}
• LVS サービス：${LVS_BACKEND_URL} — デフォルトは http://${HOST_IP:-localhost}:38111
• VIOS：vss-manage-video-io-storage が管理します。そちらを参照してください。

設定されている場合は環境変数を使用します（VLM ベースから末尾の /v1 を取り除いてください。スキルが追加します）。それ以外の場合はデフォルトを使用します。どちらも機能しない場合はユーザーに尋ねてください。ポートをスキャンしたり、設定ファイルを読んで推測したりしないでください。

モデル名： ${VLM_NAME} を読み取ります（デフォルトは nim_nvidia_cosmos3-nano-reasoner_bf16-final）。RT-VLM の /v1/models が通知する ID と一致している必要があります。わかりやすい名称の nvidia/cosmos3-nano-reasoner に置き換えないでください。

エンドポイントのスキーマ、オプションのフィールド、レスポンスのエンベロープ、エラー処理については、references/video-summarization-api.md を参照してください。

可用性チェック（ルーティング前に両方実行してください）。 準備完了の判定には HTTP ステータスコードのみを使用します — LVS /v1/ready は本文が空でも正当に 200 を返すことがあるため、本文を確認しないでください。

VLM="${VLM_BASE_URL:-${RTVI_VLM_BASE_URL:-http://${HOST_IP:-localhost}:8018}}"
VLM="${VLM%/v1}"

# VLM / RT-VLM: 200 on /v1/models
vlm_code=$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 3 --max-time 10 \
  "$VLM/v1/models")
[ "$vlm_code" = "200" ] && echo "VLM OK" || echo "VLM not reachable (HTTP $vlm_code)"

# Video summarization service: 200 on /v1/ready, with retry on 503 (warmup) for up to ~30s
VIDEO_SUMMARIZATION_URL=${LVS_BACKEND_URL:-http://${HOST_IP:-localhost}:38111}
video_sum_code=000
for i in $(seq 1 10); do
  video_sum_code=$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 3 --max-time 10 "$VIDEO_SUMMARIZATION_URL/v1/ready")
  case "$video_sum_code" in
    200) echo "video summarization OK"; break ;;
    503) sleep 3 ;;                 # warming up; keep polling
    *)   break ;;                   # any other code = not reachable, stop retrying
  esac
done
[ "$video_sum_code" = "200" ] || echo "video summarization service not reachable (HTTP $video_sum_code)"

結果の解釈方法：

• video_sum_code = 200 → すべての動画で ステップ 2（LVS + HITL）。
• video_sum_code != 200、vlm_code = 200 → ステップ 2 のフォールバック（VLM）。ルーティングのフォールバック注記を先頭に追加します。
• vlm_code != 200 → 失敗です。少なくとも 1 つのバックエンドに到達できる必要があります。
• 再試行ループ後に LVS が 200 以外のコードを返すことだけが、利用不可を示すシグナルです。標準出力が空であることや JSON フィールドが欠落していることは、「利用不可」を意味しません。

---

ステップ 1 - vss-manage-video-io-storage でクリップ URL を取得（サブタスク。最終回答ではありません）

すべての VIOS 操作には vss-manage-video-io-storage スキルを使用してください — 正規の curl レシピ、パラメーターのデフォルト、削除／アップロードのフローはこのスキルが管理します。URL を捏造したり、VIOS 呼び出しを独自に作成したりしないでください。内容が古くなるおそれがあります。

このステップはサブタスクです — ここでターンを終了しないでください。クリップ URL を最終回答として返さないでください。VIOS から次の 3 つの値を取得します。

1. streamId（sensor/list → sensor/<id>/streams 経由、またはアップロードレスポンスから直接取得）。
2. タイムライン - {startTime, endTime}（ISO 8601 UTC）。endTime - startTime が長さです。ユーザー向けのヘッダーにのみ必要です（ルーティングは /v1/ready のみに基づきます）。
3. 一時的な MP4 クリップ URL — container=mp4 を指定した /storage/file/<streamId>/url のバリエーションです。レスポンスフィールド：.videoUrl。両方のバックエンドで、GET 可能な HTTP(S) URL が必要です。

それ以外のすべて（認証、アップロード、disableAudio、有効期限など）は vss-manage-video-io-storage スキルで扱います。VIOS が失敗した場合は、ユーザーにそちらを参照するよう案内してください。

---

ステップ 2 — 優先：HITL を使用した動画要約マイクロサービス

セットアップで /v1/ready が 200 を返した場合は、必ずこの経路を使用します。長さは関係ありません。

高度なフィールド（media_info、schema、構造化出力、ストリームのキャプション生成、メトリクス、推奨設定）については、references/video-summarization-api.md を参照してください。

HITL：まずシナリオとイベントを収集する（必須 — 省略しないでください）

詳しい手順については、references/hitl-prompts.md を参照してください。LVS サービスを呼び出す前に、必ず HITL を実行してください。

自律モードのデフォルト値。 呼び出し元が HITL を省略し（「プロンプトを表示せず自律的に実行」）、かつ元のクエリで default／defaults を求めている（または指定がない）場合は、scenario="activity monitoring" と events=["notable activity"] をそのまま使用してください。ファイル名やセンサー名から推測してはいけません。最終回答でデフォルト値を明記し、より具体的なパラメーターでの再実行を提案してください。これがサポートされている唯一の HITL 省略方法です。「動画が短い」または「ユーザーが急いでいるように見える」は、有効な理由ではありません。

POST /v1/summarize（3.2 GA ルート）を優先してください。/summarize は互換性エイリアスです。

VIDEO_SUMMARIZATION_URL=${LVS_BACKEND_URL:-http://${HOST_IP:-localhost}:38111}

# From HITL reply:
SCENARIO='warehouse monitoring'
EVENTS_JSON='["notable activity"]'
OBJECTS_JSON=''  # '' to omit, else '["forklifts","pallets","workers"]'

curl -s --max-time 300 -X POST "$VIDEO_SUMMARIZATION_URL/v1/summarize" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg url "<clip_url_from_vss_manage_video_io_storage>" \
        --arg model "${VLM_NAME:-nim_nvidia_cosmos3-nano-reasoner_bf16-final}" \
        --arg scenario "$SCENARIO" \
        --argjson events "$EVENTS_JSON" \
        --argjson objects "${OBJECTS_JSON:-null}" '{
    url: $url,
    model: $model,
    scenario: $scenario,
    events: $events,
    chunk_duration: 10,
    num_frames_per_second_or_fixed_frames_chunk: 20,
    use_fps_for_chunking: false,
    seed: 1
  } + (if $objects == null then {} else {objects_of_interest: $objects} end)')" \
  | jq -r '.choices[0].message.content' \
  | jq '{video_summary, events}'

video_summary と events がどちらも空の場合、クリップに要求されたイベントが含まれていない可能性があります。「コンテンツなし」と報告するのではなく、より幅広い scenario／events を指定して再実行してください。

調整項目： chunk_duration（デフォルトは 10s、0 = 単一チャンク）、num_frames_per_second_or_fixed_frames_chunk（デフォルトは 20。意味は use_fps_for_chunking によって異なります）、seed（デフォルトは 1）。num_frames_per_chunk は非推奨です。

---

ステップ 2 のフォールバック — デフォルトのプロンプトを使った VLM への直接呼び出し

この方法を使うのは、ウォームアップ後に /v1/ready が 200 を返さなかった場合のみです。HITL は実行しないでください。ユーザーが選択したのではなく、サービスが利用できなかったためフォールバックしています。Routing のフォールバック注記を応答の先頭に追加してください。

VLM="${VLM_BASE_URL:-${RTVI_VLM_BASE_URL:-http://${HOST_IP:-localhost}:8018}}"
VLM="${VLM%/v1}"
PROMPT='Describe in detail what is happening in this video,
including all visible people, vehicles, equipments, objects,
actions, and environmental conditions.
OUTPUT REQUIREMENTS:
[timestamp-timestamp] Description of what is happening.
EXAMPLE:
[0.0s-4.0s] <description of the first event>
[4.0s-12.0s] <description of the second event>'

curl -s --max-time 300 -X POST "$VLM/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
        --arg model "${VLM_NAME:-nim_nvidia_cosmos3-nano-reasoner_bf16-final}" \
        --arg text "$PROMPT" \
        --arg url "<clip_url_from_vss_manage_video_io_storage>" \
        '{
          model: $model,
          temperature: 0.0,
          max_tokens: 1024,
          messages: [{
            role: "user",
            content: [
              {type: "text", text: $text},
              {type: "video_url", video_url: {url: $url}}
            ]
          }]
        }')" | jq -r '.choices[0].message.content'

応答： 標準の OpenAI チャット補完エンベロープです。要約は choices[0].message.content に含まれます。

Cosmos モデルに関する注記： Cosmos モデルは、<answer>...</answer> ブロックで推論を返す場合があります。通常の要約だけを得るには、推論に関する指示を省略してください。フレームのサンプリングとピクセル数の制限はサーバー側で適用されます。video_url を渡す場合、クライアント側での前処理は不要です。

---

エンドツーエンドの例

/v1/ready を確認し、適切な方法を実行する、LVS または VLM へのフォールバックを含むスクリプト全体については、references/end-to-end-example.md を参照してください。

---

応答

• VLM は OpenAI チャット補完エンベロープを返します。要約は choices[0].message.content に含まれます。
• LVS サービス も同じエンベロープを返しますが、content は JSON 文字列です。jq -r '.choices[0].message.content' | jq を実行すると、{video_summary, events} を取得できます。
• エラー は、HTTP の 2xx 以外のステータスと JSON {error: ...} として返されます。LVS の 503 は通常、ウォームアップ中であることを示します。/v1/ready を再試行してください。

出力をユーザーに提示する

バックエンドの出力は、最小限の変換で提示してください。言い換えたり、別の話し方に変えたり、絵文字を追加したり、再フォーマットしたりしないでください。バックエンドの呼び出し 1 回につき、表示も 1 回にします。複数の方法を並行して試して曖昧にしたり、ヘッダーを重複させたり、同じ動画に対して LVS と VLM の両方を呼び出したりしてはいけません。

ヘッダー行。 次のうち、いずれか 1 つだけを正確に使用して開始してください。

Summary of <video_name> (<duration>)

<duration> は、< 60 s の場合は Ns、それ以外の場合は Mm Ss（例：3m 30s）です。

LVS の出力： video_summary をそのまま表示してください（整えられ、トーンが調整されたレポートです。書き換えると忠実性が損なわれます）。各 events エントリーは、start_time、end_time、type、および description 全文をそのまま表示してください（クライアントが適切に表示できる場合は表、それ以外の場合はイベントごとのリストを使用します）。1 行のヘッダーと、異なるパラメーターでの再実行を提案する締めくくりを追加してもかまいません。

VLM の出力： choices[0].message.content をそのまま表示してください。モデルが <answer>…</answer> ブロックを生成した場合は、<think> ブロックを除き、回答のみを表示してください。

フォールバック警告（該当する場合）は、要約の上に表示してください。要約に混在させてはいけません。

ヒント

• 処理時間ではなく、サービスの利用可否に基づいて振り分けます。 Setup で /v1/ready を一度だけ確認します。HTTP 200 の場合はすべてのクリップで LVS+HITL を使用し、それ以外の場合は VLM にフォールバックします。
• LVS の経路では HITL が必須です。 許可されている唯一のバイパスは、defaults によるオプトインです。VLM のフォールバック経路はサイレントです（HITL なし）。
• 準備完了の条件は /v1/ready の HTTP 200 のみです。それ以外は条件に含まれません。 本文は空の場合があります。必ず curl -s -o /dev/null -w '%{http_code}' を使用してください。jq／grep／head にパイプで渡してはいけません。
• VIOS は vss-manage-video-io-storage に委任します — これはサブタスクです。最終回答は Step 2 の概要であり、クリップの URL ではありません。
• LVS の出力には jq を 2 回使います。 1 回目で OpenAI エンベロープを展開し、2 回目で content 内の JSON 文字列を解析します。
• 3.2 GA では /v1/summarize を優先してください。 /summarize は互換性のためのエイリアスです。
• エンドポイントが提示する VLM モデル ID をそのまま使用してください（デフォルトは nim_nvidia_cosmos3-nano-reasoner_bf16-final）。
• 出力はそのまま表示してください — 言い換え、再フォーマット、video_summary や choices[0].message.content の書き換えは行いません。
• 1 回の呼び出しにつき、表示も 1 回です。 並列で保険をかけたり、二重に表示したりしないでください。
• イメージタグはホストのプラットフォームに合わせてください。 x86／Jetson Thor では LVS_TAG=3.2.1（および RTVI_VLM_IMAGE_TAG=3.2.1）を、SBSA／DGX Spark／Grace（サーバークラスの ARM64）ホストでは LVS_TAG=3.2.1-sbsa（および RTVI_VLM_IMAGE_TAG=3.2.1-sbsa）を使用します。

相互参照

• vss-deploy-profile — base（VLM のみ）または lvs（VLM + 動画要約サービス）プロファイルを起動します
• vss-manage-video-io-storage（VIOS API）— 動画をアップロードし、ストリームを一覧表示して、クリップ URL を取得します
• vss-search-archive — アーカイブ全体のセマンティック検索（別のプロファイル）
• 動画要約 API リファレンス — references/video-summarization-api.md
• 動画要約サービス運用リファレンス — references/video-summarization-deployment.md

bump:3