vss-summarize-video

VSS 摘要

通过 Pipeline Manager 运行摘要工作流。请自行运行 curl 命令 并转达结果。端点使用 nginx /manager 前缀。

设置 HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}。

环境设置（先运行）

此技能通过实际源文件驱动 Video Search & Summarization 应用，因此必须有 VSS 应用，并且必须从其应用根目录运行命令。请先执行此操作；无论工作区中是否已有 VSS 源代码，都适用。

运行捆绑的引导脚本。它会先尝试查找现有的 VSS 检出目录——从当前目录向上遍历， 并检查所在的 git 仓库——找到后会复用，绝不会重新克隆。只有找不到检出目录时， 才会从 main 对 sample-applications/video-search-and-summarization 执行浅克隆、 单分支、稀疏检出。它会在标准输出中打印解析出的应用根目录：

# SKILL_DIR is THIS skill's own directory (shown to you when the skill loads);
# in-repo it is .github/skills/vss-summarize-video. Works the same if the skill is installed standalone.
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

以下每条命令都假设当前工作目录为此 APP_ROOT。如需从 fork/分支拉取，或复用 特定的检出目录，请在运行前覆盖 VSS_REPO_URL、VSS_REPO_BRANCH 或 VSS_CLONE_DIR。

前提条件

1. 后端运行正常且已启用摘要——先进行探测；如果不满足，请使用 vss-troubleshoot / vss-deploy：

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

2. 要摘要的视频 videoId——使用 POST /manager/videos 上传一个视频（multipart， 字段为 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)
}'

⚠️ 完成条件是 videoSummaryStatus == "complete"，而不是 summary 非空。 最终的 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