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_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 → 失败；至少一个后端必须可访问。
• 重试循环后，LVS 返回非 200 状态码是唯一表示服务不可用的信号。标准输出为空或缺少 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}（UTC 的 ISO 8601 格式）。endTime - startTime 为时长；仅用于面向用户的标题（路由完全由 /v1/ready 决定）。
3. 临时 MP4 片段 URL — /storage/file/<streamId>/url 变体，参数为 container=mp4。响应字段：.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_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 chat-completion 信封。摘要位于 choices[0].message.content。

**Cosmos 模型说明：**Cosmos 模型可能通过 <answer>...</answer> 块返回推理内容。如果需要纯摘要，请省略推理指令。帧采样和像素限制由服务端应用；传入 video_url 时，无需在客户端进行预处理。

---

端到端示例

完整的 LVS 或 VLM 回退脚本（会探测 /v1/ready 并运行相应路径）见 references/end-to-end-example.md。

---

响应

• VLM 返回 OpenAI chat-completion 信封；摘要位于 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——这是一个子任务；最终答案应为步骤 2 的摘要，而不是片段 URL。
• 对 LVS 输出使用两次 jq。 第一次提取 OpenAI 信封中的内容，第二次解析 content 中的 JSON 字符串。
• 对于 3.2 GA，优先使用 /v1/summarize；/summarize 是兼容性别名。
• 使用端点公布的确切 VLM 模型 ID（默认值为 nim_nvidia_cosmos3-nano-reasoner_bf16-final）。
• 原样呈现输出——不要改述、重新排版或改写 video_summary 或 choices[0].message.content。
• 一次调用，一次呈现。 不要并行尝试，也不要重复呈现。
• 让镜像标签与主机平台匹配。 在 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