vss-manage-video-io-storage

用途

管理 VSS 视频输入/输出和存储工作流中的 VIOS 与 NvStreamer API 操作：传感器、流、上传、快照、片段、时间线和录制状态。

前置条件

• 可通过 $HOST_IP 访问的活动 VSS 部署（参见 vss-deploy-profile 和 references/）。
• 执行任何镜像拉取操作时，需要在 $NGC_CLI_API_KEY 和 $NVIDIA_API_KEY 中配置 NGC 凭据。
• 调用方已安装 curl、jq 和 Docker。

说明

VIOS 操作

调用 VIOS REST API 管理摄像头/传感器、RTSP 流、录制、快照和存储。适用于以下请求：添加摄像头、添加 RTSP 流、列出传感器、查看已配置的传感器/摄像头/流、检查流状态、获取快照、下载片段、上传视频文件或管理视频存储。直接使用 curl 查询 VIOS API——不要浏览 UI。

上传路由规则：

• 如果用户要求“将 <file>.mp4 上传到 VIOS”、“上传视频文件”，或其他明确表示要将本地视频存储为 VIOS 文件型传感器的请求，请使用直接 VIOS API：references/api-reference.md 第 8 节中的 PUT /vst/api/v1/storage/file/{filename}。
• 只有当用户明确需要实时/合成 RTSP 摄像头馈送、询问 NvStreamer，或要求获取 RTSP URL 时，才使用 NvStreamer。
• 对于普通的 VIOS MP4 上传请求，不要用 NvStreamer 上传 → RTSP URL → VIOS /sensor/add 的交接流程替代。

以下情况不要使用此技能：

• 对片段执行 VLM 推理或临时视觉问答——请使用 vss-ask-video。
• 在存档中进行语义搜索，或为搜索摄取视频——请使用 vss-search-archive。
• 生成已录制片段的叙述性摘要——请使用 vss-summarize-video。
• 生成事件时间范围或警报时间窗口报告——请使用 vss-generate-video-report 的 Mode B。
• 读取分析指标、事件或警报——请使用 vss-query-analytics。

此技能随附的参考契约

此技能在 references/ 下附带了 4 个参考文件。请根据当前任务阅读相应文件：

文件	用途	适用对象
references/api-reference.md	完整的 VIOS REST API 参考（运行时契约），涵盖传感器管理、存储、快照、片段提取、WebRTC 实时/回放、RTSP 代理、录像机、服务配置和服务发现。调用任何 VIOS API 操作时都请阅读此文件。	运维用户 + 此技能本身
references/nvstreamer-api-reference.md	NvStreamer REST API 参考，涵盖版本、传感器列表/信息/状态/流、3 种上传方法（PUT v2 / PUT v1 / POST multipart）及 nvstreamer-* 自定义标头、删除、快照（按帧索引的实时快照、按时间戳索引的存储快照）、存储信息和文件系统扫描。NvStreamer（vss-vios-nvstreamer，即 launch_vst 的 streamer-adaptor 变体）由启动 VIOS 的同一组配置文件启动，包括 dev-profile-alerts、dev-profile-lvs、dev-profile-search 和所有 warehouse 配置文件。部署方面请参阅 integrate-vios-service.md § Topology B。当通过合成 RTSP 提供测试/示例视频、获取 NvStreamer 为文件生成的 RTSP URL，或执行标准的 NvStreamer → VIOS 交接流程（上传到 NvStreamer → 读取 RTSP URL → 通过 /sensor/add 向 VIOS 注册该 URL）时，请阅读此文件。	运维用户 + 编写上传 → RTSP URL → VIOS /sensor/add 流程的技能作者
references/integrate-vios-service.md	集成契约，说明 VIOS 如何接入其他 VSS 微服务。记录了所需的对等服务（RT-VLM、ELK、Kafka、Redis、sdr-controller / SDRC）、由 vss-build-vision-agent 技能的第 4 步使用的结构化 component_services: 块、集成输入/输出（Kafka 主题、REST 端点、文件路径）、环境变量、网络要求，以及已知的集成限制（例如 /url 变体的双重 http:// Bug、VIOS + SDRC 补丁要求）。当编写与 VIOS 对接的技能、组合新的 VSS 部署，或调试字幕流水线连接时，请阅读此文件。	技能作者、部署编排人员、配对文件维护人员
references/deploy-vios-service.md	部署契约，说明启动 VIOS 所需的条件。记录了容器映像和标签（nvcr.io/nvidia/vss-core/vss-vios-*:3.2.0）、GPU / CPU / 内存 / 存储要求、启动行为与健康检查调优、所需环境变量（特别是用于控制上传所需 libav apt-install 步骤的 VST_INSTALL_ADDITIONAL_PACKAGES=true）、已知部署问题（卷漂移、缺少 libav、残留容器导致的 502）、先决条件、试运行、验证部署和拆除命令。当 VIOS 未运行且你（或调用方）需要单独部署它、调试容器启动故障，或编写封装 VIOS 的部署技能时，请阅读此文件。	运维人员、部署技能作者

部署前提条件 — VIOS 必须正在运行

此技能主要是一个 API 客户端，假定 VIOS 已启动，并可通过 VST 入口访问（默认地址为 http://${HOST_IP}:30888）。它本身不会部署 VIOS，但如果无法访问 VIOS，则会使用随附的部署操作手册（references/deploy-vios-service.md）协调部署，或交由完整技术栈的 /vss-deploy-profile 技能处理。在执行任何操作之前：

1. 探测 VIOS：

   curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null
   

2. 如果探测失败，则表示 VIOS 尚未部署。 提供两种后续方案：

   “无法通过 http://${HOST_IP}:30888 访问 VIOS——目前没有正在运行的部署。你有两个选择： (a) 使用此技能随附的 references/deploy-vios-service.md 操作手册独立启动 VIOS——其中记录了镜像标签、环境变量（尤其是 VST_INSTALL_ADDITIONAL_PACKAGES=true）、主机目录、NGC 登录、启动命令、健康检查循环以及已知部署问题。如果你只需要 VIOS 本身（不需要 RT-VLM / ELK / 等组件），或者要组合自定义配置文件，这是合适的选择。 (b) 通过 /vss-deploy-profile 技能部署包含 VIOS 的完整 VSS 配置文件——base（推荐）、lvs、search 或 alerts 都会同时启动 VIOS 和其他组件。如果你想要完整的 VSS 技术栈，这是合适的选择。 你想选择哪种？”

   • 如果用户选择 (a) → 按步骤引导他们完成 references/deploy-vios-service.md。特别留意其中的 § Environment Variables — Required for Upload-to-Caption Path 和 § Known Deployment Issues 章节——缺少 libav 导致的故障（VST_INSTALL_ADDITIONAL_PACKAGES=true）以及卷漂移导致的挂起（先运行 docker compose up --yes 或 docker volume rm）是启动过程中最常见的两个阻碍。部署成功且步骤 1 中的探测通过后，返回此处。
   • 如果用户选择 (b) → 转交给 /vss-deploy-profile -p <profile>（默认为 base）。成功后返回此处。
   • 如果用户两种方案都拒绝 → 停止。VIOS 操作要求 VST 后端处于运行状态；不要尝试捏造响应，也不要以降级模式继续操作。

   预先授权的自主模式： 如果调用方已明确预先授权部署前置依赖项（例如，请求中写明“已预先授权部署前置依赖项”，或者你正在获准执行此操作的非交互式评测框架中运行），则跳过确认，并优先选择方案 (a)——通过此技能随附的 references/deploy-vios-service.md 独立启动 VIOS；除非请求明确要求部署完整 VSS 配置文件，此时应调用 /vss-deploy-profile -p base。

3. 如果探测通过，则继续。 VIOS 已启动；下面的所有操作均可安全执行。

---

已知限制 — 先前部署遗留的容器

如果先前部署留下的 *-smc VST 容器在拆除后仍然存留，并在 :30000 / :30888 上的 network_mode: host 端口绑定竞争中胜出，则 GET /vst/api/v1/sensor/list 和 GET /vst/api/v1/sensor/<sensorId>/streams 可能返回 HTTP 502 Bad Gateway 或过时结果。解决方法： 重新运行 /vss-deploy-profile——其步骤 0 中的拆除操作会通过 grep 清除完整的 sensor-ms-* / vst-ingress-* / sdr-* / sdrc-* / rtspserver-ms-* 集合。 其他路径（storage/file/* 上传、*/picture/url 快照、*/url 剪辑提取）不受影响。完整的故障模式目录、解决方法以及当前路由约定（直连与 SDRC；SDR/Envoy 已在 PR #711 中移除）见 references/deploy-vios-service.md § Known Deployment Issues 和 issue #151。

---

设置

基础 URL： http://<VST_ENDPOINT>/vst/api/v1

端点解析：

• 使用与当前 VSS 部署关联的 VIOS 端点。此端点表示从 VSS Agent 的运行时上下文可访问的 VST 后端。
• 不要尝试通过 Shell 命令、文件系统访问或静态配置文件来发现主机、IP 或端口。
• 假定 VSS 部署上下文已提供正确的 VST 网络端点。

可用性检查：

• 发起任何 API 调用前，请验证是否可通过 VSS 部署端点访问 VST 后端：

  curl -sf --connect-timeout 5 http://<VST_ENDPOINT>/vst/api/v1/sensor/version
  

• 如果后端不可用（退出代码非零或发生连接错误），请妥善处理失败并向用户报告错误。有关“部署前提条件”部分中的部署或停止分支，请参阅上文。

回退：

• 如果上下文中没有端点信息，请明确询问用户提供 VST 端点（主机/IP 和端口）。

所有 curl 命令都由你执行，不要指示用户手动运行命令。

身份验证： 可选。大多数部署无需身份验证。如果返回 401，请使用 -H "Authorization: Bearer <token>" 重试，并向用户索取令牌。

开始/结束时间处理： 任何需要 startTime/endTime 的 API：

• 如果用户提供了这些值，请直接使用。
• 如果用户未提供，请先获取相关流的时间线，以查找有效的录制时间范围，然后从响应中选取合适的值再调用 API。切勿伪造时间戳。

解析 sensorId / streamId： 如果用户未提供 sensorId 或 streamId，请使用以下任一方式自动查询：

• GET /sensor/list — 列出所有传感器及其 sensorId
• GET /sensor/{sensorId}/streams — 列出指定传感器的流及其 streamId
• GET /sensor/streams — 列出所有传感器的所有流
• GET /live/streams — 列出所有当前活动的实时流
• GET /replay/streams — 列出所有可用的回放流

如果某个传感器只有一个流，则 sensorId 和 streamId 相同，可以互换使用。

---

服务映射

功能	URL 前缀	权威参考
版本 / 健康检查	/vst/api/v1/sensor/version	references/api-reference.md
传感器列表 / 信息 / 状态 / 添加 / 删除	/vst/api/v1/sensor/	references/api-reference.md
传感器流	/vst/api/v1/sensor/streams、/vst/api/v1/sensor/{id}/streams	references/api-reference.md
网络扫描	/vst/api/v1/sensor/scan	references/api-reference.md
录制时间线	/vst/api/v1/storage/	references/api-reference.md
视频剪辑下载 / URL	/vst/api/v1/storage/	references/api-reference.md（操作）+ references/integrate-vios-service.md § Known Integration Constraints（发现 8：/url 的双重 http:// 错误——优先使用二进制直接端点）
文件上传 / 删除	/vst/api/v1/storage/	references/api-reference.md（PUT v2 + 旧版 v1 端点）+ references/deploy-vios-service.md § Known Deployment Issues（发现 9：libav 缺失故障模式）
实时流 / 快照（图片）	/vst/api/v1/live/	references/api-reference.md
回放流 / 历史快照	/vst/api/v1/replay/	references/api-reference.md（操作）+ references/integrate-vios-service.md § Known Integration Constraints（发现 8）
NvStreamer：文件转 RTSP 转发器（上传、获取生成的 RTSP URL、文件系统扫描、帧快照）	http://${HOST_IP}:${NVSTREAMER_HTTP_PORT:-31000}/vst/api/v1/	references/nvstreamer-api-reference.md（Streamer 端点与 VIOS 网关分开——端口不同，/version 上的 type: "streamer"）

---

操作

完整的 VIOS REST API 参考文档涵盖传感器管理、存储、快照、片段提取、WebRTC 实时播放／回放、RTSP 代理、录像机、服务配置和服务发现，位于 references/api-reference.md。调用任何操作时，请阅读该文件。

当请求涉及将磁盘上的视频文件作为合成 RTSP 摄像头提供服务（向 NvStreamer 上传样本、获取自动生成的 RTSP URL、向 VIOS 注册该 URL）时，请使用 NvStreamer 端点，并根据 references/nvstreamer-api-reference.md 了解相关接口。任何附带 NvStreamer 的 VIOS 配置都会自动启动它；无需单独部署。

对于有关 VIOS 如何与其他微服务交互，或如何启动 VIOS 的集成和部署问题，请分别参考 references/integrate-vios-service.md 和 references/deploy-vios-service.md（各文件的涵盖范围请参见上方的 Reference contracts 表）。

---

工作流：传感器名称／IP -> 片段或快照

当用户知道传感器名称或 IP，但需要片段或快照时：

0. 确认 VST 可访问（参见 Setup — Availability Check）：

   curl -sf --connect-timeout 5 "http://<VST_ENDPOINT>/vst/api/v1/sensor/version"
   

1. 列出传感器，找到 sensorId：

   curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/list" | jq .
   

2. 获取该传感器的流，找到 streamId（优先选择 isMain: true）：

   curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/streams" | jq .
   

3. 检查时间线，确认请求的时间范围内存在录像：

   curl -s "http://<VST_ENDPOINT>/vst/api/v1/storage/<streamId>/timelines" | jq .
   

4. 使用 streamId 下载片段或快照。优先使用二进制直连接口（/storage/file/<streamId>?startTime=...&endTime=...、/replay/stream/<streamId>/picture?startTime=...、/storage/stream/<streamId>/picture?startTime=...），而不是 /url JSON 封装形式——参见 references/integrate-vios-service.md § Known Integration Constraints 中的 Finding 8（在 3.2.0 中，/url 形式会返回带有重复 http:// 的 URL，需在客户端去除）。

---

响应

成功且有数据： JSON 对象或数组。

成功但无数据： null——null 响应表示 API 调用成功，但没有可返回的数据（例如，未配置计划、扫描未返回结果）。这不是错误。

成功并返回布尔值： 某些端点成功时会返回 true（例如，DELETE /sensor/{sensorId}）。

错误： 包含 error_code 和 error_message 的 JSON 对象：

{
  "error_code": "VMSInternalError",
  "error_message": "VMS internal processing error"
}

常见代码：VMSInternalError、VMSNotFound、VMSInvalidParameter。

如果 PUT 上传时出现 InvalidParameterError: Failed to get media information，这是缺少 libav 的故障模式——部署 VIOS 时未设置 VST_INSTALL_ADDITIONAL_PACKAGES=true。修复方法请参见 references/deploy-vios-service.md § Known Deployment Issues 中的 Finding 9。

如果 /url 形式的响应中，imageUrl 或 videoUrl 字段带有重复的 http:// 前缀，这是 Finding 8——请在客户端去除开头的 http://，或改用二进制直连接口。

---

示例

操作提示词示例：

• “列出活跃的 VIOS 传感器，并显示其流状态。”
• “将此样本视频上传到 VIOS，并返回生成的流 ID。”
• “从此传感器的录像时间线下载一段两秒的片段。”
• “使用 NvStreamer 上传文件并获取生成的 RTSP URL。”

限制

• VIOS 操作需要可访问的 VST 后端；健康探测失败时，请停止操作或部署所需的前置条件。
• 大多数部署不需要身份验证，但部署可以添加外部身份验证层。
• 示例中的容器内路径使用 ${VST_CONTAINER_ROOT} 作为 VST 在容器内安装根目录的通用占位符。使用路径示例前，请根据当前部署确定其实际值。
• 请勿在日志或最终响应中打印 API 密钥、Bearer 令牌或生成的凭据。

故障排除

• 错误：健康探测失败。原因：VIOS 尚未部署，或端点有误。解决方案：按照部署前置条件流程操作，或询问正确的 VST 端点。
• 错误：上传失败，并显示 Failed to get media information。原因：VIOS 容器中未安装 libav 软件包。解决方案：设置 VST_INSTALL_ADDITIONAL_PACKAGES=true 并重新部署。
• 错误：/url 响应中包含 http://http://...。原因：已知的 URL 构造缺陷。解决方案：使用二进制直连端点，或去掉重复前缀。

---

提示

• **jq：**所有 JSON 响应都会通过 jq . 管道处理，以便阅读。二进制响应（片段下载、快照）不会这样处理，而是使用 -o <file>。
• **时间格式：**始终使用 ISO 8601 UTC 格式，例如 2026-04-10T10:30:00Z 或 2026-04-10T10:30:00.000Z。
• **streamId 请求头：**实时、回放和录像机端点要求将 streamId 同时作为路径参数和请求头传入——两者都要包含。
• **大型片段：**使用二进制直连 /storage/file/<id>?...&container=mp4 端点，并通过 -o clip.mp4 直接流式传输。/url 封装变体存在 Finding 8 中提到的双重 http:// 缺陷，在上游修复前请避免使用，或者在客户端剥除重复前缀。
• 传感器与流 ID：sensorId 用于标识摄像头；streamId 用于标识该摄像头的特定视频流（一个传感器可以有主流和子流）。
• **识别传感器类型（RTSP 或上传文件）：**调用 GET /sensor/<sensorId>/streams，并检查每个流的 url 字段。如果 url 以 rtsp:// 开头，则表示这是实时 RTSP/IP 摄像头流。如果 url 是文件路径（例如 "${VST_CONTAINER_ROOT}/streamer_videos/TruckAccident.mp4"），则表示这是上传文件传感器。这决定了要使用哪种删除流程——参见第 8 节。
• **上传时间戳会用于录像时间线：**通过 PUT /vst/api/v1/storage/file/<filename>?timestamp=<iso> 上传文件时，GET /storage/<streamId>/timelines 返回的时间线以指定的时间戳为起点，而不是以上传时的实际时间为起点。之后查询快照或片段时，必须使用此范围内的时间戳——请先获取时间线。权威说明见 references/api-reference.md § 8 和 references/integrate-vios-service.md § Integration Interfaces > Inputs > Upload video file。
• **端点解析：**VST 端点由 VSS 部署上下文提供。请勿尝试手动查找 IP/端口。如果无法获取，请询问用户。所有 curl 示例均使用 <VST_ENDPOINT> 作为占位符——执行前请替换为已解析的端点。