mcpField
V
vss-setup-video-analytics-api

vss-setup-video-analytics-api

github.com/promptingcompany云与 DevOps039 次安装17 周前更新
代码仓库

关于 vss-setup-video-analytics-api

此技能面向配置 VSS 部署的运维人员，用于独立部署 video-analytics-api REST 服务。它涵盖配置、存储、Elasticsearch 与可选 Kafka 的设置，以及部署和健康检查。

主要功能

  1. 01独立 Docker Compose 部署
  2. 02内置、随服务或自定义配置
  3. 03数据日志卷设置
  4. 04Elasticsearch 与可选 Kafka 指引
  5. 05REST 端点与健康检查指引

适用场景

  1. 01不启动完整套件而运行 REST API
  2. 02指定服务使用的 Elasticsearch 或 Kafka
  3. 03使用自定义 API 配置部署
  4. 04检查服务健康状态和可用端点

安装

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

$npx skills add https://github.com/promptingcompany/nv-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