vss-summarize-video

说明

请遵循下方的路由表和分步工作流。以 workflow、quick start 或 flow 结尾的各节均应自上而下执行。详细参考资料位于 references/。

示例

端到端示例存放在 evals/ 下（每个 *.json 清单都包含一个可运行的场景），也列在下方各工作流的 curl 代码块中。运行 Tier-3 评估：nv-base validate <this-skill-dir> --agent-eval，即可重放这些示例。

直接调用 VLM NIM 或视频摘要微服务。 请始终自行运行 curl 命令，切勿指示用户运行。

主要视频工作流查询类型：“总结这段视频。” 直接视频摘要 API 和服务运维请求由下方相应的参考路由章节处理。

用途

为单个录制的视频片段生成一段精炼完整的叙述性摘要；如果 LVS 微服务路径可用，则附上带时间戳的事件。

请勿将此技能用于：

• 实时 RTSP 字幕生成——请使用 vss-deploy-dense-captioning。
• 报告生成，包括事件或警报时间段报告——请使用 vss-generate-video-report Mode B。
• 跨档案的语义搜索——请使用 vss-search-archive。

前提条件

• VSS lvs 配置在 $HOST_IP 上运行（端口 38111），或可访问的 VLM/RT-VLM 端点作为备用方案。vss-deploy-profile 技能会启动这些服务。
• Agent 主机可通过网络访问这两个端点；VIOS 提供的片段 URL 必须能由所选后端获取。
• Agent 主机上已安装 jq 和 curl。

限制

• 直接使用 VLM 备用方案时，仅使用一个固定提示词，无法指定 场景/事件——输出质量低于 LVS 路径。
• 远程 VLM 端点通常无法访问 localhost/私有片段 URL。
• 每个请求仅调用一次后端；不进行并行试探或多轮摘要。

故障排除

症状	原因	解决方法
/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 详情：references/video-summarization-api.md，涵盖 /v1/summarize、/summarize、/v1/generate_captions、 /v1/stream_summarize、健康探测、/models、/recommended_config、 /metrics、请求字段、响应结构以及 API 注意事项。
• 视频摘要服务配置与运维： references/video-summarization-deployment.md，涵盖 VSS lvs 配置方案、端口、必需的环境变量、日志、状态、试运行、 拆除、模型/后端切换、Elasticsearch/Neo4j/ArangoDB 后端选择以及服务级故障排查。
• 扩展视频摘要运维参考资料： 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-deploy-profile 技能进行完整的 VSS 配置方案部署，并使用 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 配置未运行。要我现在使用 /vss-deploy-profile 技能并指定 -p lvs 来部署吗？回复 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 基础 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 → 对所有视频执行步骤 2（LVS + HITL）。
• video_sum_code != 200，vlm_code = 200 → 执行步骤 2 备用方案（VLM）；在开头添加路由备用方案说明。
• vlm_code != 200 → 失败；至少一个后端必须可访问。
• 重试循环结束后，非 200 的 LVS 状态码是唯一表示服务不可用的信号。标准输出为空或缺少 JSON 字段都不表示“不可用”。

---

步骤 1 - 通过 vss-manage-video-io-storage 获取片段 URL（子任务，不是最终答案）

所有 VIOS 交互都使用 vss-manage-video-io-storage 技能 — 该技能提供规范的 curl 命令、参数默认值以及删除/上传流程。 不要虚构 URL 或自行编写 VIOS 调用；这些内容会逐渐过时。

此步骤是子任务 — 不要在此结束本轮；不要将片段 URL 作为最终答案返回。从 VIOS 收集以下三个值：

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。两个后端都需要可通过 HTTP(S) 执行 GET 请求的 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_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 时，无需在客户端进行预处理。

---

端到端示例

完整的 LVS 或 VLM 回退脚本会探测 /v1/ready 并运行相应路径，详见 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。

向用户呈现输出

以最少转换呈现后端输出——不要转述、改变语气、添加表情符号或重新排版。一次后端调用 → 一次呈现：不要并行处理并模棱两可地表达，不要重复标题，也不要针对同一视频同时调用 LVS 和 VLM。

标题行。 恰好以下列其中一项开头：

Summary of <video_name> (<duration>)

<duration> = < 60 s 时为 Ns，否则为 Mm Ss（例如 3m 30s）。

**LVS 输出：**原样呈现 video_summary（这是经过润色且语气受控的报告——改写会损失保真度）。原样呈现每个 events 条目中的 start_time、end_time、type 和完整 description（客户端能清晰呈现时使用表格，否则使用逐事件列表）。可以添加一行标题和结尾处的提示，询问是否要使用不同参数重新运行。

**VLM 输出：**原样呈现 choices[0].message.content。如果模型生成了 <answer>…</answer> 块，则删除 <think> 块并显示答案。

回退警告（如适用）应置于摘要上方，不得混入摘要内容。

提示

• 根据服务是否可用进行路由，而非根据时长。 在 Setup 中探测一次 /v1/ready：HTTP 200 → 所有片段都使用 LVS+HITL；其他情况 → 回退到 VLM。
• LVS 路径必须使用 HITL。 defaults opt-in 是唯一获准的绕过方式。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。 第一次解包 OpenAI 信封，第二次解析 content 中的 JSON 字符串。
• 3.2 GA 优先使用 /v1/summarize；/summarize 是兼容性别名。
• 使用端点公布的准确 VLM 模型 ID（默认值为 nim_nvidia_cosmos-reason2-8b_hf-1208）。
• 原样呈现输出——不要改述、重新排版或改写 video_summary 或 choices[0].message.content。
• 一次调用，一次呈现。 不要并行尝试，也不要重复呈现。

交叉引用

• 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