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 を使用してください。
• インシデントレポートやアラート時間帯レポートなどのレポート生成 — vss-generate-video-report の Mode B を使用してください。
• アーカイブ全体のセマンティック検索 — vss-search-archive を使用してください。

前提条件

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

制限事項

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

トラブルシューティング

症状	原因	対処方法
/v1/ready が繰り返し 503 を返す	LVS サービスの起動がまだ完了していません	Setup の手順に従って最大約 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 のプローブ（Setup → Availability checks を参照）が 200 以外を返す場合は、ユーザーに確認してください。

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

• はい → /vss-deploy-profile に引き継ぎ、その後もう一度プローブして Step 2（LVS + HITL）に進みます。
• いいえ → Step 2 fallback（VLM with default prompt） に直接進み、Routing fallback の注記を先頭に追加します。再度確認せず、シナリオ／イベントの HITL も実行しません。
• 自律的なデプロイを事前承認済み（呼び出し元が明示的に指定）→ 確認を省略し、直接 /vss-deploy-profile を呼び出します。
• VLM フォールバックの使用を事前承認済み（「lvs は使わず、VLM だけを使ってください」）→ 確認せず、Step 2 fallback に直接進みます。

---

セットアップ

エンドポイント（ローカルの 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 のベース URL から末尾の /v1 を取り除いてください。スキル側で追加されます）。設定されていない場合はデフォルトを使用します。どちらも機能しない場合はユーザーに確認してください。推測のためにポートをスキャンしたり、設定ファイルを読み取ったりしないでください。

モデル名： ${VLM_NAME} を読み取ります（デフォルトは nim_nvidia_cosmos-reason2-8b_hf-1208）。RT-VLM の /v1/models が通知する ID と一致している必要があります。わかりやすい名前の nvidia/cosmos-reason2-8b に置き換えないでください。

エンドポイントのスキーマ、省略可能なフィールド、レスポンスの形式、エラー処理については、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 → すべての動画で Step 2（LVS + HITL） に進みます。
• video_sum_code != 200、vlm_code = 200 → Step 2 fallback（VLM） に進み、Routing fallback の注記を先頭に追加します。
• vlm_code != 200 → 失敗です。少なくとも 1 つのバックエンドに到達できる必要があります。
• 再試行ループ後の LVS の 200 以外のコードだけが、利用不可を示すシグナルです。標準出力が空であることや JSON フィールドがないことは、「利用不可」を意味しません。

---

Step 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 に問題がある場合は、ユーザーにそちらを案内してください。

---

Step 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_cosmos-reason2-8b_hf-1208}" \
        --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_cosmos-reason2-8b_hf-1208}" \
        --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 Reason 2 は、<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_cosmos-reason2-8b_hf-1208）。
• 出力は一字一句そのまま表示してください — video_summary や choices[0].message.content の言い換え、再フォーマット、書き換えは行わないでください。
• 1 回呼び出したら、1 回だけ表示します。 並列での保険的な呼び出しや、二重表示は行いません。

関連項目

• 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:2