mcpField
V
vss-setup-video-analytics-api

vss-setup-video-analytics-api

github.com/nvidia云与 DevOps3.8k1.8k 次安装今天更新
代码仓库

关于 vss-setup-video-analytics-api

该技能指导独立部署 video-analytics-api REST 服务，并配置其数据日志挂载及 Elasticsearch、Kafka 连接。面向只需运行该 API、而非完整视频分析栈的用户。

主要功能

  1. 01独立部署 REST API 容器
  2. 02选择内置、服务自带或自定义配置
  3. 03配置数据日志卷挂载
  4. 04检查 Elasticsearch 与 Kafka 依赖
  5. 05提供 Kafka 支持的动态配置与校准

适用场景

  1. 01单独启动视频分析 REST API
  2. 02将 API 连接到指定 Elasticsearch
  3. 03无 Kafka 运行 API
  4. 04通过 API 发布配置或校准更新

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nvidia/skills --skill vss-setup-video-analytics-api

安装后在 Claude Code 中输入/vss-setup-video-analytics-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

BENCHMARK.md
skill-card.md
skill.oms.sig
evals/
evals.json
standalone_deploy.json
references/
configuration.md
deploy-video-analytics-api-service.md
ngc-api-key-registry-login.md

详细介绍

用途

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

说明

按照以下路由表和分步工作流操作。每个以 工作流、快速开始 或 流程 结尾的章节都应从上到下依次执行。详细参考资料位于 references/ 中。

示例

端到端示例存放在 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。

限制

  • 需要部署与之匹配的 VSS 配置文件 / 微服务，并确保调用方能够访问。
  • NGC 托管的模型和 NIM 可能受到速率限制、GPU 内存要求和许可证限制。
  • 并发、GPU 内存和存储限制取决于主机硬件以及配置文件的 compose 文件。

故障排除

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

VSS Setup Video Analytics 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 仅处理路由和前置条件。

适用场景

  • “部署 video analytics api” / “独立运行 video-analytics-api”
  • “我只想运行 REST API，而不是完整堆栈”
  • “使用我自己的 video-analytics-api 配置”
  • “将 API 指向其他 Elasticsearch / Kafka”
  • “不使用 Kafka 启动 API” / “无代理运行 API”
  • “查看有哪些 REST 端点可用”

前提条件

  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 也能运行。如果希望部署时不启用 broker，可使用镜像内置配置，或使用设置了 kafka.brokers: [] 的自定义配置；服务随附的 compose 配置指向 localhost:9092，因此依赖 Kafka 的功能（动态配置、动态校准、RTLS/AMR）在 broker 可访问之前会无法运行。

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

如果任何必需的前提条件不满足，请先指出缺失项，再继续操作。

工作流

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

  1. 选择配置 — 镜像内置默认配置、服务随附配置或自定义配置。
  2. 确定文件上传是否需要数据日志卷。
  3. 确认基础设施依赖项 — Elasticsearch（必需）、Kafka（可选）。
  4. 使用 docker compose up 部署并通过运行状况检查验证。

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

端点参考

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

依赖 Kafka 的功能（运行时，需要 broker）

容器启动且 Kafka broker 可访问后，即可使用另外三项功能：

动态配置

API 充当动态配置更新的生产者。操作员向 /config 发送 POST 请求时，API 会向 mdx-notification 主题发布一条带有 Kafka 键 behavior-analytics-config 的 upsert 消息。下游的 behavior-analytics 容器会使用该消息并返回 ACK。API 也会处理引导流程 — behavior-analytics 启动时会发布一条 request-config 消息，API 则会回复一条 upsert-all 消息，其中包含从 Elasticsearch 获取的最新已验证配置。

消费者端验证、ACK 语义和完整的 wire contract 均记录在 vss-setup-behavior-analytics 动态配置参考文档中。

动态校准

API 会在 mdx-notification 上发布校准更新通知，Kafka key 为 calibration。支持 upsert-all（完整快照）、upsert（按传感器合并）和 delete（按传感器移除）。下游 behavior-analytics 容器会接收这些通知，并将其应用到实时校准中。消费者端的验证和各操作策略记录在 vss-setup-behavior-analytics 动态校准参考文档中。

RTLS / AMR

API 会从 Kafka 接收实时位置（mdx-rtls）和 AMR（mdx-amr）消息，并通过 REST 端点提供这些数据。

路由规则

  • 如果用户想要“完整技术栈”（UI / Agent / 感知）：转交给 vss-deploy-profile，并使用配置文件 warehouse（或 alerts）。不要并行运行此技能。
  • 如果用户想要部署分析流水线（行为创建、事件检测）：转交给 vss-setup-behavior-analytics。
  • 如果用户想通过 REST API 发布运行时配置 / 校准更新：确认 Kafka 可访问，然后使用 /config 或校准端点，并引导用户查看行为分析动态更新参考文档中的消费者通信协议。
  • 如果用户想从消费者端（behavior-analytics）了解动态配置 / 动态校准通信协议：引导他们查看 vss-setup-behavior-analytics 的动态配置和动态校准参考文档。
  • 如果用户想查询或调用 REST API 端点：部署参考文档中的端点表列出了可用端点。如需完整的 OpenAPI 规范，请参阅 video-analytics-api 仓库中的 src/app/specification/openapi.json。

bump:1

评论

支持 Markdown