vss-summarize

VSS 要約

Pipeline Manager を介して要約パイプラインを実行します。curl コマンドは ご自身で実行し、結果を伝えてください。エンドポイントには nginx の /manager プレフィックスを使用します。

HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345} を設定します。

前提条件

1. バックエンドが正常で、要約が有効になっていること — まず確認してください。有効でない場合は、 vss-doctor / vss-up を使用します：

   curl -sf "$HOST/manager/health" >/dev/null && \
   curl -s "$HOST/manager/app/features" | jq '.summary // .'   # confirm summary capability
   

2. 要約する videoId があること — POST /manager/videos（マルチパート、 フィールド video）で動画をアップロードすると、{ "videoId": "…" } が返されます。または既存の動画を一覧表示します — レスポンスは単なる配列ではなく オブジェクト { "videos": [...] } です。また、 name は生成されたハッシュです（実際のファイル名は url / dataStore.fileName にあります）：

   curl -s -X POST "$HOST/manager/videos" -F "video=@/path/to/clip.mp4" | jq .
   curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
   

1. 要約パイプラインを開始する

POST /manager/summary。リクエスト本文には必須フィールドがあります — title、 sampling.*、evam.evamPipeline のいずれかが欠けていると 400 が返されます。完全な スキーマ、プロンプトのオーバーライド、音声オプションについては references/summary-request.md を参照してください。

有効な最小リクエスト：

curl -s -X POST "$HOST/manager/summary" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Loading dock review",
    "videoId": "<VIDEO_ID>",
    "sampling": { "chunkDuration": 20, "samplingFrame": 5, "frameOverlap": 0, "multiFrame": 5 },
    "evam": { "evamPipeline": "object_detection" },
    "produceFinalSummary": true
  }' | jq .
# → { "summaryPipelineId": "<STATE_ID>" }

サンプリングの制約： Pipeline Manager は multiFrame == frameOverlap + samplingFrame を適用します。frameOverlap: 0 の場合は、 multiFrame == samplingFrame に設定してください。不一致の場合は 400 "Multi frame mismatch" が返されます。 evamPipeline は object_detection | video_ingestion のいずれかです。

2. 完了するまでポーリングする

返された summaryPipelineId が stateId です。GET /manager/summary/{stateId} にはトップレベルの status / progress フィールドはありません（/raw にのみあります）— 進捗状況は 各ステージのフィールドにあります：

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # string, "complete" when chunked
  frames:   .frameSummaryStatus,     # COUNTS object: {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # string: "na" → "inProgress" → "complete"  ← real done signal
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ 完了の判定は summary が空でないことではなく、videoSummaryStatus == "complete" です。 最終的な summary テキストは、 videoSummaryStatus がまだ "inProgress" の間に逐次ストリーミングされるため、 「summary の長さ > 0」を条件にポーリングすると、文の途中で切れた結果が返されます。常に videoSummaryStatus を条件にしてください。produceFinalSummary: false の場合は最終ステージがないため、 代わりに frameSummaryStatus.inProgress == 0 を条件にしてください。

until curl -s "$HOST/manager/summary/$STATE_ID" \
       | jq -e '.videoSummaryStatus == "complete"' >/dev/null; do sleep 10; done

要約には時間がかかります（チャンクごとの VLM 処理 + LLM の map-reduce）— 秒ではなく数分です。

3. 要約を取得する

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # final map-reduced summary
# Per-chunk captions live in .frameSummaries[] (each: frameKey, status, summary).
# NOT in .chunks[] — those only carry {chunkId, duration, audioTranscripts}:
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # everything (audio, frames, status, …)

最終的な要約テキストを提示し、必要に応じてチャンクごとの詳細を案内してください。音声に 発話がない場合、audioTranscriptSummary はその旨を示します — エラーではありません。

管理

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # list all
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # delete one