
名称	vss-summarize-video
描述	用于通过 LVS 摘要微服务（HITL 门控）并带有 VLM 回退来汇总一段录制的视频。不用于报告生成或实时 RTSP 字幕。
开源协议	Apache-2.0 metadata:
版本	“3.2.1”
作者	“NVIDIA 视频搜索与摘要团队” github-url: “https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization” tags: “nvidia blueprint operational”

说明

请遵循下面的路由表和逐步工作流。每个以“工作流”、“快速开始”或“流程”结尾的章节都应从上到下执行。详细参考资料位于 references/。

示例

完整的端到端示例保存在 evals/ 下（每个 *.json 清单包含一个可运行的场景），并包含在下面各工作流的 curl 代码块中。使用 nv-base validate <this-skill-dir> --agent-eval 运行 Tier-3 评估来重放它们。

直接调用 VLM NIM 或视频摘要微服务。请始终自己执行 curl 命令；绝不要让用户运行。

主要的视频工作流查询类型：“Summarize this video.” 直接视频摘要 API 和服务操作请求由下面的引用路由部分处理。

目的

对单个录制的视频片段生成一个简洁的叙述性摘要，当 LVS 微服务路径可达时，可包含带时间戳的事件。

不要将此技能用于：

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

先决条件

VSS lvs 配置文件运行在 $HOST_IP 上（端口 38111），或者可访问的 VLM/RT-VLM 端点作为回退。vss-deploy-profile 技能会启动这些。
代理主机到两个端点的网络可达性；来自 VIOS 的剪辑 URL 必须能够被所选后端获取。
代理主机上可用的 jq 和 curl。

局限性

直接 VLM 回退使用单个固定提示，无法针对场景/事件 —— 输出质量低于 LVS 路径。
远程 VLM 端点通常无法访问 localhost/私有剪辑 URL。
每次请求一次后端调用；不做并行对冲或多遍摘要。

故障排除

症状	原因	修复
`/v1/ready` 反复返回 503	LVS 服务仍在预热	如“设置”中所示重试至多约 30 秒；如果始终不返回 200，则服务可能未部署
`video_summary` 和 `events` 为空	剪辑不包含请求的事件	使用更广泛的 `scenario` 或不同 `events` 重新运行
VLM 返回 `<think>` 块	Cosmos 推理模式	在呈现前剥离到 `</think>` 为止的所有内容
`curl /v1/ready` 的 stdout 为空	服务合法返回空正文的 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 的状态，询问用户：

“VSS lvs 配置文件当前没有运行在 $HOST_IP 上。我现在使用 /vss-deploy-profile 技能并带 -p lvs 来部署它吗？回复 no 则改用仅 VLM 回退（质量较低，没有场景/事件定向）。”

是 → 移交给 /vss-deploy-profile，然后重新探测并以第 2 步（LVS + HITL）继续执行。
否 → 直接进入 第 2 步回退（带默认提示的 VLM），并在回复前加上路由回退注释。不要再次询问，也不要运行场景/事件 HITL。
预先授权自主部署（调用者明确说明）→ 跳过确认，直接调用 /vss-deploy-profile。
预先授权使用 VLM 回退（“skip lvs, just use the 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 base 中去除尾部 /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: /v1/models 返回 200
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)"

# 视频摘要服务: 在 /v1/ready 返回 200，如果 503（预热）则重试，最长约 30 秒
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 是唯一不可用信号。空 stdout 或缺失 JSON 字段不是“不可用”。

第 1 步 - 通过 `vss-manage-video-io-storage` 获取剪辑 URL（子任务，不是最终答案）

对所有 VIOS 交互使用 vss-manage-video-io-storage 技能 —— 它拥有规范的 curl 配方、参数默认值和删除/上传流程。不要捏造 URL 或手工编写 VIOS 调用；它们会漂移。

此步是子任务 —— 不要在这里结束轮次；不要将剪辑 URL 作为最终答案返回。从 VIOS 收集三个值：

streamId（通过 sensor/list → sensor/<id>/streams，或直接从上传响应中获取）。
时间轴 - {startTime, endTime}（ISO 8601 UTC）。endTime - startTime 是时长；仅用于用户可见的头部（路由仅由 /v1/ready 驱动）。
临时 MP4 剪辑 URL —— /storage/file/<streamId>/url 变体，带 container=mp4。响应字段：.videoUrl。两个后端都需要一个它们可以 GET 的 HTTP(S) 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}

# 来自 HITL 回复：
SCENARIO='warehouse monitoring'
EVENTS_JSON='["notable activity"]'
OBJECTS_JSON=''  # '' 表示省略，否则 '["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 —— 用户未选择加入；你是因为服务缺失而回退。在回复前加上路由回退注释。

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 聊天完成包装。摘要在 choices[0].message.content 中。

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

端到端示例

参见 references/end-to-end-example.md 获取完整的 LVS-或-VLM-回退脚本示例，该脚本探测 /v1/ready 并运行相应路径。

响应

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 秒时为 Ns，否则为 Mm Ss（例如 3m 30s）。

LVS 输出： 逐字呈现 video_summary（润色、语气控制的报告 —— 重写会损失保真度）。以 start_time、end_time、type 和完整的 description 逐字呈现每个 events 条目（当客户端能干净呈现时用表格，否则用逐事件列表）。你可以添加一行头部和一句使用不同参数重新运行的结束语。

VLM 输出： 逐字呈现 choices[0].message.content。如果模型产生 <think>…</think><answer>…</answer> 块，则丢弃 <think> 块并显示答案。

回退警告（适用时）放在摘要上方，绝不要混入其中。

提示

按服务可用性路由，而不是按时长。 在设置中探测 /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 —— 它是子任务；最终答案是第 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 — 跨档案的语义搜索（不同配置文件）
vss-query-analytics — 从 Elasticsearch 查询事件/事件
视频摘要 API 参考 — references/video-summarization-api.md
视频摘要服务操作参考 — references/video-summarization-deployment.md

bump:3

说明

示例

目的