⚡

VSS视频分析API部署Skill vss-setup-video-analytics-api

用于独立部署 vss-video-analytics-api REST 服务，支持用户自定义配置、数据日志绑定、Elasticsearch/Kafka 连接，可无 Kafka 运行。提供 REST 端点查询、动态配置和标定更新等能力。关键词：VSS、视频分析 API、REST 服务、独立部署、Elasticsearch、Kafka

视频智能服务(VSS) 0 次安装 0 次浏览 更新于 9/6/2026
名称 vss-setup-video-analytics-api
描述 用于独立部署 vss-video-analytics-api REST 服务（配置来源、数据日志绑定、Elasticsearch、可选 Kafka）。不用于完整仓库部署。
开源协议 Apache-2.0 metadata:
作者 “NVIDIA 视频搜索与汇总团队”
版本 “3.2.0” github-url: “https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization” tags: “nvidia blueprint operational deployment 视频分析API REST API”

Purpose

独立部署 video-analytics-api REST 服务，使用用户选择的配置、数据日志绑定以及 Elasticsearch / Kafka 连接。

Instructions

按照下面的路由表和分步工作流执行。每个以 workflow、quick start 或 flow 结尾的章节都应从上到下执行。详细参考材料位于 references/。

Examples

已完成的端到端示例保存在 evals/ 下（每个 *.json 清单包含一个可运行的场景）。运行 Tier-3 评估以重放它们：

nv-base validate skills/vss-setup-video-analytics-api --agent-eval

最小的独立启动如下所示：

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data}
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

有关完整工作流（配置来源、数据日志绑定、基础设施依赖、REST 端点），请参阅 references/deploy-video-analytics-api-service.md。有关逐字段 JSON 配置参考，请参阅 references/configuration.md。

Limitations

  • 需要匹配的 VSS profile / 微服务已部署且可从调用方访问。
  • NGC 托管的模型和 NIM 可能受到速率限制、GPU 内存要求和许可限制的约束。
  • 并发、GPU 内存和存储限制取决于主机硬件和 profile 的 compose 文件。

Troubleshooting

  • 错误：REST 调用返回连接被拒绝。原因：目标微服务未运行。解决：探测 /docs 或 /health；通过 vss-deploy-profile 或匹配的 vss-deploy-* 技能重新部署。
  • 错误：NGC 拉取返回 HTTP 401/403。原因：缺少或过期的 NGC_CLI_API_KEY。解决：docker login nvcr.io 并在重试前重新导出该密钥。
  • 错误：容器 OOM 或模型加载失败。原因：所选 profile 的 GPU 内存不足。解决：切换到较小的变体或通过 docker compose down 释放 GPU。

VSS 设置视频分析 API — 独立

仅部署 vss-video-analytics-api 容器（来自上游 video-analytics-api 仓库的 Node.js REST API），不作为完整仓库蓝图堆栈的一部分。

完整的运维演练 — 配置来源选项、数据日志卷行为、基础设施依赖、REST API 端点、部署+验证、故障排除 — 位于 references/deploy-video-analytics-api-service.md。逐字段 JSON 配置参考位于 references/configuration.md。本 SKILL.md 仅处理路由和前置条件。

When to use

  • “部署视频分析 API” / “独立运行 video-analytics-api”
  • “我只想运行 REST API，不想运行完整堆栈”
  • “使用我自己的 video-analytics-api 配置”
  • “将 API 指向不同的 Elasticsearch / Kafka”
  • “在没有 Kafka 的情况下启动 API” / “无代理运行 API”
  • “检查可用的 REST 端点”

Prerequisites

  1. 仓库检出，并将 $VSS_APPS_DIR 指向 <repo>/deploy/docker/。服务 compose 的卷绑定需要此设置。

  2. NGC 凭据 — 设置 $NGC_CLI_API_KEY，以便 docker 能拉取镜像。参见 references/ngc-api-key-registry-login.md。

    关于 NGC_CLI_API_KEY 的安全处理说明：该密钥是长期凭据，可拉取你的 NGC 组织可用的所有 NVIDIA 私有镜像。切勿提交该密钥、切勿粘贴到聊天中、切勿存储在 /tmp 中。在部署时以交互方式读取（read -rs NGC_CLI_API_KEY）或从你的密钥管理器（Vault、AWS Secrets Manager、sealed-secrets）加载。使用 umask 077 + chmod 600 写入任何派生的 .env 文件，将其添加到 .gitignore，并在定义的周期内以及每台主机退役后轮换该密钥。如果它曾被暴露（主机快照、共享屏幕、工单附件），请立即轮换。

  3. Docker 运行时 — Docker Engine 28.3.3，带 Docker Compose 插件 v2.39.1+。使用 docker --version 和 docker compose version 验证。

  4. Elasticsearch — 必须可通过 elasticsearch.node 中配置的 URL 访问。服务器启动时会 ping ES；如果无法访问，它会退出（然后 restart: always 会将其重新拉起）。如果你还需要启动 ES，请使用基础设施 compose：docker compose -f services/infra/compose.yml up -d elasticsearch。

  5. 可选 Kafka broker。API 可以在没有 Kafka 的情况下运行。如果你想要一个安静的无代理部署，请使用镜像内置配置或带有 kafka.brokers: [] 的自定义配置；服务自带的 compose 配置指向 localhost:9092，因此在 broker 可访问之前，依赖 Kafka 的功能（动态配置、动态标定、RTLS/AMR）将失败。

  6. 默认 compose 需要 $VSS_DATA_DIR。基础 compose 将 $VSS_DATA_DIR/data_log/vss_video_analytics_api 绑定挂载，用于 multipart 上传处理和基于文件的资产（如标定图像）。请将目录设置为可写的主机路径并预先创建，或者如果不需要图像上传，则移除该挂载。

如果任何必需的前提条件失败，请先说明差距，然后再继续。

Workflow

将 references/deploy-video-analytics-api-service.md 交给用户，并按顺序引导他们完成其中的步骤：

  1. 选择配置 — 镜像内置默认配置、服务自带配置或自定义配置。
  2. 决定是否需要数据日志卷用于文件上传。
  3. 确认基础设施依赖 — Elasticsearch（必需）、Kafka（可选）。
  4. 通过 docker compose up 和健康检查进行部署+验证。

compose 文件的编辑、配置选项、部署+验证命令、REST API 端点表和故障排除表均在该参考中 — 请勿在此重复。

Endpoint Reference

REST 端点表和运行时依赖说明请使用 references/deploy-video-analytics-api-service.md。

Kafka-dependent features (runtime, requires broker)

一旦容器启动并且 Kafka broker 可访问，就会提供三个额外功能：

Dynamic config

API 充当动态配置更新的生产者。当操作员向 /config 发送 POST 时，API 会向 mdx-notification 主题发布一条 upsert 消息，Kafka key 为 behavior-analytics-config。下游的 behavior-analytics 容器消费该消息并回 ACK。API 还处理引导流程 — 当 behavior-analytics 启动时，它会发布一条 request-config 消息，API 回复包含来自 Elasticsearch 的最新已验证配置的 upsert-all。

消费端验证、ACK 语义和完整的线上契约在 vss-setup-behavior-analytics 动态配置参考中有文档说明。

Dynamic calibration

API 在 mdx-notification 上生成标定更新通知，Kafka key 为 calibration。支持 upsert-all（完整快照）、upsert（按传感器合并）和 delete（按传感器移除）。下游的 behavior-analytics 容器消费这些通知并将其应用到实时标定中。

消费端验证和每个 action 的策略在 vss-setup-behavior-analytics 动态标定参考中有文档说明。

RTLS / AMR

API 从 Kafka 消费实时位置（mdx-rtls）和 AMR（mdx-amr）消息，并通过 REST 端点暴露它们。

Routing rules

  • 如果用户想要“完整堆栈”（UI / agent / perception）：请转交给 vss-deploy-profile，profile 为 warehouse（或 alerts）。不要并行运行本技能。
  • 如果用户想要部署分析流水线（行为创建、事件检测）：请转交给 vss-setup-behavior-analytics。
  • 如果用户想要通过 REST API 发布运行时配置/标定更新：请确认 Kafka 可访问，然后使用 /config 或标定端点，并指向 behavior-analytics 动态更新参考以了解消费者线上契约。
  • 如果用户想从 消费者 侧（behavior-analytics）理解动态配置/动态标定的线上契约：请将他们指向 vss-setup-behavior-analytics 的动态配置和动态标定参考。
  • 如果用户想要查询 REST API 端点或与之交互：部署参考中的端点表涵盖了可用的端点。完整的 OpenAPI 规范请参见 video-analytics-api 仓库中的 src/app/specification/openapi.json。

bump:1