
名称	vss-manage-video-io-storage
描述	用于调用 VIOS REST API（传感器列表、时间线、片段提取、快照、添加/删除传感器和流）。不用于 VLM 推理或搜索。
开源协议	Apache-2.0 metadata:
版本	“3.2.0” github-url: “https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization” tags: “nvidia blueprint operational”

目的

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

前提条件

在 $HOST_IP 上可访问有效的 VSS 部署（参见 vss-deploy-profile 和 references/）。
NGC 凭据位于 $NGC_CLI_API_KEY 和 $NVIDIA_API_KEY 中，用于任何镜像拉取。
调用方环境中有 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。
不要用 NvStreamer 上传 -> RTSP URL -> VIOS /sensor/add 的交接替换普通的 VIOS MP4 上传请求。

请勿将此技能用于：

关于片段的 VLM 推理或临时视觉问答——使用 vss-ask-video。
跨归档的语义搜索或为搜索摄取视频——使用 vss-search-archive。
录制片段的叙述性摘要——使用 vss-summarize-video。
事件范围或警报窗口报告——使用 vss-generate-video-report 模式 B。
阅读分析指标、事件或警报——使用 vss-query-analytics。

此技能附带的参考合同

此技能随 references/ 包提供了四个参考文件。阅读与当前任务相关的文件：

文件	目的	受众
`references/api-reference.md`	完整的 VIOS REST API 参考（运行时合同）——传感器管理、存储、快照、片段提取、WebRTC 实时/回放、RTSP 代理、录像机、服务配置、服务发现。在调用任何 VIOS API 操作时阅读此文。	操作用户 + 本技能自身
`references/nvstreamer-api-reference.md`	NvStreamer REST API 参考——版本、传感器列表/信息/状态/流、三种上传方法（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://` 错误、VIOS + SDRC 补丁要求）。在编写与 VIOS 作为同级通信的技能、组合新的 VSS 部署或调试字幕管道接线时阅读此文。	技能作者、部署组合者、配对文件维护者
`references/deploy-vios-service.md`	部署合同——启动 VIOS 所需的条件。记录容器镜像和标签（`nvcr.io/nvidia/vss-core/vss-vios-:3.2.0`）、GPU/CPU/内存/存储要求、启动行为 + 健康检查调优、必需的环境变量（特别是 `VST_INSTALL_ADDITIONAL_PACKAGES=true`，因为 libav apt-install 步骤限制上传）、已知部署问题（卷漂移、缺少 libav、来自旧容器的 502）、前提条件、dry-run、验证部署和拆除命令。当 VIOS 未运行且需要独立部署、调试容器启动失败或编写包装 VIOS 的部署技能时阅读此文。*	操作员、部署技能作者

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

此技能主要是 API 客户端，假设 VIOS 已在 VST 入口（默认 http://${HOST_IP}:30888）启动并可达。它本身不部署 VIOS，但当 VIOS 不可达时，它会使用捆绑的部署手册（references/deploy-vios-service.md）协调部署，或移交给完整栈的 /vss-deploy-profile 技能。在做任何工作之前：

探测 VIOS：

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

如果探测失败，则 VIOS 未部署。 提供两条前进路径：

“VIOS 在 http://${HOST_IP}:30888 处不可达——当前没有任何部署正在运行。您有两个选项： (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。特别注意其 § 环境变量 — 上传到字幕路径的必要条件 和 § 已知部署问题 部分——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。
如果探测通过，继续。 VIOS 已启动；以下所有操作都可安全执行。

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

GET /vst/api/v1/sensor/list 和 GET /vst/api/v1/sensor/<sensorId>/streams 可能返回 HTTP 502 Bad Gateway 或陈旧结果，当先前部署中遗留的 *-smc VST 容器在 :30000 / :30888 上赢得 network_mode: host 端口绑定竞争时。补救措施：重新运行 /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 代理运行时上下文可达的 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`（流式端点与 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 与其他微服务的集成和部署问题，分别参见 references/integrate-vios-service.md 和 references/deploy-vios-service.md（每个文件的覆盖范围见上文“参考合同”表）。

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

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

验证 VST 可访问（见设置——可用性检查）：

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

列出传感器以找到 sensorId：

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

获取该传感器的流以找到 streamId（优先 isMain: true）：

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

检查时间线以确认请求范围内存在录制：

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

使用 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 发现 8（/url 变体在 3.2.0 中返回双 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 发现 9 的修复方法。

如果在 /url 变体响应的 imageUrl 或 videoUrl 字段中看到双 http:// 前缀，那是发现 8——在客户端剥离前导 http:// 或切换到二进制直接端点。

示例

示例操作提示：

“列出活动 VIOS 传感器并显示其流状态。”
“将此示例视频上传到 VIOS 并返回生成的流 ID。”
“下载此传感器录制时间线上的两秒片段。”
“使用 NvStreamer 上传文件并检索其生成的 RTSP URL。”

限制

VIOS 操作需要可访问的 VST 后端；当健康探测失败时停止或部署先决条件。
大多数部署不需要认证，但部署可以添加外部认证层。
容器侧路径示例使用 ${VST_CONTAINER_ROOT} 作为 VST 容器内安装根目录的中性占位符。从活动部署中解析后再使用路径示例。
不要在日志或最终响应中打印 API 密钥、承载令牌或生成的凭据。

故障排除

错误：健康探测失败。原因：VIOS 未部署或端点错误。解决方案：遵循部署前提流程或要求正确的 VST 端点。
错误：上传失败并显示 Failed to get media information。原因：libav 包未安装在 VIOS 容器中。解决方案：设置 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 信封变体具有发现 8 的双 http:// 缺陷——避免直到上游修复或使用客户端前缀剥离。
传感器与流 ID： sensorId 标识摄像头；streamId 标识来自该摄像头的特定视频流（一个传感器可以有一个主流和子流）。
识别传感器类型（RTSP vs 上传文件）： 调用 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> 作为占位符——在执行前替换为已解析的端点。